@skyramp/mcp 0.4.1 → 0.4.2-rc.1

package/build/prompts/reuse-hand-off.js

@@ -0,0 +1,130 @@
+/**
+ * The modularize → reuse hand-off, shared by the two places that arm the chain:
+ * generation (TestGenerationService, for the files a codeReuse call wrote) and
+ * maintenance (skyramp_actions, for a test it updates or regenerates). One
+ * predicate decides whether a file owes the pair, and one builder produces the
+ * next-steps text, so the two callers cannot drift on either.
+ */
+import { isUtilsReuseEnabled } from "../utils/featureFlags.js";
+import { fillPlaceholders } from "../recommendation/verifierContracts.js";
+import { readPromptAsset, sectionBody } from "./promptAssets.js";
+import { isBrowserTestType, isModularizeFirstTarget, } from "../utils/reuseRouting.js";
+import { utilsSpecFor, } from "../utils/utils-verify/index.js";
+import { enhanceAssertionsCall } from "../skills/enhanceAssertionsSkill.js";
+/** Why Java generation never asks for codeReuse. */
+const CODE_REUSE_JAVA_REASON = "cross-file helpers do not compile in the test executor";
+/** Why every other unsupported language is left out. Java has its own reason
+ *  above; a language the shared-helper verifier does not cover is left out
+ *  because nothing can check the module it would write. Naming Java's reason for
+ *  a Go or Ruby test would be a false statement about that file. */
+function codeReuseUnverifiableReason(language) {
+    return `the shared-helper verifier has no rules for ${language}`;
+}
+/**
+ * The generation-call clause that asks for codeReuse, language-conditional in
+ * words, as the testbot prompt appends it to its integration generation step
+ * when utils reuse is on.
+ *
+ * States the RULE, not one exception. Naming Java as the only language left out
+ * is false — code reuse covers three languages and discovery records seventeen —
+ * and an agent in a Go repository reads "unset for Java", concludes Go is not
+ * excepted, and asks for a reuse pass that can move no helpers for Go.
+ */
+export const CODE_REUSE_GENERATION_CLAUSE = `, setting \`modularizeCode: false\` and \`codeReuse: true\` for TypeScript, JavaScript and Python, and leaving \`codeReuse\` unset for any other language (for Java, ${CODE_REUSE_JAVA_REASON}; for the rest, ${codeReuseUnverifiableReason("them")})`;
+/**
+ * Whether the maintenance step can actually rewrite a test of this type. Its
+ * REGENERATE strategy names the integration and contract generators only and
+ * forbids skyramp_ui_test_generation, which needs a recorded trace this tool does
+ * not have. A browser test's REGENERATE is therefore advice to the developer: no
+ * call here rewrites the file, so nothing may be armed against it — a hand-off
+ * would refuse the execution of a file the plan never told anyone to rewrite.
+ */
+export function isMaintenanceRegenerable(testType) {
+    return !isBrowserTestType(testType);
+}
+/**
+ * What the regenerate instruction asks of the generation call, as words for the
+ * summary (`clause`) and as the arguments the structured plan carries (`args`),
+ * from one decision. Undefined when the call must not ask for code reuse: utils
+ * reuse off, or a test type that is not a modularize-first target — contract, for
+ * one, whose generator accepts neither `codeReuse` nor `modularizeCode`. For a
+ * modularize-first type: the resolved clause and arguments for a language with a
+ * utils spec; the leave-unset clause and no arguments for Java; the generic clause
+ * and no arguments when the language is not cataloged.
+ */
+export function regenerateCodeReuse(testType, 
+/** Optional because the discovery catalog does not always carry one: an
+ *  uncataloged but real test file is accepted deliberately, and its language is
+ *  unknown. The clause is omitted in that case. */
+language) {
+    if (!isUtilsReuseEnabled())
+        return undefined;
+    if (!isMaintenanceRegenerable(testType))
+        return undefined;
+    if (!isModularizeFirstTarget(testType, language))
+        return undefined;
+    // No cataloged language: nothing records a hand-off for the file and no
+    // arguments are emitted for it, so a clause asking the agent to set
+    // codeReuse: true would ask for a call the structured plan does not — the very
+    // split that carrying the options on the entry closed. Say nothing instead.
+    if (!language)
+        return undefined;
+    return utilsSpecFor(language)
+        ? {
+            clause: ", setting `modularizeCode: false` and `codeReuse: true`",
+            args: { codeReuse: true, modularizeCode: false },
+        }
+        : {
+            clause: `, and leave \`codeReuse\` unset (${language.toLowerCase() === "java" ? CODE_REUSE_JAVA_REASON : codeReuseUnverifiableReason(language)}),`,
+        };
+}
+/**
+ * Whether a test of this type and language owes the modularize → reuse pair.
+ * Routing (isModularizeFirstTarget) says which flows modularize first; the utils
+ * spec says which languages have a payable reuse half — recordReuseHandOff writes
+ * nothing for a language without one (Java), so instructing the pair there would
+ * be a debt nothing tracks.
+ */
+export function isModularizeFirstHandOffTarget(testType, 
+/** Optional because generation's own `language` param is: the predicate is the
+ *  thing that decides an absent or unsupported language owes nothing. */
+language) {
+    return (isModularizeFirstTarget(testType, language) && !!utilsSpecFor(language));
+}
+/** The argument clause of the skyramp_reuse_code call the agent is told to make. */
+export function reuseCodeArgsClause(language, testType, framework) {
+    return `\`testFile\` set to the absolute path of the generated test file, \`language: "${language}"\`, \`testType: "${testType}"\`${framework ? `, and \`framework: "${framework}"\`` : ""}`;
+}
+/**
+ * The CRITICAL NEXT STEPS block: modularize, then reuse (whose returned steps end
+ * in the verify call). `enhanceFirst` prepends the assertion enhancer — browser
+ * tests generated with enhanceAssertions run it on the raw file, before the
+ * selectors move into the utils file. Maintenance never sets it: the update
+ * strategy calls the enhancer after the edit, and the block says the pair runs
+ * before it.
+ */
+const HAND_OFF_MD = readPromptAsset("code-reuse/hand-off.md");
+/** One section of the hand-off markdown, by heading, with its placeholders
+ *  filled. The markdown is the single source of this instruction text. */
+function handOffStep(heading, values) {
+    return fillPlaceholders(sectionBody(HAND_OFF_MD, `## ${heading}`), values);
+}
+export function buildModularizeFirstNextSteps(params) {
+    const { testType, language, framework, enhanceFirst } = params;
+    const enhanceCall = enhanceAssertionsCall(testType, "generated test file");
+    const values = {
+        testType,
+        reuseArgs: reuseCodeArgsClause(language, testType, framework),
+        enhanceCall: enhanceCall.charAt(0).toUpperCase() + enhanceCall.slice(1),
+    };
+    const steps = [
+        ...(enhanceFirst ? [handOffStep("Enhance first", values)] : []),
+        handOffStep("Modularize", values),
+        handOffStep("Reuse", values),
+    ];
+    const ordering = handOffStep(enhanceFirst
+        ? "Ordering with the enhancer"
+        : "Ordering without the enhancer", values);
+    return `⏭️**CRITICAL NEXT STEPS — ${ordering}**:
+${steps.map((text, i) => `${String.fromCharCode(97 + i)}. ${text}`).join("\n")}`;
+}

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

