@skyramp/mcp 0.4.1 → 0.4.2-rc.2

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,44 @@ 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_SAME_STEP = "the SAME action sequence (same Playwright primitives in the same order, selectors identical)";
+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 +170,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 +178,21 @@ 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,
+    inlineSite: {
+        noun: "inline request block",
+        nouns: "Inline request blocks",
+        unit: "block",
+        stepNoun: "request step",
+        extendClause: " — or, for API request helpers, by EXTENDING them with defaulted parameters as the rules below allow",
+        match: (fileName) => `whose method+path matches a helper now defined in \`${fileName}\``,
+        target: (fileName) => `CALLS TO \`${fileName}\``,
+        lift: (fileName) => `lift a literal the helper lacks to a defaulted parameter in \`${fileName}\``,
+        keeps: "its other steps, assertions and order stay verbatim",
+        afterSteps: "",
+    },
+    inlineCallSiteRule: `**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 ${API_LIFTABLE}): REPLACE the block with a call to the helper, passing the block's own literals as arguments — the status its assertion expected becomes the call's status argument, and that assertion is DELETED, not kept beside the call (the helper asserts it) — and lift anything the helper does not yet take — the block's BODY and the query parameters it sends included, not only the scalars inside them — to a parameter DEFAULTED to the helper's current value, so every existing call site sends what it sent before. The expected status is the one exception to that default: a helper that pins a literal status lifts it to a parameter with NO default, and every existing call site of that helper is updated to pass the literal it pinned. 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.`,
     // 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 +204,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)",
+    sameStep: BROWSER_SAME_STEP,
     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 +260,26 @@ 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: "",
+    inlineSite: {
+        noun: "inline action sequence",
+        nouns: "Inline action sequences",
+        unit: "sequence",
+        stepNoun: "action sequence",
+        extendClause: "",
+        // The in-house clause is unconditional here: this rule renders on the seeded UI
+        // flow only, and that is the flow STEP 2b/3b render on.
+        match: (fileName) => `whose action key equals a helper now defined in \`${fileName}\` — or, when STEP 2b found a qualifying in-house module, one of THEIR helpers whose key is defined (their module is not edited in this step; STEP 3b's rules govern the call, and a helper whose key is undefined is left alone). A sibling's OWN module-level copy of the sequence counts: delete it and import the shared helper in its place`,
+        // A site matched against the customer's helper passes what their signature
+        // takes and lifts nothing: their module is STEP 3b's to change, and on that
+        // path the Skyramp module was never created.
+        target: (fileName) => `CALLS TO THE SHARED HELPER (IN \`${fileName}\`, OR THE REPOSITORY'S OWN MODULE)`,
+        lift: (fileName) => `for a helper in \`${fileName}\`, lift a literal it lacks to a defaulted parameter there; for one of the repository's own helpers, pass only the literals its signature takes and lift nothing — their module is not edited in this step`,
+        keeps: "its other steps, assertions, page-error guard and order stay verbatim",
+        afterSteps: "5. Run every sibling you edited with skyramp_execute_test after the verify call — an edited pre-existing test without a recorded execution cannot be reported.\n",
+    },
+    inlineCallSiteRule: `**An inline action sequence is a call site, not a helper.** A step written inline — a run of browser actions (clicks, fills, selects, presses) and the structural waits between them, not wrapped in a function — is never something to author a helper from in this pass. But when a helper that performs ${BROWSER_SAME_STEP} already exists — judge it by the action key: the verb plus the locator chain of each action, in order, argument values aside — the run is that helper's call site: REPLACE the run with a call to the helper, passing the run's own literals (${BROWSER_LIFTABLE}) as arguments; lift a literal the helper does not yet take to a parameter DEFAULTED to the helper's current literal, so every existing call site keeps its behaviour. The call replaces the actions and the structural waits between them and NOTHING else: every value assertion stays in the test body — one that follows the run stays right after the call, selector verbatim and expected value unchanged — and the page-error guard (\`page.on('pageerror'...)\`, error collectors and their final \`expect\`) stays where it is. A run with a value assertion, a guard or any other statement BETWEEN two of its actions is NOT a call site — a call cannot carry it, and an assertion never moves across an action — leave the run as it is. A \`waitForTimeout(...)\` line between two actions of the run is recorder noise, not a difference: the run still matches, and the call replaces the sleep with it. A run whose selectors differ from the helper's, or that has an action the helper lacks or lacks one the helper has, stays as it is.`,
     // 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 +291,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/startTraceCollectionPrompts.js

