@skyramp/mcp 0.3.8 → 0.3.9-rc.1

package/build/playwright/registerPlaywrightTools.js

@@ -154,6 +154,7 @@ export async function registerPlaywrightTools(server, options) {
         'browser_wait_for',
         'browser_take_screenshot',
         'browser_assert',
+        'browser_assert_hidden',
         'browser_assert_api_request',
         'browser_assert_table_cell',
         'browser_mouse_action',

package/build/prompts/enhance-assertions/uiAssertionsPrompt.js

@@ -33,7 +33,7 @@ expect(trigger).to_be_focused()`,
             },
             {
                 title: "Selector constraints",
-                description: "Every assertion uses a selector already in the file. Never invent `data-testid`, role names, or classes.",
+                description: "Every assertion uses a selector already in the file. Never invent `data-testid`, role names, or classes. One exception: a `data-*` attribute + value listed in `uiContext.removedElements` (from the `skyramp_analyze_changes` output in your context) may be asserted `toBeHidden()` even though no element carries it any more — `getByTestId(value)` for `data-testid`, `page.locator('[data-cy=\"value\"]')` for any other attribute — see Removed element guard. A `-` line in the raw diff is not enough on its own: renames and moved elements also appear there.",
                 subPoints: [
                     "No tautological assertions — locating an element by text X, then asserting it contains X.",
                 ],
@@ -44,6 +44,27 @@ expect(trigger).to_be_focused()`,
                     },
                 ],
             },