@@ -1,6 +1,70 @@
+/**
+ * Where a test states the status it expects: ONCE, as the argument of the helper
+ * call. The helper asserts it (that is the shared invariant), so the policy has to
+ * say what the spec contains after that — left unsaid, the agent left the status
+ * behind a defaulted parameter the call omitted, or asserted it a second time on the
+ * response the helper returned. Quoted by the prompt and by the two verify findings
+ * (`status-default`, `status-restated`) that enforce it, so the sentence the agent
+ * reads is the sentence the gate returns.
+ */
+export declare const STATUS_ONCE_RULE: {
+    /** Written as the ACTION to take and the helpers it applies to. A first version
+     *  said the parameter "carries NO default" in the present tense; quoted beside a
+     *  finding that showed `expected_status=201`, it read as a description that was
+     *  false about the very line it quoted, and the advisory was acted on 0 of 9 times. */
+    readonly noDefault: "Give every helper THIS RUN WRITES its expected status as a required parameter: no default value, not optional. A call site that can omit the status hides the expectation, so every call site passes the status it expects. A helper that already exists at HEAD keeps the signature it has, default included — never remove an incumbent's default, since callers this run cannot see rely on it; a call site this run writes still passes the status explicitly, whether or not the helper would default it. A helper whose status NEVER varies may assert the literal instead of taking a parameter at all: what this rule forbids is a DEFAULT, which lets a call site silently inherit an expectation it never stated, and a pinned literal no caller can vary hides nothing. Give it a parameter the moment a second call site needs a different status. Declare the expected-status parameter BEFORE any parameter that carries a default: Python refuses `def create_product(client, headers, body=DEFAULT_BODY, expected_status)` with `SyntaxError: non-default argument follows default argument`, and a module that does not import takes every test in the file with it at collection.";
+    readonly notRestated: "the test body does not assert the status again on the response the helper returns — the helper asserted it, and the call's status argument is the one statement of it";
+};
 /** 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";
+/**
+ * What a shared helper of one family may assert — the ONE declaration.
+ *
+ * Every statement of the rule is rendered from here: the prompt sentence the agent
+ * reads, the per-language predicate the verify pass runs, and the violation message
+ * the gate returns. They disagreed before — the prompt permitted one matcher, the
+ * gate accepted eight, and the message repeated the gate's reading — so a value
+ * assertion could sit in a delivered helper, pass the gate and reach the customer
+ * with nothing reported. Widening or narrowing a family is an edit to one array.
+ *
+ * The api family's permitted assertion is not a matcher list (it is a status-code
+ * comparison whose RECEIVER decides: `expect(res.status)` yes, `expect(res.body.status)`
+ * no), so `permittedMatchers` is empty for it and its predicate stays hand-written.
+ * Stating its list here is what SKYR-4318 does; it edits this table, and the gate
+ * reads the table, so no second mechanism is needed for it.
+ */
+export interface HelperAssertionPolicy {
+    /** Matcher names permitted inside a shared helper, in the camelCase spelling.
+     *  Empty when the family's rule is not expressible as a matcher list. */
+    permittedMatchers: readonly string[];
+    /** Matchers the family refuses. Named rather than implied: the boundary reads as
+     *  a rule the agent can apply, not as a list it must invert. */
+    refusedMatchers: readonly string[];
+    /** The sentence that states the boundary, quoted VERBATIM by the prompt and by the
+     *  gate's violation message. One string, so a reader who follows the message and a
+     *  reader who follows the prompt are told the same thing. */
+    boundary: string;
+}
+/**
+ * ARIA roles whose accessible name is the page's own CONTENT rather than a control's
+ * label. A locator built from one of these plus a name selects by what the page SAYS,
+ * which is the scenario's data: `getByRole("heading", { name: "Your cart is empty!" })`
+ * is the scenario's outcome wearing a structural locator.
+ *
+ * A DENY-list, not an allow-list. The rule blocks a customer's run, so a role nobody
+ * has listed has to pass — an allow-list refused `getByRole("dialog", { name })`, which
+ * is an ordinary wait for a named modal and is permitted everywhere else.
+ */
+export declare const CONTENT_ROLES: readonly ["heading", "paragraph", "cell", "gridcell", "columnheader", "rowheader", "row", "listitem", "definition", "term", "img", "figure", "article", "note", "tooltip", "alert", "log", "marquee", "timer", "blockquote", "caption", "option", "menuitem", "menuitemcheckbox", "menuitemradio", "treeitem"];
+/** Spoken once, quoted everywhere. */
+export declare const BROWSER_ASSERTION_BOUNDARY: string;
+export declare const HELPER_ASSERTION_POLICIES: Record<"api" | "browser", HelperAssertionPolicy>;
+/** The WAIT FORMS a shared browser helper may use. It deliberately stops short of
+ *  what a structural locator is: the boundary states that, once, and this clause is
+ *  rendered beside it. A second summary of the locator rule was a second rule to keep
+ *  equal, and it fell behind the boundary the first time the boundary gained an
+ *  exception. */
+export declare const BROWSER_STRUCTURAL_WAITS: string;
 /**
  * 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
@@ -9,7 +73,13 @@ export declare const BROWSER_STRUCTURAL_WAITS = "`waitForResponse`, `waitForLoad
  */
 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\")`";