@@ -76,7 +76,7 @@ When playwright is enabled for trace collection, you can optionally configure:
      1. Start the trace collection.
      2. Have the user log in once.
      3. STOP IMMEDIATELY after login completes — any further interactions will pollute the trace.
-   - Re-use the saved file by passing it as \`playwrightStoragePath\` (option 3) on later \`skyramp_start_trace_collection\` runs (skips login). Generated tests that reference \`storageState\` will also auto-mount it when run via \`skyramp_execute_test\`.
+   - Re-use the saved file by passing it as \`playwrightStoragePath\` (option 3) on later \`skyramp_start_trace_collection\` runs (skips login). Generated tests that reference \`storageState\` read it from that path when run via \`skyramp_execute_test\`.
    - Example user prompts: "save my session", "store login session for future tests", "record auth state", "with session storage".
 
 **Example usage prompt for trace collection:**

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

@@ -92,7 +92,7 @@ function buildSubstrateBody() {
 
 For each suite that DOES need the SUT, bring up its substrate INSIDE \`.skyramp/sut/setup.sh\` — the same script that brings up the preflight SUT app — so one \`targetSetupCommand\` stands up every consumer. Bring-up and teardown always live in \`setup.sh\` / \`teardown.sh\`, never in \`workspace.yml\`. Install the suite's dev/test dependencies from the repo's OWN lockfile (\`package-lock.json\`, \`uv.lock\`, \`go.sum\` — never "latest"), and pin any UI browser image to the repo's version, inside that script. Choose the most reuse the suite can reach, in order of preference:
 
-**Reuse the running SUT (prefer this).** When the suite targets the app over HTTP from a base-URL env var and does not boot its own app (no \`webServer\`, or one that defaults to \`reuseExistingServer\`, or a global-setup that only logs in / seeds against a running server), point it at the already-running SUT — stand up no second app and no separate env-start, and bake the suite's OWN base-URL env var into \`testRunCommand\` as an inline prefix referencing the SUT's exported URL. The left-hand name is whatever that repo's config reads — e.g. \`PW_BASE_URL=$SKYRAMP_TEST_BASE_URL npx playwright test\` for a Playwright config that reads \`PW_BASE_URL\`, or \`APP_BASE_URL=$SKYRAMP_TEST_BASE_URL <run cmd>\` for one that reads \`APP_BASE_URL\`. Read the config to find the real name; never assume it. Use \`$SKYRAMP_TEST_BASE_URL\` for a single-URL SUT, or \`$SKYRAMP_TEST_SERVICE_URL_<SERVICENAME>\` (service name upper-cased, \`- . : /\` replaced with \`_\`) when the SUT exposes multiple distinct service URLs, matching the service the suite targets. Inline ONLY this base-URL prefix (it must be shell-expanded); record any STATIC env the suite needs (e.g. \`NODE_ENV\`, a test-DB driver) in the suite's \`testEnv\` map when you record the contract, not as an inline prefix.
+**Reuse the running SUT (prefer this).** When the suite targets the app over HTTP from a base-URL env var and does not boot its own app (no \`webServer\`, or one that defaults to \`reuseExistingServer\`, or a global-setup that only logs in / seeds against a running server), point it at the already-running SUT — stand up no second app and no separate env-start, and bake the suite's OWN base-URL env var into \`testRunCommand\` as an inline prefix referencing the SUT's exported URL. The left-hand name is whatever that repo's config reads — e.g. \`PW_BASE_URL=$SKYRAMP_TEST_BASE_URL npx playwright test\` for a Playwright config that reads \`PW_BASE_URL\`, or \`APP_BASE_URL=$SKYRAMP_TEST_BASE_URL <run cmd>\` for one that reads \`APP_BASE_URL\`. Read the config to find the real name; never assume it. Use \`$SKYRAMP_TEST_BASE_URL\` for a single-URL SUT, or \`$SKYRAMP_TEST_SERVICE_URL_<SERVICENAME>\` (service name upper-cased, \`- . : /\` replaced with \`_\`) when the SUT exposes multiple distinct service URLs, matching the service the suite targets. Put any STATIC env the suite needs (e.g. \`NODE_ENV\`, a test-DB driver) in the same inline prefix.
 
 **Reuse the SUT's built image + infra — when the suite boots its own app.** When the suite MUST boot its own app instances (e.g. per-worker containers via its own orchestration), reuse what the SUT phase already produced — the built image and the running infra — instead of rebuilding from source or standing up a duplicate data tier (rebuilding wastes the SUT's work and duplicate infra desyncs from it). The suite owns spawning the app instances; you own the substrate and the handoff, in \`setup.sh\`. So read its orchestration code for how it FINDS each thing it needs, and satisfy that mechanism — an equivalent service under a different identity provides nothing, because the suite looks for the one its code names, does not find it, and dies in its own setup having never reached a test. The mechanism is one of:
 - A config value it reads — typically a mode flag telling it to use a prebuilt image, plus a variable naming the tag; also base URLs and DSNs. The names are repo-specific (\`E2E_APP_IMAGE\`, \`<APP>_E2E_IMAGE\`, …). Build the app image ONCE and export the tag under the name that suite reads. And a suite that spawns containers needs EVERY image it launches present in the local daemon, not just the app's — \`docker pull\` any gateway, proxy, database or browser image it names, explicitly, in \`setup.sh\`. Do not leave one to chance because it happened to be cached while you were working: that is ambient runner state, the next runner will not have it, and the suite fails in its own global setup naming an image you never provided.
@@ -110,12 +110,11 @@ function buildRecordTestContractBody() {
 
 Recording a suite documents that it EXISTS and how it is invoked; provisioning it is the substrate step's business and proving it is the local canary's. Maintenance runs choose what to execute from this list and cannot discover a suite missing from it, so record a suite even when its environment is one you could not build or its command needs infra you did not stand up — write a working \`testRunCommand\` and record the unmet requirement in that suite's \`canaryDetail\` (below) so CI can supply it. Some suites are hard to reduce to a single command — they want a Docker socket, their own orchestration, or a long list of env vars. Record those too: follow the \`testRunCommand\` rules below, and say in your summary what the suite needs. Each entry sets:
 - \`framework\` — the suite's runner.
-- \`testRunCommand\` — the base run command. An in-process suite is just the repo's own standalone command (e.g. \`yarn test:unit\`). At run time the adapter appends a machine-readable reporter flag and the specific test-file paths to the END of this string, and points the reporter at an output path — so the command has to be one that can actually receive them. **The reporter itself must exist in the suite's environment, and \`setup.sh\` is what installs it**: Playwright and Mocha ship theirs, but **pytest needs the \`pytest-json-report\` plugin** — without it pytest exits on an unrecognised option and the suite reports nothing however healthy it is. The runner process also has to be able to WRITE the reporter's output path, which is the same constraint the container rule below describes. The rules below follow from all that, and breaking any of them means the suite can never report a result:
-  - It must accept appended arguments. Record the invocation that receives them (\`npx playwright test\`, \`pnpm --filter <package> test:unit\`). **Prefer invoking the runner directly** — the repo's own config via a flag or package filter, the suite's static env in \`testEnv\` — which satisfies this rule by construction. Most of what a repo's launcher script does IS just that env, so reach for the script only when it does setup you cannot express that way: values it derives at run time, files it sources, a sidecar it starts. Then a repo's own wrapper is fine but only if it FORWARDS its arguments to the runner. Open the script and check: one ending in \`exec "$@"\` (or otherwise passing \`"$@"\` on) is safe, and you record it with the runner's own command appended, e.g. \`bash <wrapper-script> playwright test\`. A script that hardcodes the test invocation inside itself is NOT safe: your appended arguments are ignored, so it silently runs the WHOLE suite and writes no report where the adapter looks. **When a repo ships several entrypoints for one suite, read them all and pick the forwarding one** — a \`…-host\` and a \`…-container\` variant commonly sit side by side, and only one of them can be driven. Only when the setup is genuinely irreducible AND no shipped entrypoint both forwards arguments and runs from the repository root, write your own thin wrapper in \`.skyramp/sut/\` — translate the appended paths if the script it calls changes directory, and \`exec\` with \`"$@"\`.
-  - The appended paths are relative to the repository root, and the command runs from the repository root. So do not \`cd\` into a subdirectory — the paths will not resolve from there. Point the runner at the subdirectory instead, with the config the repo ALREADY has (e.g. \`npx playwright test --config <path/to/playwright.config.*>\` — the repo's own file, which you have read and confirmed exists) or a package filter (e.g. \`pnpm --filter @scope/e2e test\`); for pytest, name its config and target from the root (e.g. \`pytest -c pytest.ini tests/api\`, or \`--rootdir\` when the suite needs one) rather than changing directory, since pytest resolves \`conftest.py\` and \`sys.path\` from where it runs. **Never name a path you did not write**: a command pointing at a config you invented but never created fails everywhere, and a config you write outside \`.skyramp/sut/\` is not captured with the SUT files, so it is missing on the next run even though it worked on yours.
-  - A value that must be SHELL-EXPANDED at run time goes directly in front of the runner, e.g. \`PW_BASE_URL=$SKYRAMP_TEST_BASE_URL npx playwright test\` — the executor writes \`testEnv\` values verbatim and cannot expand \`$…\`. Never put such an assignment in front of a \`cd\` (\`VAR=$X cd e2e && npx playwright test\`): the assignment applies only to the \`cd\`, so the runner never sees VAR. Static values belong in \`testEnv\` (next), not inlined here.
-  - If the repo runs this suite inside a container (a script doing \`docker run … <runner>\`), that boundary swallows the appended arguments, drops any environment the reporter is configured through, and leaves the reporter writing to an output path that does not exist inside the container — so the wrapper cannot be the \`testRunCommand\`. Record the runner invocation itself, and KEEP the wiring that script provided by moving the env it set into \`testEnv\` — a bare runner that has lost the mode flags and image tags is just as unrunnable as the wrapper. State the container requirement (docker socket, runner size) in your summary so CI can supply it. Record the suite either way, never drop it.
-- \`testEnv\` — a map of STATIC environment variables the suite needs, as literal values with no shell expansion (e.g. \`NODE_ENV: testing\`, \`DB: better-sqlite3\`). The executor injects these into the test process's environment at run time, so record them here instead of inlining them into \`testRunCommand\`: structured env is adapter-safe (selectors are appended to the command without disturbing env) and lets maintenance inspect or override it. Omit when the suite needs no static env. (Values that need runtime shell expansion, like the SUT base-URL, stay inline in \`testRunCommand\` — see above.)
+- \`testRunCommand\` — the base run command. An in-process suite is just the repo's own standalone command (e.g. \`yarn test:unit\`). To run one test file, the agent adds that file's path to the END of this string, so the command has to be one that can actually receive it. Put every environment variable the suite needs in front of the runner (e.g. \`NODE_ENV=testing PW_BASE_URL=$SKYRAMP_TEST_BASE_URL npx playwright test\`). Breaking any rule below means the suite can never run a single file:
+  - It must accept an appended path. Record the invocation that receives it (\`npx playwright test\`, \`pnpm --filter <package> test:unit\`). **Prefer invoking the runner directly** — the repo's own config via a flag or package filter, the suite's env as an inline prefix — which satisfies this rule by construction. Most of what a repo's launcher script does IS just that env, so reach for the script only when it does setup you cannot express that way: values it derives at run time, files it sources, a sidecar it starts. Then a repo's own wrapper is fine but only if it FORWARDS its arguments to the runner. Open the script and check: one ending in \`exec "$@"\` (or otherwise passing \`"$@"\` on) is safe, and you record it with the runner's own command appended, e.g. \`bash <wrapper-script> playwright test\`. A script that hardcodes the test invocation inside itself is NOT safe: the appended path is ignored, so it silently runs the WHOLE suite. **When a repo ships several entrypoints for one suite, read them all and pick the forwarding one** — a \`…-host\` and a \`…-container\` variant commonly sit side by side, and only one of them can be driven. Only when the setup is genuinely irreducible AND no shipped entrypoint both forwards arguments and runs from the repository root, write your own thin wrapper in \`.skyramp/sut/\` — translate the appended path if the script it calls changes directory, and \`exec\` with \`"$@"\`.
+  - The appended path is relative to the repository root, and the command runs from the repository root. So do not \`cd\` into a subdirectory — the path will not resolve from there. Point the runner at the subdirectory instead, with the config the repo ALREADY has (e.g. \`npx playwright test --config <path/to/playwright.config.*>\` — the repo's own file, which you have read and confirmed exists) or a package filter (e.g. \`pnpm --filter @scope/e2e test\`); for pytest, name its config from the root (e.g. \`pytest -c pytest.ini\`, or \`--rootdir\` when the suite needs one) and no test directory rather than changing directory, since pytest resolves \`conftest.py\` and \`sys.path\` from where it runs. **Never name a path you did not write**: a command pointing at a config you invented but never created fails everywhere, and a config you write outside \`.skyramp/sut/\` is not captured with the SUT files, so it is missing on the next run even though it worked on yours.
+  - Never put an environment assignment in front of a \`cd\` (\`VAR=$X cd e2e && npx playwright test\`): the assignment applies only to the \`cd\`, so the runner never sees VAR.
+  - If the repo runs this suite inside a container (a script doing \`docker run … <runner>\`), that boundary swallows the appended path and drops the environment set in front of it — so the wrapper cannot be the \`testRunCommand\`. Record the runner invocation itself, and KEEP the wiring that script provided by moving the env it set into the inline prefix — a bare runner that has lost the mode flags and image tags is just as unrunnable as the wrapper. State the container requirement (docker socket, runner size) in your summary so CI can supply it. Record the suite either way, never drop it.
 - \`pathGlobs\` — the repo-relative paths that suite owns, written as globs (e.g. a package's \`test/unit/**\` for a backend unit suite, \`e2e/tests/**\` for a browser suite). **Record it on every suite, always** — including when the repo has only one. It is what sends a test file to the suite that can actually run it, and a suite with no globs accepts EVERY file, so an omitted entry means a suite gets handed specs it cannot load and its runner dies parsing them. Keep the globs disjoint, so no file matches two suites. Scope by DIRECTORY, not by filename — \`e2e/tests/**\`, not \`e2e/tests/**/*.spec.ts\`. A directory owns whatever the suite runs; narrowing by filename quietly drops every file named differently, and one suite routinely mixes conventions — \`.test.ts\` beside \`.spec.ts\`, or \`test_*.py\` beside \`*_test.py\`. Only narrow by filename when one directory genuinely holds two runners' files, and then list every pattern the suite owns after checking the real filenames on disk.
 - \`canaryStatus\` + \`canaryDetail\` — filled in AFTER the local canary, not now. \`proven\` means you watched a test from that suite execute; \`unproven\` means you did not, and \`canaryDetail\` then states what it still needs. An unproven suite stays recorded and stays maintained, so never delete an entry to avoid marking it.
 The workspace records only how to run and where to find each suite; the environment a suite needs — a built image, shared infra, a browser — is brought up by \`setup.sh\`.`;