+            {
+                title: "Removed element guard",
+                description: "When the PR deletes a rendered element (a `data-*` attribute + value listed in `uiContext.removedElements`) and the test visits the page that rendered it, assert `toBeHidden()` on it — `getByTestId(value)` when the attribute is `data-testid`, otherwise `page.locator('[<attribute>=\"<value>\"]')` (never `getByTestId` for `data-cy`/`data-qa`: Playwright resolves it against `data-testid` and the guard would pass vacuously). `toBeHidden` passes when the locator matches nothing or a single non-visible node (it is strict on multiple matches, like every locator assertion), which is the right contract for a removed element; do not substitute a `toBeVisible` on an unrelated element. Pair it with at least one positive assertion on a retained element of the same page so the test cannot pass on a blank or un-rendered page.",
+                subPoints: [
+                    "Anchor on the removed attribute+value or role+name, never on text or position — a text-based absence check breaks when unrelated siblings change.",
+                    "Do not add a guard for an element whose whole page or route was removed — that is maintenance of the tests that covered it, not a new assertion.",
+                ],
+                examples: [
+                    {
+                        language: "javascript",
+                        code: `await expect(page.getByTestId('navbar-sessionid-row')).toBeHidden();
+await expect(page.locator('[data-cy="checkout-btn"]')).toBeHidden();
+await expect(page.getByTestId('navbar-products')).toHaveText('Products');`,
+                    },
+                    {
+                        language: "python",
+                        code: `expect(page.get_by_test_id('navbar-sessionid-row')).to_be_hidden()
+expect(page.get_by_test_id('navbar-products')).to_have_text('Products')`,
+                    },
+                ],
+            },
             {
                 title: "Page errors",
                 description: "Register `page.on('pageerror', ...)` before the first navigation and assert `expect(errors).toHaveLength(0)` at the end of the test.",

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

@@ -16,6 +16,8 @@ export declare function buildRenameStrategy(): string;
 export declare function buildFileRenameStrategy(): string;
 /** Strategy string for in-place UPDATE edits. */
 export declare function buildUpdateStrategy(): 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 DELETE — remove obsolete test files whose covered endpoints/UI no longer exist. */
@@ -27,6 +29,8 @@ export declare function buildUpdateFileInstruction(params: {
     suggestedNewFile?: string;
     updateInstructions?: string;
     rationale?: string;
+    /** Visual baselines to refresh at final execution instead of editing (SKYR-4298). */
+    rebaselineSnapshots?: string[];
 }): string;
 /** Per-file instruction block for a single REGENERATE recommendation. */
 export declare function buildRegenerateFileInstruction(params: {

package/build/prompts/test-maintenance/actionsInstructions.js

@@ -23,6 +23,10 @@ UPDATE is an in-place edit to the existing baseline file — do not create a new
 
 After editing, re-read each file to confirm the change landed, then call skyramp_enhance_assertions with each updated file path.`;
 }
+/** Strategy string for UPDATE entries that refresh visual-snapshot baselines (SKYR-4298). */
+export function buildRebaselineStrategy() {
+    return `Some update_context entries carry rebaseline_snapshots: the diff changed how the page or element those toHaveScreenshot() baselines capture looks, so the committed PNGs are stale and must be replaced, not the spec. For those baselines do NOT edit the toHaveScreenshot() call, do NOT raise maxDiffPixelRatio, do NOT remove the assertion, and do NOT touch the PNG yourself. Refresh them at the final execution: call skyramp_execute_test for that spec with rebaselineSnapshots set to exactly the listed filenames — SmartPlaywright re-captures each one and the new PNG lands beside the spec, where the Testbot PR shows it as an image diff for review. An entry with edit_required: false (no context) has nothing to edit: skip the Edit/re-read/skyramp_enhance_assertions steps for that file — the refresh at final execution is its whole maintenance. When you call skyramp_execute_test for the refresh, set testFile to the entry's spec_file (NOT its file, which is the page object for a POM-backed update). The execution result names which baselines were refreshed and which were not; report only the refreshed ones as refreshed. Never pass rebaselineSnapshots on the phase: "before" run — that run is the evidence that the baseline is stale.`;
+}
 /** Strategy string for REGENERATE — call generation tool to overwrite the file. */
 export function buildRegenerateStrategy() {
     return `For each file in regenerate_context, call the appropriate generation tool (skyramp_integration_test_generation or skyramp_contract_test_generation) with outputDir set to the file's directory and output set to the filename. The generation tool will overwrite the file. Do NOT use skyramp_ui_test_generation here — UI test regeneration requires a recorded trace (playwrightInput) and must be handled separately.`;
@@ -34,6 +38,7 @@ export function buildDeleteStrategy() {
 /** Per-file instruction block for a single UPDATE recommendation. */
 export function buildUpdateFileInstruction(params) {
     const { testFile, renames, suggestedNewFile, updateInstructions, rationale } = params;
+    const rebaselineSnapshots = params.rebaselineSnapshots ?? [];
     const renameTable = renames.length > 0 ? [
         `**Endpoint Rename Detected — Path Substitution Required:**\n`,
         `| Old Path | New Path | Method |`,
@@ -49,13 +54,20 @@ export function buildUpdateFileInstruction(params) {
     ].join("\n") : "";
     const changeBlock = updateInstructions
         ? `**What to change:**\n\n${updateInstructions}\n`
-        : renames.length === 0
+        : renames.length === 0 && rebaselineSnapshots.length === 0
             ? [
                 rationale ? `**Why:** ${rationale}\n` : "",
                 `**Action:** Update this test file based on the rationale above.\n`,
             ].filter(Boolean).join("\n")
             : "";
-    return `\n### ${testFile}\n\n${renameTable}${changeBlock}`;
+    const rebaselineBlock = rebaselineSnapshots.length > 0
+        ? [
+            `**Visual baselines to refresh:** ${rebaselineSnapshots.map((s) => `\`${s}\``).join(", ")}`,
+            rationale && !updateInstructions ? `**Why:** ${rationale}` : "",
+            `**Action:** Do not edit these \`toHaveScreenshot()\` calls, their \`maxDiffPixelRatio\`, or the PNGs. At the final execution, call \`skyramp_execute_test\` for this spec with \`rebaselineSnapshots: ${JSON.stringify(rebaselineSnapshots)}\` so SmartPlaywright re-captures them; the refreshed PNGs are delivered with the Testbot PR as image diffs.\n`,
+        ].filter(Boolean).join("\n")
+        : "";
+    return `\n### ${testFile}\n\n${renameTable}${changeBlock}${rebaselineBlock}`;
 }
 /** Per-file instruction block for a single REGENERATE recommendation. */
 export function buildRegenerateFileInstruction(params) {

package/build/prompts/test-maintenance/uiDriftAnalysisSections.js

@@ -39,10 +39,12 @@ Matching none does **not** mean IGNORE — first run the selector safety net: ma
 
 Build a detection list first: for each matched diff line, write one line: \`{pattern type} — "{diff line}" — affects {route/component}\`.
 
+**Visual-snapshot baselines.** A test that calls \`toHaveScreenshot("<name>.png")\` pixel-compares a page, element, or region against a committed baseline PNG. For such a test only — this does not widen the detection list for any other test — also treat as a reaching change any appearance edit inside what the call captures: a CSS/Tailwind/styled-components change, a changed literal string that renders, a swapped image or icon, a reordered or added visible element. When such a change reaches what one of those calls captures, the baseline is stale — the assertion's expected value is the image, and it must be refreshed exactly as a text assertion would be corrected. Assign **UPDATE** and list the affected baseline filenames in \`rebaselineSnapshots\` (only those whose captured page/element/region the diff reaches — an unaffected baseline in the same spec stays as it is). The refresh happens at execution via \`skyramp_execute_test\`'s \`rebaselineSnapshots\`; never edit the \`toHaveScreenshot()\` call, raise \`maxDiffPixelRatio\`, delete the assertion, or hand-edit a PNG to make it pass — those hide real regressions. When a pre-edit run reports \`Screenshot comparison failed\` and NO diff line explains the mismatch for that capture, the baseline is not stale: leave the test as it is, keep it \`Fail\`, and record the finding in \`issuesFound\`.
+
 **Rules (assign exactly one action per test; severity order above):**
 - **DELETE** when the test's target is gone: all routes/pages it covers no longer exist; all critical selectors were removed with no migration path; or, for a component/widget test, the component it renders was deleted (source removed with no re-export; report-only for external tests).
 - **REGENERATE** when the interaction model changed so fundamentally that the test's action sequence is broken with no migration path: the flow itself changed, not just selector values (e.g. a form replaced by a modal, buttons replaced by a dropdown, a click-to-update button replaced by an auto-updating stepper). Re-recording from scratch is the only viable approach. Broken-selector count alone does not decide REGENERATE; if the flow still works with targeted edits, it is UPDATE.
-- **UPDATE** when the test's flow still holds but something it relies on shifted on a page or component it exercises: a selector (className, data-testid, aria-*) was renamed or moved, a new selector was added that the test should adopt or assert (including a dynamic class like \`+ \`btn--\${variant}\`\`), or an assertion needs adjusting. Fix it in place in the existing file, never a new spec for the same page or component. An added selector is still drift, not a no-op. Read the test/POM to confirm the component is targeted and prefer UPDATE; fall back to VERIFY only when reading leaves impact undetermined.
+- **UPDATE** when the test's flow still holds but something it relies on shifted on a page or component it exercises: a selector (className, data-testid, aria-*) was renamed or moved, a new selector was added that the test should adopt or assert (including a dynamic class like \`+ \`btn--\${variant}\`\`), an assertion needs adjusting, or a \`toHaveScreenshot()\` baseline captures something whose appearance the diff changed (see **Visual-snapshot baselines** above — name the stale files in \`rebaselineSnapshots\`). Fix it in place in the existing file, never a new spec for the same page or component. An added selector is still drift, not a no-op. Read the test/POM to confirm the component is targeted and prefer UPDATE; fall back to VERIFY only when reading leaves impact undetermined.
 - **VERIFY** when the test may be impacted but you cannot confirm breakage without reading more context (e.g. the affected selectors live in a page object or indirect import you have not read). Read that file before escalating to UPDATE.
 - **IGNORE** when the changed code cannot reach this test's routes or rendered components (the diff touches different routes or components). If you cannot point to a diff line affecting this test's routes, selectors, or rendered components, the action is IGNORE or VERIFY, not UPDATE.
 </ui_decision_rules>`;
@@ -182,6 +184,7 @@ Test: {testFile}
 Action: UPDATE
 Rationale: UPDATE because {quoted diff line}; name the concrete before→after value (e.g. data-testid "old-id" → "new-id", class "btn-old" → "btn-new", route "/old" → "/new") — this rationale is the report's record of what was maintained, so a vague "selector changed" is not enough
 UpdateInstructions: {what must change — specific selectors to update, routes to patch, assertions to add}
+RebaselineSnapshots: {only when a toHaveScreenshot() baseline captures what the diff visibly changed — the stale filenames, e.g. ["page-001.png"]; omit otherwise}
 \`\`\`
 \`\`\`
 Test: {testFile}

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

@@ -48,6 +48,7 @@ function _execCoverageBody(ctx) {
   **Avoid backfilling with a test for a completely unrelated resource (e.g. \`POST /reviews\` when the PR only changes \`/orders\`) if any PR-endpoint edge-case integration test is feasible.**
 - **Contract tests (\`[skyramp]\`)**: If an existing \`[skyramp]\` contract test already covers that resource path → UPDATE the existing test file instead of creating a new one. A new test case is a new test even if the file already exists — count it toward \`newTestsCreated\`.
 - **\`[removed]\` endpoints**: If a GENERATE item targets an endpoint marked \`[removed]\` — the route was deleted in this PR, not renamed — generate a single contract test that asserts \`404 Not Found\`. Do not generate success-path (2xx) tests for removed endpoints. The purpose is a regression guard that catches the endpoint being accidentally re-added.
+- **Removed UI elements** (\`uiContext.removedElements\` in the \`skyramp_analyze_changes\` output): the grounding for the removal test the budget rule already requires — it names each removed element (a \`data-*\` attribute and value) and the page it rendered on. Per PAGE listed, not per id: if the plan already has a UI candidate on that page, that trace carries the guard (record \`browser_assert_hidden\` per listed element on that page — \`testId\` for \`data-testid\`, otherwise \`attribute\` + \`value\` — plus the page's ordinary assertions); otherwise register ONE candidate \`verify-removed-ui-<page-slug>\` (\`testType: "ui"\`, category \`breaking_change\`; \`skyramp_register_test_plan\` requires at least one step — use a placeholder \`GET <page path>\` → 200). Every guard spec pairs its \`toBeHidden()\` assertions with at least one positive assertion on a retained element of the same page; never substitute a \`toBeVisible\` on an unrelated element for the guard.
 - **Integration/scenario tests**: Always generate as a new file via the scenario pipeline, even if an existing integration test covers the same resource. A new multi-step scenario is a distinct test. Count it toward \`newTestsCreated\`.
 - **UI tests**: Always generate as a new file. Count toward \`newTestsCreated\`.`;
 }

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

@@ -213,7 +213,7 @@ export function isTestFile(filePath) {
  * frontend GENERATE list is placeholders the agent must fill from the diff itself.
  */
 function changedBehaviorSection(effectiveGenerate, budgetPlanTiming = "") {
-    return `**Fill the budget from changed behavior:** The ceiling above is the most this run may plan, not a quota to reach or a default to cut. Enumerate every observable behavior this diff changes — each option value added, removed, renamed or reordered; each label, element, route, state, validation rule or computed value that renders or behaves differently — and give each one its own candidate. Treat no change as too trivial to test: a changed option value that no test asserts is a test. A changed style value counts too — a spacing, size, color, radius, font weight, icon size or class name that now renders differently is a changed behavior; its candidate asserts the new computed style or class on that element, or records a \`browser_visual_snapshot\` of it. A removed option, element or feature is a changed behavior too: its candidate asserts the removed thing is absent from the page where it used to render — the removal is what this PR ships, so the removal is what gets tested.
+    return `**Fill the budget from changed behavior:** The ceiling above is the most this run may plan, not a quota to reach or a default to cut. Enumerate every observable behavior this diff changes — each option value added, removed, renamed or reordered; each label, element, route, state, validation rule or computed value that renders or behaves differently — and give each one its own candidate. Treat no change as too trivial to test: a changed option value that no test asserts is a test. A changed style value counts too — a spacing, size, color, radius, font weight, icon size or class name that now renders differently is a changed behavior; its candidate asserts the new computed style or class on that element, or records a \`browser_visual_snapshot\` of it. A removed option, element or feature is a changed behavior too: its candidate asserts the removed thing is absent from the page where it used to render — the removal is what this PR ships, so the removal is what gets tested. When the \`skyramp_analyze_changes\` output carries \`uiContext.removedElements\`, take the removed elements (each a \`data-*\` attribute and value) and the page to assert on from that list (it excludes renames, moves and deleted files, and names the page the element rendered on) instead of reading them off the raw diff; a removed element the list does not carry still gets its candidate, grounded in the diff.
 
 A changed behavior is something a user can observe differently after this diff. Code the diff deletes, dedupes or simplifies without changing what renders is not a changed behavior — its coverage is maintenance of the tests that reach it — and a pre-existing defect you notice nearby is an \`issuesFound\` entry, not a slot in this budget. Only a comment, whitespace or equivalent-value edit (\`0px\` → \`0\`) changes nothing observable.
 

package/build/prompts/testbot/testbot-prompts.js

@@ -144,7 +144,7 @@ export function getTestbotPrompt(opts) {
         maintenanceBeforeExecStep = `   d. Plan-only run: skip the pre-edit baseline execution — the application is not running. Record every maintenance verdict from static drift analysis alone; execution statuses simply remain unrecorded.`;
     }
     else {
-        maintenanceBeforeExecStep = `   d. Call \`skyramp_execute_test\` with \`phase: "before"\` and \`stateFile\` for every UPDATE/REGENERATE/DELETE test. Exclude tests marked \`[external]\` — those are baselined in step 2(a) via \`skyramp_run_existing_tests\`. Run them sequentially, not in parallel. This captures the pre-edit baseline — do not skip even if you expect the test to fail.`;
+        maintenanceBeforeExecStep = `   d. Call \`skyramp_execute_test\` with \`phase: "before"\` and \`stateFile\` for every UPDATE/REGENERATE/DELETE test. Exclude tests marked \`[external]\` — those are baselined in step 2(a) via \`skyramp_run_existing_tests\`. Run them sequentially, not in parallel. This captures the pre-edit baseline — do not skip even if you expect the test to fail. Never pass \`rebaselineSnapshots\` here: a \`Screenshot comparison failed\` on this run is the evidence that a visual baseline is stale, and the refresh belongs to the final execution.`;
     }
     // For follow-up requests: emit the @skyramp-testbot header + guardrails + retrieve-recommendations step.
     // For first-run prompts: emit the full Task 1 analysis + maintenance section.
@@ -233,7 +233,7 @@ ${maintenanceBeforeExecStep}
    **Requirement check — does the code do what the PR says it does?** Read the \`<TITLE>\` and \`<DESCRIPTION>\` above as a statement of *intended* behavior and check the diff against it, requirement by requirement. The description is not outranked by the code: when the two disagree, that is a \`requirement_conflict\`, not a case of "the description loses". Detection, the requirements-file rules, the four false-red pre-checks and the promotion ordering are specified in the Code Review step of the Execution Plan \`skyramp_analyze_changes\` returned — follow them there rather than improvising; read any requirements file the description names from \`${repositoryPath}\`.
    - **On a mismatch, do both.** (a) Add an \`issuesFound\` entry at severity \`high\` or \`critical\` — never \`medium\` or below — quoting the requirement and naming the file and line that contradicts it. (b) Carry it into Task 2 as a \`requirement_conflict\` candidate: a test asserting **what the description requires**, which therefore FAILS on the current code. Where no such test is recordable, record the Execution Plan's VERIFY-style entry in \`additionalRecommendations\` instead — never resolve the disagreement by asserting what the code does.
 
-4. **Blueprint Citation Invariant** (UI test recommendations only). Every named UI element in your recommendation must correspond to an element actually captured in one of the blueprints you captured from the UI Blueprint Capture section of \`skyramp_analyze_changes\`. For **every** UI recommendation — both \`newTestsCreated[]\` entries (tests you generated) AND \`additionalRecommendations[]\` entries (deferred tests) with \`testType: "ui"\` — populate **four** fields: \`description\`, \`reasoning\`, \`targetElements\`, and \`pageContext\`. \`description\` and \`reasoning\` carry different roles — fill BOTH (see Field 4 below). The structured fields (\`targetElements\`, \`pageContext\`) are required on UI recs in BOTH arrays; non-UI recs (contract / integration / e2e / batch-scenario) MUST omit them.
+4. **Blueprint Citation Invariant** (UI test recommendations only). Every named UI element in your recommendation must correspond to an element actually captured in one of the blueprints you captured from the UI Blueprint Capture section of \`skyramp_analyze_changes\` — with one exception: a removal guard's target is an element the PR removed, which no blueprint can contain; it is grounded in \`uiContext.removedElements\` instead (see the negative-test note below). For **every** UI recommendation — both \`newTestsCreated[]\` entries (tests you generated) AND \`additionalRecommendations[]\` entries (deferred tests) with \`testType: "ui"\` — populate **four** fields: \`description\`, \`reasoning\`, \`targetElements\`, and \`pageContext\`. \`description\` and \`reasoning\` carry different roles — fill BOTH (see Field 4 below). The structured fields (\`targetElements\`, \`pageContext\`) are required on UI recs in BOTH arrays; non-UI recs (contract / integration / e2e / batch-scenario) MUST omit them.
 
    **Field 1 — \`targetElements\`** (the elements the test targets — array, length 1+):
    \`\`\`json
@@ -347,7 +347,7 @@ ${maintenanceBeforeExecStep}
      "reasoning": "Would assert the **Edit Order** button (\`edit-order-btn\`) is not rendered on cancelled orders; enforces the conditional-render guard added in OrderDetail.tsx:118."
    }
    \`\`\`
-   (For negative tests, ground \`targetElements\` against a captured page where the element DOES render — so the verifier can confirm the citation is real.)
+   (For negative tests, ground \`targetElements\` against a captured page where the element DOES render — so the verifier can confirm the citation is real. **Exception — removal guards:** an element listed in \`uiContext.removedElements\` renders on no page any more, so no blueprint can contain it. For its \`verify-removed-ui-<testId>\` recommendation, cite the element from that list (\`testId\` for a \`data-testid\`; otherwise name the \`attribute="value"\` pair in \`reasoning\` and leave \`testId\` null), take \`role\` and \`accessibleName\` from the deleted JSX in the diff, set \`pageContext.url\` to the page the list names, and prefix \`reasoning\` with \`[removed-element]\`.)
 
    *Page-level / lifecycle test (no single dominant element), recommendatory voice:*
    \`\`\`json
@@ -392,13 +392,13 @@ ${maintenanceBeforeExecStep}
 
    **Self-check before submitting (per UI rec, in both \`newTestsCreated\` and \`additionalRecommendations\`):**
    - **Both \`description\` AND \`reasoning\` are populated.** \`description\` is a 2-4 sentence walkthrough; \`reasoning\` is one sentence about what's verified + why. They must not duplicate each other.
-   - Every entry in \`targetElements\` must appear verbatim in a captured blueprint element (matched on \`accessibleName\` + \`role\`).
+   - Every entry in \`targetElements\` must appear verbatim in a captured blueprint element (matched on \`accessibleName\` + \`role\`) — except a removal guard's entry, whose \`testId\` (or, for a non-\`data-testid\` attribute, the \`attribute="value"\` named in \`reasoning\`) must instead appear in \`uiContext.removedElements\` and whose \`reasoning\` carries the \`[removed-element]\` prefix.
    - Every element name appearing in \`reasoning\` must match an entry's \`accessibleName\` exactly. Every backticked identifier in \`reasoning\` must come from a \`testId\` or \`stableId\` of an entry.
    - **Voice matches the array:** \`newTestsCreated\` uses descriptive voice ("verifies", "asserts", "documents"). \`additionalRecommendations\` uses recommendatory voice ("would verify", "should assert", "would cover").
-   - \`pageContext.url\` must equal the URL of the BlueprintCapture you lifted \`targetElements\` from.
+   - \`pageContext.url\` must equal the URL of the BlueprintCapture you lifted \`targetElements\` from (for a removal guard: the page \`uiContext.removedElements\` names for that id).
    - Never mix two elements' fields in one \`targetElements\` entry — each entry is one captured element.
    - No internal jargon in \`reasoning\` or \`description\`: no \`logicalName\`, \`fingerprint\`, \`pageHash\`, \`xpath\`.
-   - If any check fails, re-capture and verify, or drop that recommendation.
+   - If any check fails, re-capture and verify, or drop that recommendation (a removal guard passes these checks through the \`removedElements\` grounding above, never through invention).
 
    **Non-UI entries (contract / integration / e2e / batch-scenario) are unaffected.** Use their pre-existing reasoning formats. Do NOT add \`targetElements\` or \`pageContext\` to non-UI entries — the schema rejects them.
 
@@ -576,6 +576,7 @@ ${CONTRACT_MODE_GUIDANCE}
   - \`skyramp_export_zip\` outputPath: \`${repositoryPath}/.skyramp/<test_name>_trace.zip\`
   - \`skyramp_ui_test_generation\`: set \`modularizeCode: false\` and \`codeReuse: true\` (TypeScript/JavaScript Playwright only — the default; leave \`codeReuse\` unset for other languages)
   - **\`browser_assert\` — MANDATORY**: at least one per page navigated. Call multiple assertions in the same tool call batch when checking independent elements. If you navigate to 2 pages, assert on both. Each assertion should verify a business outcome (state change, computed value, error condition) — not just that an element is visible.
+  - **Removal guard — when \`uiContext.removedElements\` is non-empty**: the server has already resolved which elements this PR removed — each identified by a \`data-*\` attribute and value — and the page each rendered on (renames, moves and deleted files are excluded). Per listed PAGE: \`browser_navigate\` to it, wait for the app to render, then call \`browser_assert_hidden\` once per listed element using the target the list shows — \`testId: "<value>"\` when the attribute is \`data-testid\`, otherwise \`attribute: "<name>", value: "<value>"\` (e.g. \`attribute: "data-cy"\`); no \`ref\` — the element no longer exists, so no snapshot has one; the tool checks the live page and refuses to record on a blank or un-rendered page. Then at least one \`browser_assert\` on a RETAINED element of the same page verifying its text, value or state. If a UI trace for that page is already planned, record the guard assertions inside that trace; otherwise this is its own trace and spec, \`verify-removed-ui-<page-slug>\`. The generated test asserts \`toBeHidden()\` on \`getByTestId(...)\` or \`page.locator('[data-cy="..."]')\` accordingly. A removed element the server did not list still gets its test (the budget rule requires it) — ground that one in the diff and say so in \`reasoning\`.
   - **\`browser_visual_snapshot\` — for visual/appearance checks**: when the instruction asks to take a screenshot, capture a baseline, or verify how a page/element/region *looks* (not its text or value), call \`browser_visual_snapshot\` — it records a \`toHaveScreenshot()\` assertion so the generated test pixel-compares against a baseline on every run. Do NOT use \`browser_take_screenshot\` for this: it captures a throwaway image that is dropped at export and never appears in the generated test (use it only to view the page yourself).
   - **Wait for stable state before the second capture**: After performing an action that affects computed fields (filling a discount, submitting a form, adding an item), check the current page state before calling the second \`browser_blueprint\` (the capture after the action). If a computed field — total, price, count, derived text — still shows its initial empty or zero value (e.g. \`$0.00\`, \`0\`, \`Loading...\`, empty string), that means async data hasn't finished loading yet. Use \`browser_wait_for\` to wait up to 10 seconds for the field to update to a real value (for example, wait for the total to show a non-zero amount like \`$799.99\` instead of \`$0.00\`). Once the field shows a real value, THEN call the second \`browser_blueprint\` to capture stable state. If after 10 seconds the field still hasn't updated, skip the assertion on that field — don't capture and assert a value that hasn't loaded.
   If \`browser_navigate\` fails (app not running / connection refused), apply skip condition (a) above: move the intended test to \`additionalRecommendations\` with the failure reason AND record the outage in \`issuesFound\`.
@@ -651,6 +652,8 @@ If a test **execution** (\`skyramp_execute_test\`) fails for a newly generated t
    If you cannot point at the missing or wrong line in application code, the app is not at fault — shared or seeded data, parallel test workers, or setup the test itself never did explain the collision. Treat that as an infrastructure failure: fix it and retry once as in step 3.
 
    **If you did confirm the missing or wrong operation in the source, do NOT make the test pass.** Never add a reset, cleanup, or setup call for isolation. Never weaken the assertion — no \`==\` to \`>=\`, no exact value to a range. A failing test whose diagnosis names a pre-existing bug is the most valuable output of this run; a passing version of it reports nothing.
+
+   **Visual snapshots — maintained tests only, and never a third run.** A newly generated test writes its baseline on its first run and cannot be stale, so this applies to an existing spec whose committed baseline the PR made out of date. That mismatch is known from the \`phase: "before"\` run, and the refresh rides the final run: pass the \`rebaseline_snapshots\` list \`skyramp_actions\` returned as \`rebaselineSnapshots\` on that one call. It never costs an extra execution — if a screenshot mismatch on a maintained test first appears on the final run, report \`Fail\`; do not add a run. The execution result names which baselines were refreshed and which were not; the report row's description carries the refreshed names automatically, so \`afterDetails\` states only the outcome (e.g. \`1 passed in 6.1s\`). If no diff line explains a mismatch, keep the test \`Fail\` and add an \`issuesFound\` entry. Never raise \`maxDiffPixelRatio\`, never remove the \`toHaveScreenshot()\` call, never edit or delete a PNG by hand, and never pass \`rebaselineSnapshots\` for a mismatch the diff does not explain.
 3. Apply a targeted fix and retry **once** only for **infrastructure failures** — that means exactly **2 total \`skyramp_execute_test\` calls per test file** for these cases. Examples of infrastructure failures worth fixing:
    - Assertion mismatch from floating-point precision, or an expected value mis-transcribed from the observed response or computed with an arithmetic slip. If application behavior outside the diff explains the mismatch, it is not an infrastructure failure — use step 2 instead.
    - Import error, syntax error, or missing dependency in the generated test file
@@ -673,7 +676,7 @@ Do not make any changes other than the code-reuse refactoring (step 3 and the ge
 
 **Execution timing:**
 - **beforeStatus** (maintained tests only): execute each maintained test file **once at the start** (before any edits) to capture \`beforeStatus\`. This is the only execution allowed before edits.
-- **Final execution**: Do NOT call \`skyramp_execute_test\` again until ALL maintenance edits AND ALL new test generation/enhancement are complete. Then execute every test file once — maintained files (for \`afterStatus\`) and new files together. **Execute tests SEQUENTIALLY (one at a time)** — do NOT send multiple \`skyramp_execute_test\` calls in the same tool call batch, as concurrent execution overwhelms the stdio transport and causes MCP disconnection. Exclude tests marked \`[external]\`.
+- **Final execution**: Do NOT call \`skyramp_execute_test\` again until ALL maintenance edits AND ALL new test generation/enhancement are complete. Then execute every test file once — maintained files (for \`afterStatus\`) and new files together. For a maintained spec whose \`skyramp_actions\` entry carried \`rebaseline_snapshots\`, pass that exact list as \`rebaselineSnapshots\` on this run and only this run. **Execute tests SEQUENTIALLY (one at a time)** — do NOT send multiple \`skyramp_execute_test\` calls in the same tool call batch, as concurrent execution overwhelms the stdio transport and causes MCP disconnection. Exclude tests marked \`[external]\`.
 - Only report test results for files you actually ran.
 **Auth**: If \`skyramp_analyze_changes\` reports an auth token or \`SKYRAMP_TEST_TOKEN\` is set, pass it in **every** \`skyramp_execute_test\` call from the first attempt — do NOT wait for a 401/403 to discover auth is needed.`;
     }

package/build/services/containerEnv.d.ts

@@ -22,4 +22,4 @@ export declare function isValidEnvVarName(name: string): boolean;
 /**
  * Build the environment variable array for the Docker executor container.
  */
-export declare function buildContainerEnv(options: Pick<TestExecutionOptions, "token" | "language" | "useHostNetwork">, saveStoragePath?: string, hostEnv?: Record<string, string | undefined>, passthroughNames?: string[]): string[];
+export declare function buildContainerEnv(options: Pick<TestExecutionOptions, "token" | "language" | "useHostNetwork" | "rebaselineSnapshots">, saveStoragePath?: string, hostEnv?: Record<string, string | undefined>, passthroughNames?: string[]): string[];

package/build/services/containerEnv.js

@@ -77,6 +77,18 @@ export function buildContainerEnv(options, saveStoragePath, hostEnv = process.en
         ...(options.token ? [`SKYRAMP_TEST_TOKEN=${options.token}`] : []),
         "SKYRAMP_IN_DOCKER=true",
     ];
+    // Visual-snapshot baselines this run replaces (SKYR-4298). SmartPlaywright
+    // reads SKYRAMP_UPDATE_SNAPSHOTS and re-captures each named baseline through
+    // its first-run path instead of comparing. Set here, first-class, because the
+    // SKYRAMP_ prefix is reserved from workspace passthrough below — nothing else
+    // can put it in the container. Omitted entirely when nothing is to refresh, so
+    // the default stays "compare".
+    const rebaseline = (options.rebaselineSnapshots ?? [])
+        .map((n) => n.trim())
+        .filter(Boolean);
+    if (rebaseline.length > 0) {
+        env.push(`SKYRAMP_UPDATE_SNAPSHOTS=${rebaseline.join(",")}`);
+    }
     // Skyramp-generated tests are standalone HTTP tests that never need host repo
     // conftest.py files or pytest configuration. --noconftest prevents loading any
     // conftest in the test directory tree (avoids missing deps like boto3, django).

package/build/tools/executeSkyrampTestTool.d.ts

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { TestExecutionResult } from "../types/TestExecution.js";
 import { TestType } from "../types/TestTypes.js";
+import { MaintenanceActionCore, TestAnalysisResult } from "../types/TestAnalysis.js";
 export declare const CONTRACT_EXECUTION_MODES: readonly ["provider", "consumer"];
 export type ContractExecutionMode = (typeof CONTRACT_EXECUTION_MODES)[number];
 /**
@@ -20,6 +21,16 @@ export declare function shouldInjectSkyrampBaseUrl(testType: TestType, contractM
  * its own attachment line.
  */
 export declare function withVideoInfo(output: string, videoPath?: string): string;
+/**
+ * Normalize the `rebaselineSnapshots` request (SKYR-4298): dedupe and drop blanks,
+ * and refuse it on the pre-edit run. A refresh there would overwrite the very
+ * evidence that the baseline is stale, and `beforeStatus` would read Pass for a
+ * test that failed against the committed image.
+ */
+export declare function resolveRebaselineSnapshots(requested: string[] | undefined, phase: "before" | "after" | undefined): {
+    snapshots: string[];
+    error?: string;
+};
 /**
  * The failure text the agent receives. Everything it needs has to be in here:
  * only a tool's return value reaches the transcript, and Claude Code does not
@@ -37,5 +48,74 @@ export declare function withVideoInfo(output: string, videoPath?: string): strin
  * agent at authentication on a run whose output was empty, and then it keyed off
  * the bare number, which pointed it there on a test count or a line number.
  */
+/** The on-disk files a requested baseline name resolves to; empty when none matches. */
+export type BaselineFileState = Array<{
+    file: string;
+    size: number;
+    mtimeMs: number;
+}>;
+/**
+ * Snapshot of the requested baselines under `<spec>-snapshots/` (SKYR-4298): for
+ * each requested name, every PNG whose name matches the stem (a spec may hold both
+ * `<stem>-linux.png` and `<stem>-chromium-linux.png`; latching onto one of them would
+ * misreport the other) with its size and mtime. Taken before and after the run so
+ * the tool can tell the agent which baselines were actually rewritten — SmartPlaywright
+ * is the only party that knows the exact filename, and an executor image that lacks
+ * SKYRAMP_UPDATE_SNAPSHOTS (or a name matching no toHaveScreenshot call) leaves
+ * every file untouched.
+ */
+export declare function readBaselineState(specFile: string, requested: string[]): Record<string, BaselineFileState>;
+/**
+ * Which requested baselines changed on disk between two readBaselineState calls, and
+ * which files carried the change (the ones to stage).
+ */
+export declare function diffBaselineState(before: Record<string, BaselineFileState>, after: Record<string, BaselineFileState>): {
+    refreshed: string[];
+    notRefreshed: string[];
+    refreshedFiles: Record<string, string[]>;
+};
+/**
+ * Authorize a refresh against the persisted maintenance state (SKYR-4298). The
+ * parameter description tells the agent to pass exactly what skyramp_actions
+ * returned, but prose cannot tell an authorized list from an invented one, so the
+ * tool checks: an UPDATE verdict for this spec must list every requested name, and
+ * the spec's phase:"before" run must already be recorded — a refresh before that
+ * run would overwrite the very evidence that the baseline is stale, whatever
+ * `phase` says or omits. A newly generated test has no verdict and no committed
+ * baseline, so it can never be refreshed here.
+ */
+export declare function authorizeRebaseline(stateData: {
+    existingTests?: TestAnalysisResult[];
+    maintenanceVerdicts?: MaintenanceActionCore[];
+} | null | undefined, testFile: string, requested: string[]): {
+    error?: string;
+};
+/**
+ * Reconcile the persisted verdict with what the executor actually did (SKYR-4298).
+ * An executor image whose @skyramp/skyramp predates SKYRAMP_UPDATE_SNAPSHOTS rewrites
+ * nothing; left alone, the verdict would still promise a refresh, the report gate
+ * would refuse the report, and nothing in the prompt makes the agent's way out
+ * deterministic. So: names that were not refreshed are dropped from the verdict; a
+ * rebaseline-only UPDATE with nothing left becomes VERIFY (the test stays red, the
+ * rationale says why), and an UPDATE that also carried edits keeps UPDATE and is
+ * held to its edit. The report then reflects what happened, not what was asked.
+ */
+export declare function applyRefreshOutcomeToVerdicts(verdicts: MaintenanceActionCore[], testFile: string, outcome: {
+    refreshed: string[];
+    notRefreshed: string[];
+}, executorImage: string): {
+    verdicts: MaintenanceActionCore[];
+    note?: string;
+};
+/**
+ * The refresh outcome line appended to the execution result, on pass and on fail
+ * alike. Without it a stale-baseline run that could not refresh reads as a bare
+ * "Screenshot comparison failed", and the report gate then tells the agent to run
+ * with rebaselineSnapshots set — which it already did.
+ */
+export declare function describeRefreshOutcome(outcome: {
+    refreshed: string[];
+    notRefreshed: string[];
+}): string;
 export declare function buildExecutionFailureText(result: TestExecutionResult): string;
 export declare function registerExecuteSkyrampTestTool(server: McpServer): void;