+export declare const BROWSER_VALUE_ASSERTIONS: string;
+/**
+ * What qualifies as a browser reuse target — stated once, read by the page-object
+ * prompt and by the in-house search on the shared-module path, so the two cannot
+ * disagree about which of the customer's modules the run may call.
+ */
+export declare const SELECTOR_OWNING_MODULE_RULE = "**A reuse target does not have to be a class.** Selector-owning helper libraries qualify \u2014 modules exporting free functions like `bookFirstEvent(page)` whose bodies contain the selector literals. A helper module qualifies only if its functions OWN selectors; a module whose functions take selectors as parameters (generic interaction utilities) owns nothing and is not a reuse target. Playwright fixture factories wired into the repo's own `test` object (`test.extend`-style) are NOT substitutable either \u2014 using them requires replacing the Skyramp runtime imports, which is forbidden.";
 /**
  * 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
@@ -43,6 +113,22 @@ export interface HelperPolicy {
     namingExample: string;
     /** "One X = one helper" closing line for a utils file. */
     oneHelperRule: (fileName: string) => string;
+    /**
+     * What may carry a difference in WHAT THE STEP SENDS between two call sites of
+     * one operation — the request body for API helpers; for browser helpers, why
+     * the question does not arise. Stated once here because both ends of the
+     * modularize -> reuse chain decide it: modularization shapes the helper, reuse
+     * merges a second caller into it, and a helper shaped so it cannot carry the
+     * second caller sends that caller off to write its own copy.
+     */
+    bodyShapeRule: string;
+    /**
+     * How the request's options object is built in a language that types it — one
+     * literal at the call, optional fields inline. Empty when the kind issues no
+     * request (browser helpers). Rendered beside `bodyShapeRule` at both ends of
+     * the chain for the same reason it is.
+     */
+    optionsShapeRule: string;
     /** Kind-specific near-duplicate / merge section for STEP 4b of code reuse. */
     nearDupRules: (fileName: string) => string;
     /**

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

@@ -14,9 +14,104 @@
  *   values / literal arguments, the helper holds actions + structural waits.
  */
 import { isBrowserTestType } from "../utils/reuseRouting.js";