@@ -152,7 +151,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_execute_test, 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

@@ -1,3 +1,5 @@
+import { RUN_TEST_COMMAND_RULES } from "../../skills/runTestSkill.js";
+import { runnableLanguagesText } from "../../types/TestTypes.js";
 /**
  * Path of the Testbot workflow file relative to the repo root. Created by the
  * Testbot installer and edited in-place by every SUT setup mode.
@@ -82,7 +84,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,10 +97,10 @@ 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, pick one real test FILE per recorded suite. For each file, call **\`skyramp_execute_test\`** with \`commandOverride\`: the suite's recorded \`testRunCommand\` limited to that file, plus \`cwd\`, \`testFile\`, \`language\`, \`testType\`, and \`repository\`: "${args.repository}". Shape the command this way: ${RUN_TEST_COMMAND_RULES}. Pass no \`stateFile\`. Do NOT canary by running the suite's command in your shell. \`skyramp_execute_test\` takes ${runnableLanguagesText()} only: a suite in any other language (Go, RSpec, Jasmine) cannot be canaried this way — record \`canaryStatus: unproven\` with \`canaryDetail\` naming the language.
    - 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.
+   - Read the verdict per file, and the output with it. Some runners exit 0 when they find no test (mocha; junit with \`-DfailIfNoTests=false\`), so \`Pass\` on its own does not prove a test ran: the output must show at least one test from that file executing. If it does not, the suite is not proven — treat it as you would an \`Error\`. \`Fail\` does prove the command works, because only a test that ran can fail. \`Error\` means that it does not — the output says why, and that text belongs in the suite's \`canaryDetail\`.
+   - A \`Fail\` verdict is fine — the environment is runnable, so proceed. An \`Error\` verdict 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.
 5. Tear down — run \`targetTeardownCommand\` (branch a), or each TEARDOWN step's body in order (branch b), so the next iteration starts clean; confirm exit 0.
 Only proceed to the success report once pre-steps → setup → health check → canary (every suite in the mandatory set) → teardown all pass, and every recorded suite carries a \`canaryStatus\`. \`proven\` requires that you watched a test execute. \`unproven\` is NOT a way to close out a suite you could have fixed — it is permitted only when the blocker is something only CI can grant (a secret, a registry credential, a hosted dependency), and then \`canaryDetail\` must name that grant. Every other cause is yours to fix before you finish, and those are the common ones: a runner binary the suite needs that is installed in the repo but absent from \`PATH\`, an image nobody built, infra the bring-up never started, a wrong path in \`testRunCommand\`. Fix the artifact — \`setup.sh\`, the workflow pre-steps, \`workspace.yml\` — and canary that suite again. Only after two genuine fix attempts have failed on the same cause may you record \`unproven\`, with \`canaryDetail\` naming both the cause and what you tried. **Keep every suite recorded either way** — an unproven suite is still maintained from source, so removing the entry is the only move that loses that coverage outright.`;
 }

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;