+/**
+ * Where a test states the status it expects: ONCE, as the argument of the helper
+ * call. The helper asserts it (that is the shared invariant), so the policy has to
+ * say what the spec contains after that — left unsaid, the agent left the status
+ * behind a defaulted parameter the call omitted, or asserted it a second time on the
+ * response the helper returned. Quoted by the prompt and by the two verify findings
+ * (`status-default`, `status-restated`) that enforce it, so the sentence the agent
+ * reads is the sentence the gate returns.
+ */
+export const STATUS_ONCE_RULE = {
+    /** Written as the ACTION to take and the helpers it applies to. A first version
+     *  said the parameter "carries NO default" in the present tense; quoted beside a
+     *  finding that showed `expected_status=201`, it read as a description that was
+     *  false about the very line it quoted, and the advisory was acted on 0 of 9 times. */
+    noDefault: "Give every helper THIS RUN WRITES its expected status as a required parameter: no default value, not optional. A call site that can omit the status hides the expectation, so every call site passes the status it expects. A helper that already exists at HEAD keeps the signature it has, default included — never remove an incumbent's default, since callers this run cannot see rely on it; a call site this run writes still passes the status explicitly, whether or not the helper would default it. A helper whose status NEVER varies may assert the literal instead of taking a parameter at all: what this rule forbids is a DEFAULT, which lets a call site silently inherit an expectation it never stated, and a pinned literal no caller can vary hides nothing. Give it a parameter the moment a second call site needs a different status. Declare the expected-status parameter BEFORE any parameter that carries a default: Python refuses `def create_product(client, headers, body=DEFAULT_BODY, expected_status)` with `SyntaxError: non-default argument follows default argument`, and a module that does not import takes every test in the file with it at collection.",
+    notRestated: "the test body does not assert the status again on the response the helper returns — the helper asserted it, and the call's status argument is the one statement of it",
+};
 /** 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';
+/** Playwright matchers that answer "did this element render" — the browser analogue
+ *  of a structural wait. `.not` forms included: `not.toBeVisible` is the same claim. */
+const BROWSER_PRESENCE_MATCHERS = [
+    "toBeVisible",
+    "toBeHidden",
+    "toBeAttached",
+];
+/** Matchers that answer what STATE an element is in. Not a structural wait: a button
+ *  is enabled in one scenario and disabled in the next, so the claim belongs to the
+ *  scenario and not to the shared step. Playwright's own actionability checks already
+ *  wait for Enabled before `click()` and for Editable before `fill()`, so a helper
+ *  loses no readiness by leaving these out. */
+const BROWSER_STATE_MATCHERS = [
+    "toBeEnabled",
+    "toBeDisabled",
+    "toBeEditable",
+    "toBeFocused",
+    "toBeInViewport",
+];
+/**
+ * ARIA roles whose accessible name is the page's own CONTENT rather than a control's
+ * label. A locator built from one of these plus a name selects by what the page SAYS,
+ * which is the scenario's data: `getByRole("heading", { name: "Your cart is empty!" })`
+ * is the scenario's outcome wearing a structural locator.
+ *
+ * A DENY-list, not an allow-list. The rule blocks a customer's run, so a role nobody
+ * has listed has to pass — an allow-list refused `getByRole("dialog", { name })`, which
+ * is an ordinary wait for a named modal and is permitted everywhere else.
+ */
+export const CONTENT_ROLES = [
+    "heading",
+    "paragraph",
+    "cell",
+    "gridcell",
+    "columnheader",
+    "rowheader",
+    "row",
+    "listitem",
+    "definition",
+    "term",
+    "img",
+    "figure",
+    "article",
+    "note",
+    "tooltip",
+    "alert",
+    "log",
+    "marquee",
+    "timer",
+    "blockquote",
+    "caption",
+    // A row of data, a list entry or a menu entry is named by what it shows.
+    "option",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "treeitem",
+];
+const list = (names) => names.map((n) => `\`${n}\``).join(", ");
+/** Spoken once, quoted everywhere. */
+export const BROWSER_ASSERTION_BOUNDARY = `a shared browser helper holds actions and structural waits only — a check that an element RENDERED (${list(BROWSER_PRESENCE_MATCHERS)}, negated or not — \`.not.toBeVisible()\` in TypeScript, \`not_to_be_visible()\` in Python, which has no \`.not\` to chain through) on a STRUCTURAL locator: a test id, a CSS selector, a label, or a role + name — any role EXCEPT one that names the page's own content (${list(CONTENT_ROLES)}), whose name is the scenario's data rather than a label. A check of element STATE (${list(BROWSER_STATE_MATCHERS)}) is a value assertion, not a wait — it says what the element IS, which the next scenario calling the helper may need to be the opposite of, and \`click()\` and \`fill()\` already wait for the element to be enabled and editable. A matcher on a locator that selects by RENDERED TEXT (\`getByText(...)\`, \`filter({ hasText: ... })\`, or a role + name where the role names CONTENT rather than a control, such as \`getByRole("heading", { name: "Your cart is empty!" })\` or \`getByRole("option", { name: "Order deleted" })\`) is a value assertion too, whether or not the text holds a digit. A digit inside a STRUCTURAL selector — \`locator("h1")\`, \`getByTestId("step-2-panel")\`, \`getByLabel("Address line 1")\` — is not scenario data and is permitted. Two exceptions, because a digit THERE is the scenario's own value: a role name that carries one (\`getByRole("button", { name: "Add 2 items" })\`), and a test id built out of a row rather than written as a name (\`getByTestId("order-def@mail.com - 2 items")\`). The verify pass reports only the locator forms it can recognise as text-selecting, so a locator it does not know passes — write to the rule, not to what the check happens to catch`;
+export const HELPER_ASSERTION_POLICIES = {
+    api: {
+        permittedMatchers: [],
+        refusedMatchers: [],
+        boundary: "a shared API helper asserts only the status code; move this assertion to the test body, applied to the response the helper returns",
+    },
+    browser: {
+        permittedMatchers: BROWSER_PRESENCE_MATCHERS,
+        refusedMatchers: BROWSER_STATE_MATCHERS,
+        boundary: BROWSER_ASSERTION_BOUNDARY,
+    },
+};
+/** The WAIT FORMS a shared browser helper may use. It deliberately stops short of
+ *  what a structural locator is: the boundary states that, once, and this clause is
+ *  rendered beside it. A second summary of the locator rule was a second rule to keep
+ *  equal, and it fell behind the boundary the first time the boundary gained an
+ *  exception. */
+export const BROWSER_STRUCTURAL_WAITS = `\`waitForResponse\`, \`waitForLoadState\`, \`waitFor({ state: "visible" })\`, and ${list(BROWSER_PRESENCE_MATCHERS)} on a STRUCTURAL locator as the boundary below defines one — a check that an element rendered, not what it says or what state it is in`;
 /**
  * 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
@@ -25,15 +120,43 @@ export const BROWSER_STRUCTURAL_WAITS = '`waitForResponse`, `waitForLoadState`,
  */
 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")`';
+export const BROWSER_VALUE_ASSERTIONS = `any \`expect\` whose matcher OR locator carries scenario data: \`toHaveText\`, \`toContainText\`, \`toHaveValue\`, \`toHaveCount\`, \`toHaveURL\` with a literal, every element-STATE matcher (${list(BROWSER_STATE_MATCHERS)}), or ANY matcher — \`toBeVisible\` included — on a locator that selects by rendered text, such as \`getByText("Total: $899.98")\`, \`getByText("Order deleted")\` or \`getByRole("heading", { name: "Your cart is empty!" })\``;
 const BROWSER_LIFTABLE = "fill values, option labels, or literal arguments";
-const API_LIFTABLE = "body literals, `data_override` values, or expected status";
+const BROWSER_BODY_SHAPE_RULE = `**A BROWSER HELPER HAS NO REQUEST BODY, SO IT HAS NOTHING ELSE TO LIFT.** What it sends is the sequence of fills and clicks it performs, and every value in that sequence is already a liftable difference under the rule above (${BROWSER_LIFTABLE}). There is no second thing the helper holds that a caller might need to replace, so the body rule the API helpers carry has no counterpart here.`;
+const API_LIFTABLE = "the request body (literals inside it, or the body as a whole), the query parameters it sends, `data_override` values, or expected status";
+const API_BODY_SHAPE_RULE = `**WHAT A CALLER NEEDS TO CHANGE ABOUT THE REQUEST BODY MUST BE REACHABLE FROM THE HELPER'S SIGNATURE.** A helper is shared, and the next caller of the same method+path rarely sends the same body. Whatever a caller needs to change is a PARAMETER, defaulted to what the helper sends today so existing call sites stay valid unchanged. Two forms are acceptable; take the FIRST one that reaches everything the callers need:
+1. **One parameter per differing value, applied through \`data_override\`** — each defaulted to the literal the helper sends today, applied through the request's \`data_override\` map rather than edited into the body string. Use it whenever every caller's body differs only in the VALUE at a path the generated body already carries. It is the additive form: a caller passes only what it changes, and the body string stays as generated.
+2. **One parameter carrying the whole body** — defaulted to the body the helper sends today and passed straight to the request. Python: \`def update_order(client, headers, order_id, body=DEFAULT_ORDER_BODY)\` calling \`send_request(..., body=body)\`; TypeScript/JavaScript: \`updateOrder(client, orderId, body = DEFAULT_ORDER_BODY)\` calling \`sendRequest({ ..., body })\`. Use it when a caller needs a body \`data_override\` cannot express: a field the generated body does not carry, a field left out, or a different array shape.
+
+A module-level constant is the right home for that default, because the parameter falls back to it and any caller can pass another body instead.
+
+**TAKE ONE FORM, NEVER BOTH.** A helper that carries a whole-body parameter AND a general override parameter passed straight to the request reaches the same body twice: the body parameter already reaches every property the override could, so the second one changes nothing the first cannot, and nothing decides whether to write it. That is how one run wrote \`create_order(client, headers, expected_status, body=DEFAULT_ORDER_BODY, data_override=None)\` and the next wrote the same helper for the same route without the override. One mechanism per helper. (An override that BUILDS a map out of named parameters — \`data_override={"name": unique_suffix(name)}\` — is form 1 working, and is not this.)
+
+**CHANGE FORM WHEN THE CALLERS OUTGROW IT.** Form 1 reaches the values the generated body already carries and nothing else. The moment a caller needs a body form 1 cannot reach, move to form 2. The shapes named above are the ones seen so far, not the whole set — judge by whether the caller can be carried, not by whether it matches one of them. Leaving it on form 1 is what sends that caller off to write its own helper for the same method+path, which is the duplication this file exists to remove, re-created one directory away.
+
+**A BODY NO PARAMETER REACHES AT ALL IS NEVER ACCEPTABLE.** That includes a module-level constant the helper reads DIRECTLY, with no parameter standing in front of it: it is one body, and no caller can send another. Put the current body in the parameter's default, never in a value the parameter cannot stand in for.`;
+/**
+ * TypeScript only in effect (Python passes keyword arguments; there is no options
+ * object to build). The SDK types `sendRequest`'s argument, and a value built as a
+ * record has lost that type by the time it is passed: `TS2345 … missing url, path,
+ * method from SendRequestV2Options`. The executor transpiles without typechecking, so
+ * the run reports success and the customer's own `tsc` is the first to see it. The
+ * verify pass now compiles the delivered files; this is the same rule where the
+ * helper is authored, so it is written right the first time.
+ */
+const API_OPTIONS_SHAPE_RULE = `**THE REQUEST OPTIONS ARE ONE OBJECT LITERAL, WRITTEN AT THE CALL.** TypeScript/JavaScript: pass \`sendRequest\` a single object literal — \`client.sendRequest({ url, path, method, headers, queryParams: query })\` — with every optional field written INLINE. A query that some callers send and others do not is a parameter defaulted to an empty map — \`query = {}\` in JavaScript; in TypeScript typed by what \`sendRequest\`'s \`queryParams\` accepts (a map of \`string | number | boolean | object | null\`, so \`query: Record<string, string | string[]> = {}\` where a key may repeat); an empty map is the same request as sending none — and passed as \`queryParams: query\`; a field that must be genuinely absent is a conditional spread inside the literal (\`...(filter ? { queryParams: { filter } } : {})\`). NEVER declare the options as \`Record<string, unknown>\` (or an untyped \`{}\`) and add fields to it afterwards: the record has no \`url\`, \`path\` or \`method\` the compiler can see, so \`sendRequest(options)\` fails the customer's typecheck even though the executor runs it. TypeScript only, the same discipline applies to every parameter's type: annotate each with the type the SDK call accepts (\`client: SkyrampClient\`, \`headers: Record<string, string>\`, a path or query value as \`string | number\`) — never \`unknown\`, which is assignable to nothing but itself and fails at its first use, and never \`any\`.`;
 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}\`.`;
 }
+/**
+ * What qualifies as a browser reuse target — stated once, read by the page-object
+ * prompt and by the in-house search on the shared-module path, so the two cannot
+ * disagree about which of the customer's modules the run may call.
+ */
+export const SELECTOR_OWNING_MODULE_RULE = `**A reuse target does not have to be a class.** Selector-owning helper libraries qualify — modules exporting free functions like \`bookFirstEvent(page)\` whose bodies contain the selector literals. A helper module qualifies only if its functions OWN selectors; a module whose functions take selectors as parameters (generic interaction utilities) owns nothing and is not a reuse target. Playwright fixture factories wired into the repo's own \`test\` object (\`test.extend\`-style) are NOT substitutable either — using them requires replacing the Skyramp runtime imports, which is forbidden.`;
 /**
  * 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
@@ -46,7 +169,7 @@ export const API_HELPERS = {
     liftableLiterals: API_LIFTABLE,
     structuralNoise: "",
     namingRule: "**NAME** each helper by method + resource ONLY, written in the naming convention of the language it is emitted in — Python `create_product`, `update_order`, `get_order`, `get_orders_list`; TypeScript/JavaScript `createProduct`, `updateOrder`, `getOrder`, `getOrdersList`. Match the surrounding test file: snake_case helpers in a camelCase TS suite read as foreign code the repo did not write. Scenario adjectives in names are FORBIDDEN (`create_discount_test_product`, `updateOrder50Discount`) — 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}`,
+    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)\`). ${STATUS_ONCE_RULE.noDefault} (\`create_order(client, headers, body, 201)\`, never \`expected_status=201\` in a signature this run writes — a helper named for the happy path that defaults to a rejection reads as a bug on sight, and \`None\` is a default too.) In turn, ${STATUS_ONCE_RULE.notRestated}. 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` (Python) / `updateOrder` (TypeScript), not `update_order_discount` or `updateOrder50Discount`.",
@@ -54,6 +177,8 @@ export const API_HELPERS = {
     // 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: () => "",
+    bodyShapeRule: API_BODY_SHAPE_RULE,
+    optionsShapeRule: API_OPTIONS_SHAPE_RULE,
     // 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
@@ -65,25 +190,30 @@ For helpers that wrap one SDK request call (e.g. \`client.send_request(...)\`),
 
 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.
+3. **Differences are limited to**: the request body — literals inside it, or the body as a whole — the query parameters it sends, 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):
+Merge procedure for an API near-duplicate pair — these rules OVERRIDE the generic procedure below on two points: what the request SENDS — its body and its query — IS a liftable difference, and defaults are REQUIRED for every lifted value except the expected status (the generic "no defaults" rule applies to Playwright helpers only; the expected status is the one API parameter that never has one):
 - **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.
+- **Union the parameter lists**; a parameter one version lacked gets the default from that version's literal. The expected status is the exception. ${STATUS_ONCE_RULE.noDefault} Merging two versions this run wrote that expected different statuses means each call site passes its own — and a call site's own status assertion, if it wrote one beside the call, is deleted (${STATUS_ONCE_RULE.notRestated}).
+- **A differing query lifts the same way**: the query map is a parameter, defaulted to the map the incumbent sends — an EMPTY map where it sends none, which is the same request, so a helper that omits the query keeps omitting it for every existing caller. Where both versions send the same keys and only the values differ, one parameter per differing value is enough.
 - **Assertions**: ${API_ASSERTION_MERGE_LINE}
-- Structural differences (different items-array shape, extra request) → NOT near-duplicates; leave them alone.
+- Structural differences (an extra request, a different method or path, an extra step) → NOT near-duplicates; leave them alone. What the request SENDS is not structure, whatever form the difference takes: a body that differs is a body difference, and a query that differs is a query difference. A parameter carries each of them; a second helper carries neither.
+
+${API_BODY_SHAPE_RULE}
 
-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")}
+${API_OPTIONS_SHAPE_RULE}
+
+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, expected_status, discount_percent=25, quantity=2)\` that applies \`discount_percent\` and \`quantity\` via \`data_override\` — the expected status required and declared before the defaulted parameters, per the assertion rule above. ${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, so merge them; keep the body WITHOUT the `waitForTimeout` lines. A fixed sleep is not a structural wait: it is the one line of the pair that carries no meaning, and in a shared helper every importer pays it on every run. Where a step genuinely needs to wait, wait on the element the next line touches (`toBeVisible`, `toBeEnabled`)",
+    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, so merge them; keep the body WITHOUT the `waitForTimeout` lines. A fixed sleep is not a structural wait: it is the one line of the pair that carries no meaning, and in a shared helper every importer pays it on every run. Where a step genuinely needs to wait, wait on the element the next line touches (`toBeVisible`, or `waitFor({ state: "visible" })`) — never on its state (`toBeEnabled`), which is a scenario\'s claim and which `click()` and `fill()` already wait for',
     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}`,
+    assertionRule: `**A SHARED HELPER CONTAINS ACTIONS AND STRUCTURAL WAITS ONLY**: clicks, fills, selects, ${BROWSER_STRUCTURAL_WAITS}. Stated once, exactly as the verify pass states it: ${BROWSER_ASSERTION_BOUNDARY}. 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`.",
@@ -116,6 +246,8 @@ export async function applyDiscount(page: Page, discountPercent: string) {
 \`\`\`
 
 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.`,
+    bodyShapeRule: BROWSER_BODY_SHAPE_RULE,
+    optionsShapeRule: "",
     // 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
@@ -127,6 +259,8 @@ For this flow the rules below OVERRIDE two points of the generic text above and
 - **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}
+
+${BROWSER_BODY_SHAPE_RULE}
 `,
 };
 /** Which helper policy a test type's helpers follow. */

package/build/prompts/sut-setup/modes/adaptWorkflowPrompt.js

@@ -152,7 +152,7 @@ const _adaptPlan = new PromptPlan()
     .subStep("RECORD_CONTRACT", "Record the run contract in workspace.yml", buildRecordTestContractBody)
     .step("VERIFY", "Verify", () => "")
     .subStep("COMMON_ERRORS", "Common SUT errors", () => buildCommonSutErrorsSection())
-    .subStep("LOCAL_VALIDATION", "Local validation", () => buildLocalValidationSection())
+    .subStep("LOCAL_VALIDATION", "Local validation", (args) => buildLocalValidationSection(args))
     .done();
 // ── Goal section (static prose above the plan) ────────────────────────────────
 function buildGoalSection(args) {

package/build/prompts/sut-setup/modes/dockerComposePrompt.js

@@ -287,7 +287,7 @@ const _composePlan = new PromptPlan()
     .subStep("APPLY", "Apply the chosen strategy", buildApplyStrategyBody)
     .step("VERIFY", "Verify", () => "")
     .subStep("COMMON_ERRORS", "Common SUT errors", () => buildCommonSutErrorsSection())
-    .subStep("LOCAL_VALIDATION", "Local validation", () => buildLocalValidationSection())
+    .subStep("LOCAL_VALIDATION", "Local validation", (args) => buildLocalValidationSection(args))
     .done();
 export function getDockerComposePrompt(args) {
     const composeFile = args.sutSourceDockerComposeFile?.trim();

package/build/prompts/sut-setup/shared.d.ts

@@ -10,6 +10,9 @@ export declare enum SutSetupMode {
 }
 export interface SutPromptArgs {
     repositoryPath: string;
+    /** `owner/repo` of the checkout at repositoryPath. The canary calls
+     *  skyramp_run_existing_tests, which names its repository on every call. */
+    repository: string;
     sutSetupMode: string;
     sutSourceWorkflowFile: string;
     sutSourceDockerComposeFile: string;
@@ -41,7 +44,7 @@ export declare function buildSeedDataDiscoverySection(): string;
  * generated `.skyramp/sut/*` files.
  */
 export declare function buildWorkspaceInitSection(): string;
-export declare function buildLocalValidationSection(): string;
+export declare function buildLocalValidationSection(args: SutPromptArgs): string;
 /**
  * Returns the canonical "add to the Testbot workflow" block: every input that
  * controls the SUT lifecycle, auth, and workflow-level setup, followed by the

package/build/prompts/sut-setup/shared.js

@@ -82,7 +82,7 @@ export function buildWorkspaceInitSection() {
 
 Later steps in this SUT bootstrap run write \`.skyramp/sut/*\` files alongside the workspace file. If you need to update per-service \`runtimeDetails.serverStartCommand\` to match the new SUT files, call \`skyramp_init_workspace\` again (see its tool description for the edit-mode / \`force\` contract) rather than editing \`.skyramp/workspace.yml\` directly.`;
 }
-export function buildLocalValidationSection() {
+export function buildLocalValidationSection(args) {
     return `Before reporting success, exercise the adapted workflow locally. Testbot's external fix loop only retries when SUT lifecycle commands are set on the Testbot action. When the SUT is brought up by surrounding GHA steps (skipTargetSetup: 'true'), the fix loop is skipped — so the local check below is the only safety net before the workflow is committed.
 Run commands one at a time in your shell — individual execution pinpoints failures far faster than running the whole workflow at once. For any setup, build, or lifecycle command, a non-zero exit is a fix-needed signal: adjust the workflow, re-run the failing command, and do not proceed until it passes. (The suite canary in step 4 is the one exception — judge it on whether the test executes, not on its pass/fail result.)
 1. Validate build scripts and helper programs first — run these before anything else so build and auth failures surface cheaply:
@@ -95,7 +95,7 @@ Run commands one at a time in your shell — individual execution pinpoints fail
 3. Validate the SUT lifecycle comes up — choose the branch that matches the chosen pattern:
    a. If lifecycle commands are set on the Testbot action (skipTargetSetup is unset): run \`targetSetupCommand\` (confirm exit 0), then poll \`targetReadyCheckCommand\` until it exits 0 within \`targetReadyCheckTimeout\` seconds.
    b. If GHA steps wrap the Testbot action (skipTargetSetup: 'true'): the SETUP steps you ran in step 2 already brought the SUT up, so just poll \`targetReadyCheckCommand\` until it exits 0.
-4. Canary the repository's own suite(s) — do this only when a suite was recorded (a \`testSuites\` entry under a service's \`runtimeDetails\` in \`workspace.yml\`); skip it when none was recorded. With the SUT still running from step 3 and before teardown, call **\`skyramp_run_existing_tests\`** with \`workspacePath\` and \`testSelectors\` — one real test FILE per recorded suite. Do NOT canary by running the suite's command in your shell. **Maintenance runs every suite through this tool, so it is the only thing that proves what maintenance will actually be able to do**: a shell command you drove by hand can succeed while the same suite is unrunnable through the tool, and then the failure surfaces on a customer's first PR instead of here. It also resolves each selector to its owning suite via \`pathGlobs\`, so one call checks your routing too, and it appends the reporter flag and selector itself — you do not hand-build those.
+4. Canary the repository's own suite(s) — do this only when a suite was recorded (a \`testSuites\` entry under a service's \`runtimeDetails\` in \`workspace.yml\`); skip it when none was recorded. With the SUT still running from step 3 and before teardown, call **\`skyramp_run_existing_tests\`** with \`workspacePath\`, \`testSelectors\` — one real test FILE per recorded suite — and \`repository\`: "${args.repository}". Pass no \`stateFile\`: the canary runs before any analysis, so it writes no run state. Do NOT canary by running the suite's command in your shell. **Maintenance runs every suite through this tool, so it is the only thing that proves what maintenance will actually be able to do**: a shell command you drove by hand can succeed while the same suite is unrunnable through the tool, and then the failure surfaces on a customer's first PR instead of here. It also resolves each selector to its owning suite via \`pathGlobs\`, so one call checks your routing too, and it appends the reporter flag and selector itself — you do not hand-build those.
    - Cover **every** suite in \`runtimeDetails.testSuites\`, not a subset you choose: do not rank them or trim by cost. A suite that spawns its OWN app instances (per-worker containers via its own orchestration) belongs in the set like any other — it depends entirely on your provisioning, so its weight is a reason to run it, never a reason to defer it. HTTP readiness only shows the app answers; one real test per suite is what proves each suite's environment is present — its browser, the built e2e image, dev/test dependencies, and base-URL wiring.
    - Read the result per suite: \`summary.ran > 0\` is the suite executing. \`environmentHealthy: false\` or \`skipped: true\` means it did not — \`healthDetail\`/\`skipReason\` says why, and that text is what belongs in the suite's \`canaryDetail\`.
    - A suite that executed and then FAILED its assertions is fine — the environment is runnable, so proceed. A suite that did not execute is the fix-needed signal — the exit criteria below say what you must fix and when you are allowed to stop trying. Never edit, skip, or delete the repo's tests to force a pass; that is out of scope for setup.

package/build/prompts/test-maintenance/actionsInstructions.d.ts

@@ -1,10 +1,4 @@
-/**
- * Prompt language for skyramp_actions output — the LLM_INSTRUCTIONS block
- * emitted to the agent that applies UPDATE, REGENERATE, and DELETE actions.
- *
- * Kept separate from actionsTool.ts so prompt text is co-located with other
- * maintenance prompts and can be reviewed/edited without touching tool logic.
- */
+import { TestType } from "../../types/TestTypes.js";
 export interface RenameEntry {
     oldPath: string;
     newPath: string;
@@ -14,12 +8,17 @@ export interface RenameEntry {
 export declare function buildRenameStrategy(): string;
 /** Strategy string for file renames after path substitution. */
 export declare function buildFileRenameStrategy(): string;
-/** Strategy string for in-place UPDATE edits. */
-export declare function buildUpdateStrategy(): string;
+/** Strategy string for in-place UPDATE edits. `withPostEditSteps` is set when at
+ *  least one update_context entry carries post_edit_steps — the modularize → reuse
+ *  pair an updated test owes, which skyramp_execute_test refuses the file without. */
+export declare function buildUpdateStrategy(withPostEditSteps?: boolean): string;
 /** Strategy string for UPDATE entries that refresh visual-snapshot baselines (SKYR-4298). */
 export declare function buildRebaselineStrategy(): string;
-/** Strategy string for REGENERATE — call generation tool to overwrite the file. */
-export declare function buildRegenerateStrategy(): string;
+/** Strategy string for REGENERATE — call generation tool to overwrite the file.
+ *  `withGenerationArgs` is set when at least one regenerate_context entry carries
+ *  generation_args — the codeReuse options that arm the modularize → reuse chain the
+ *  regenerated file owes. */
+export declare function buildRegenerateStrategy(withGenerationArgs?: boolean): string;
 /** Strategy string for DELETE — remove obsolete test files whose covered endpoints/UI no longer exist. */
 export declare function buildDeleteStrategy(): string;
 /** Per-file instruction block for a single UPDATE recommendation. */
@@ -31,6 +30,9 @@ export declare function buildUpdateFileInstruction(params: {
     rationale?: string;
     /** Visual baselines to refresh at final execution instead of editing (SKYR-4298). */
     rebaselineSnapshots?: string[];
+    /** The modularize → reuse next-steps block for a test that owes the pair; closes
+     *  the file's instruction so the edit comes first. */
+    postEditSteps?: string;
 }): string;
 /** Per-file instruction block for a single REGENERATE recommendation. */
 export declare function buildRegenerateFileInstruction(params: {
@@ -38,4 +40,10 @@ export declare function buildRegenerateFileInstruction(params: {
     updateInstructions?: string;
     outputDir: string;
     outputFile: string;
+    /** The recommendation's test type, normalized to the catalog's where the catalog
+     *  has one, so the clause and regenerate_context[].generation_args agree. */
+    testType: TestType;
+    /** The cataloged language. Optional because the catalog does not always carry
+     *  one: an uncataloged but real test file is accepted deliberately. */
+    language?: string;
 }): string;