@skyramp/mcp 0.3.8 → 0.3.9-rc.1

package/build/tools/executeSkyrampTestTool.js

@@ -11,10 +11,14 @@ import { TestExecutionStatus, } from "../types/TestExecution.js";
 import { getWorkspaceBaseUrl } from "../utils/workspaceAuth.js";
 import { ProgrammingLanguage, TestType } from "../types/TestTypes.js";
 import { StateManager, getTestsRepoDir, } from "../utils/AnalysisStateManager.js";
-import { TestSource } from "../types/TestAnalysis.js";
+import { DriftAction, TestSource } from "../types/TestAnalysis.js";
 import { logger } from "../utils/logger.js";
 import { toolError } from "../utils/utils.js";
 import { recordExecutionVideo } from "./execution-video-state.js";
+import { stageGeneratedPaths } from "../utils/gitStaging.js";
+import * as fs from "fs";
+import { baselineFileMatchesStem, baselineStem, rebaselineSnapshotNameSchema, snapshotDirFor, } from "../utils/rebaselineSnapshots.js";
+import { EXECUTOR_DOCKER_IMAGE } from "../utils/versions.js";
 const TOOL_NAME = "skyramp_execute_test";
 export const CONTRACT_EXECUTION_MODES = ["provider", "consumer"];
 /**
@@ -97,22 +101,172 @@ const HTTP_401_SHAPES = [
     /\bwhere\s+401\s*=/i,
 ];
 /**
- * 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
- * capture an MCP server's stderr, so anything this omits is unrecoverable once
- * the run ends.
- *
- * `output` alone was not enough. When the executor produced none, the message
- * read "Test execution failed:" and stopped — so the agent inferred a cause and
- * reported it as fact. Measured in eval run 32220788735: it blamed an
- * unreachable backend while the app was answering 200 on both the host and the
- * docker bridge, and that invented cause reached `issuesFound`.
- *
- * The 401 hint is emitted only when the output carries a 401 in a status-shaped
- * position — see HTTP_401_SHAPES. It used to be unconditional, which pointed the
- * 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.
+ * 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 function resolveRebaselineSnapshots(requested, phase) {
+    const snapshots = [
+        ...new Set((requested ?? []).map((s) => s.trim()).filter(Boolean)),
+    ];
+    if (snapshots.length > 0 && phase === "before") {
+        return {
+            snapshots: [],
+            error: `rebaselineSnapshots cannot be combined with phase: "before". Run the pre-edit baseline without it to record the mismatch, then pass rebaselineSnapshots on the final run only.`,
+        };
+    }
+    return { snapshots };
+}
+/**
+ * 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 function readBaselineState(specFile, requested) {
+    const dir = snapshotDirFor(specFile);
+    let entries = [];
+    try {
+        entries = fs.readdirSync(dir).sort();
+    }
+    catch {
+        entries = [];
+    }
+    const state = {};
+    for (const name of requested) {
+        const stem = baselineStem(name);
+        const files = [];
+        for (const file of entries.filter((e) => baselineFileMatchesStem(e, stem))) {
+            try {
+                const st = fs.statSync(path.join(dir, file));
+                files.push({ file, size: st.size, mtimeMs: st.mtimeMs });
+            }
+            catch {
+                // vanished between readdir and stat — treat as absent
+            }
+        }
+        state[name] = files;
+    }
+    return state;
+}
+/**
+ * Which requested baselines changed on disk between two readBaselineState calls, and
+ * which files carried the change (the ones to stage).
+ */
+export function diffBaselineState(before, after) {
+    const refreshed = [];
+    const notRefreshed = [];
+    const refreshedFiles = {};
+    for (const name of Object.keys(after)) {
+        const prev = new Map((before[name] ?? []).map((f) => [f.file, f]));
+        const changed = after[name]
+            .filter((a) => {
+            const b = prev.get(a.file);
+            return !b || a.size !== b.size || a.mtimeMs !== b.mtimeMs;
+        })
+            .map((a) => a.file);
+        if (changed.length > 0) {
+            refreshed.push(name);
+            refreshedFiles[name] = changed;
+        }
+        else {
+            notRefreshed.push(name);
+        }
+    }
+    return { refreshed, notRefreshed, refreshedFiles };
+}
+/**
+ * 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 function authorizeRebaseline(stateData, testFile, requested) {
+    if (requested.length === 0)
+        return {};
+    const verdict = (stateData?.maintenanceVerdicts ?? []).find((v) => v.testFilePath === testFile && v.action === DriftAction.Update);
+    if (!verdict) {
+        return {
+            error: `rebaselineSnapshots refused: no UPDATE verdict for ${testFile} in the stateFile. Only a maintained test whose skyramp_analyze_test_health verdict listed the baselines can be refreshed — a newly generated test writes its own baseline on its first run and has nothing to refresh.`,
+        };
+    }
+    const authorized = new Set(verdict.rebaselineSnapshots ?? []);
+    const unauthorized = requested.filter((n) => !authorized.has(n));
+    if (unauthorized.length > 0) {
+        return {
+            error: `rebaselineSnapshots refused: ${unauthorized.join(", ")} not in the UPDATE verdict for ${path.basename(testFile)} (authorized: ${authorized.size ? [...authorized].join(", ") : "none"}). Pass exactly the rebaseline_snapshots skyramp_actions returned, using the name the test passes to toHaveScreenshot (page-001.png), not the on-disk file (page-001-chromium-linux.png).`,
+        };
+    }
+    const entry = (stateData?.existingTests ?? []).find((t) => t.testFile === testFile);
+    if (!entry?.executionBefore) {
+        return {
+            error: `rebaselineSnapshots refused: no phase: "before" execution is recorded for ${path.basename(testFile)}. Run the pre-edit baseline first (it is the evidence the baseline is stale), then pass rebaselineSnapshots on the final run.`,
+        };
+    }
+    return {};
+}
+/**
+ * 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 function applyRefreshOutcomeToVerdicts(verdicts, testFile, outcome, executorImage) {
+    if (outcome.notRefreshed.length === 0)
+        return { verdicts };
+    let note;
+    const next = verdicts.map((v) => {
+        if (v.testFilePath !== testFile || v.action !== DriftAction.Update)
+            return v;
+        const remaining = (v.rebaselineSnapshots ?? []).filter((n) => !outcome.notRefreshed.includes(n));
+        const reason = `baseline refresh of ${outcome.notRefreshed.join(", ")} was not applied by ${executorImage} (its @skyramp/skyramp lacks SKYRAMP_UPDATE_SNAPSHOTS, or the name matches no toHaveScreenshot call)`;
+        if (remaining.length === 0 && v.rebaselineOnly) {
+            note = `Verdict for ${path.basename(testFile)} downgraded UPDATE → VERIFY: ${reason}. The test stays as it is; report it honestly.`;
+            const { rebaselineSnapshots: _dropped, rebaselineOnly: _only, ...rest } = v;
+            void _dropped;
+            void _only;
+            return { ...rest, action: DriftAction.Verify, rationale: `${v.rationale} [${reason}]` };
+        }
+        note = `Verdict for ${path.basename(testFile)}: ${reason}; the UPDATE is held to its spec/POM edit only.`;
+        const { rebaselineSnapshots: _dropped, ...rest } = v;
+        void _dropped;
+        return {
+            ...rest,
+            ...(remaining.length > 0 ? { rebaselineSnapshots: remaining } : {}),
+            rationale: `${v.rationale} [${reason}]`,
+        };
+    });
+    return { verdicts: next, note };
+}
+/**
+ * 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 function describeRefreshOutcome(outcome) {
+    const parts = [];
+    if (outcome.refreshed.length > 0) {
+        parts.push(`Visual baselines refreshed: ${outcome.refreshed.join(", ")}.`);
+    }
+    if (outcome.notRefreshed.length > 0) {
+        parts.push(`Visual baselines NOT refreshed: ${outcome.notRefreshed.join(", ")} — the executor image may lack SKYRAMP_UPDATE_SNAPSHOTS support (needs @skyramp/skyramp with SKYR-4298), or the name matches no toHaveScreenshot() call in this spec. Do not report these as refreshed.`);
+    }
+    return parts.join(" ");
+}
 export function buildExecutionFailureText(result) {
     const output = stripVTControlCharacters(result.output || "").trim();
     const facts = [`status=${result.status}`];
@@ -199,8 +353,14 @@ export function registerExecuteSkyrampTestTool(server) {
                 .describe("Path to state file from skyramp_analyze_changes. Always pass when available — results are written back so skyramp_submit_report can override before/afterStatus with ground-truth pass/fail."),
             phase: z
                 .enum(["before", "after"])
-                .optional()
+                .default("after")
                 .describe("Execution phase for maintained tests: 'before' captures pre-edit baseline; 'after' (default) records post-edit result."),
+            rebaselineSnapshots: z
+                .array(rebaselineSnapshotNameSchema)
+                .optional()
+                .describe("UI tests only. toHaveScreenshot() baseline filenames (e.g. [\"page-001.png\"]) this run REPLACES instead of comparing against, because the PR intentionally changed how the captured page/element/region looks (SKYR-4298). " +
+                "Pass exactly the list skyramp_actions returned as rebaseline_snapshots for this spec — the tool checks it against the persisted UPDATE verdict in stateFile (so stateFile is required) and refuses names the verdict did not authorize, a spec with no such verdict, or a spec whose phase: 'before' run has not been recorded yet. Use the name as the test passes it (page-001.png), not the on-disk file (page-001-chromium-linux.png). " +
+                "The refreshed PNGs land beside the spec and are delivered with the Testbot PR as image diffs; the result names which baselines were refreshed and which were not. Never use this to silence a screenshot mismatch the diff does not explain."),
             repository: z
                 .string()
                 .optional()
@@ -227,6 +387,24 @@ export function registerExecuteSkyrampTestTool(server) {
                 errorResult = toolError(`testFile must be an absolute path, got: ${params.testFile}`);
                 return errorResult;
             }
+            const rebaseline = resolveRebaselineSnapshots(params.rebaselineSnapshots, params.phase);
+            if (rebaseline.error) {
+                errorResult = toolError(rebaseline.error);
+                return errorResult;
+            }
+            const rebaselineSnapshots = rebaseline.snapshots;
+            if (rebaselineSnapshots.length > 0) {
+                if (!params.stateFile) {
+                    errorResult = toolError("rebaselineSnapshots requires stateFile: the refresh is authorized against the UPDATE verdict skyramp_actions persisted there.");
+                    return errorResult;
+                }
+                const authState = await StateManager.fromStatePath(params.stateFile).readRepoData(params.repository);
+                const auth = authorizeRebaseline(authState, params.testFile, rebaselineSnapshots);
+                if (auth.error) {
+                    errorResult = toolError(auth.error);
+                    return errorResult;
+                }
+            }
             // Deterministic external-test guard (SKYR-3924): this tool runs Skyramp-generated
             // tests in the executor and cannot run a repo's native (user-written) suite, so a
             // run on an external test only errors (e.g. pytest import/collection failure).
@@ -343,7 +521,13 @@ export function registerExecuteSkyrampTestTool(server) {
                 playwrightSaveStoragePath: params.playwrightSaveStoragePath,
                 dockerNetwork,
                 useHostNetwork: false,
+                ...(rebaselineSnapshots.length > 0 ? { rebaselineSnapshots } : {}),
             };
+            // Identity of the requested baselines before the run, to report afterwards
+            // which ones SmartPlaywright actually rewrote (SKYR-4298).
+            const baselinesBefore = rebaselineSnapshots.length > 0
+                ? readBaselineState(params.testFile, rebaselineSnapshots)
+                : {};
             let result;
             try {
                 result = await executionService.executeTest(execOptions, onExecutionProgress);
@@ -396,10 +580,53 @@ export function registerExecuteSkyrampTestTool(server) {
             // populate testResults[].videoPath — testbot uploads only the video
             // directories the report references, so an unrecorded video is never seen.
             await recordExecutionVideo(result, params.stateFile);
+            // Which requested baselines were actually rewritten (SKYR-4298). Reported on
+            // pass and fail alike; a refreshed PNG is a deliverable like a generated
+            // spec, so stage the spec's snapshot directory whenever one was rewritten —
+            // even on a failing run, since the report gate checks the PNG, not the
+            // status — so the eval harness commit and the artifact collector see it
+            // (production delivery adds the whole test directory anyway). No-op outside
+            // a testbot run, like every other stageGeneratedPaths call; never fails the
+            // execution.
+            let refreshOutcomeText = "";
+            if (rebaselineSnapshots.length > 0) {
+                const after = readBaselineState(params.testFile, rebaselineSnapshots);
+                const outcome = diffBaselineState(baselinesBefore, after);
+                refreshOutcomeText = describeRefreshOutcome(outcome);
+                // Stage the rewritten files themselves, never the directory: `git add` on
+                // the directory would ship anything else sitting there under one
+                // authorized baseline's authority.
+                for (const name of outcome.refreshed) {
+                    for (const file of outcome.refreshedFiles[name] ?? []) {
+                        try {
+                            await stageGeneratedPaths(path.join(snapshotDirFor(params.testFile), file));
+                        }
+                        catch (err) {
+                            logger.warning(`Could not stage refreshed visual baseline ${file} for ${params.testFile}: ${err.message}`);
+                        }
+                    }
+                }
+                if (outcome.notRefreshed.length > 0 && params.stateFile) {
+                    try {
+                        const stateManager = StateManager.fromStatePath(params.stateFile);
+                        const stateData = await stateManager.readRepoData(params.repository);
+                        if (stateData?.maintenanceVerdicts) {
+                            const reconciled = applyRefreshOutcomeToVerdicts(stateData.maintenanceVerdicts, params.testFile, outcome, EXECUTOR_DOCKER_IMAGE);
+                            await stateManager.writeRepoData({ ...stateData, maintenanceVerdicts: reconciled.verdicts }, { repo: params.repository });
+                            if (reconciled.note)
+                                refreshOutcomeText += ` ${reconciled.note}`;
+                        }
+                    }
+                    catch (err) {
+                        logger.warning(`Could not reconcile the maintenance verdict with the refresh outcome: ${err.message}`);
+                    }
+                }
+            }
+            const withRefreshOutcome = (text) => refreshOutcomeText ? `${text}\n\n${refreshOutcomeText}` : text;
             // Progress is already reported by TestExecutionService
             // Only report final status if not already at 100%
             if (result.status !== TestExecutionStatus.Pass) {
-                errorResult = toolError(withVideoInfo(buildExecutionFailureText(result), result.videoPath));
+                errorResult = toolError(withRefreshOutcome(withVideoInfo(buildExecutionFailureText(result), result.videoPath)));
                 return errorResult;
             }
             // Success - progress already reported by TestExecutionService
@@ -407,7 +634,7 @@ export function registerExecuteSkyrampTestTool(server) {
                 content: [
                     {
                         type: "text",
-                        text: withVideoInfo(`Test execution result: ${stripVTControlCharacters(result.output || "")}`, result.videoPath),
+                        text: withRefreshOutcome(withVideoInfo(`Test execution result: ${stripVTControlCharacters(result.output || "")}`, result.videoPath)),
                     },
                 ],
             };

package/build/tools/submitReportTool.d.ts

@@ -101,8 +101,8 @@ export declare const newTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     description: string;
     testType: TestType;
     category: "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
-    fileName: string;
     endpoint: string;
+    fileName: string;
     testId: string;
     reasoning: string;
     repository?: string | undefined;
@@ -125,8 +125,8 @@ export declare const newTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
 }, {
     description: string;
     testType: TestType;
-    fileName: string;
     endpoint: string;
+    fileName: string;
     testId: string;
     reasoning: string;
     repository?: string | undefined;
@@ -151,8 +151,8 @@ export declare const newTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     description: string;
     testType: TestType;
     category: "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
-    fileName: string;
     endpoint: string;
+    fileName: string;
     testId: string;
     reasoning: string;
     repository?: string | undefined;
@@ -175,8 +175,8 @@ export declare const newTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
 }, {
     description: string;
     testType: TestType;
-    fileName: string;
     endpoint: string;
+    fileName: string;
     testId: string;
     reasoning: string;
     repository?: string | undefined;
@@ -201,8 +201,8 @@ export declare const newTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     description: string;
     testType: TestType;
     category: "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
-    fileName: string;
     endpoint: string;
+    fileName: string;
     testId: string;
     reasoning: string;
     repository?: string | undefined;

package/build/tools/submitReportTool.js

@@ -1021,7 +1021,11 @@ export function registerSubmitReportTool(server) {
             testType: v.testType,
             endpoint: v.endpoint,
             action: v.action,
-            description: v.rationale,
+            // A baseline refresh (SKYR-4298) leaves the spec untouched, so name the
+            // replaced PNGs here — the reviewer's cue to open the image diff in the PR.
+            description: v.rebaselineSnapshots?.length
+                ? `${v.rationale} (visual baseline refreshed: ${v.rebaselineSnapshots.join(", ")})`
+                : v.rationale,
             beforeDetails: "",
             afterDetails: "",
         }));

package/build/tools/test-management/actionsTool.js

@@ -8,7 +8,8 @@ import * as path from "path";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { dualChannelResult, toolError } from "../../utils/utils.js";
 import { isTestFile } from "../../prompts/test-recommendation/scopeAssessment.js";
-import { buildRenameStrategy, buildFileRenameStrategy, buildUpdateStrategy, buildRegenerateStrategy, buildDeleteStrategy, buildUpdateFileInstruction, buildRegenerateFileInstruction, } from "../../prompts/test-maintenance/actionsInstructions.js";
+import { REBASELINE_SNAPSHOT_NAME_RE, looksLikeOnDiskBaselineName } from "../../utils/rebaselineSnapshots.js";
+import { buildRenameStrategy, buildFileRenameStrategy, buildUpdateStrategy, buildRebaselineStrategy, buildRegenerateStrategy, buildDeleteStrategy, buildUpdateFileInstruction, buildRegenerateFileInstruction, } from "../../prompts/test-maintenance/actionsInstructions.js";
 /**
  * Compute a suggested new filename when an endpoint is renamed.
  */
@@ -102,6 +103,15 @@ const recommendationSchema = z.object({
         .optional()
         .describe("For a large UPDATE file, the concrete per-site edits you already located while reading it — one entry per place that must change, with a verbatim anchor. " +
         "Surfaced to the apply step as a checklist so it edits each site directly instead of re-grepping/re-paging the file. Provide this whenever an UPDATE touches more than a couple of sites."),
+    rebaselineSnapshots: z
+        // Loose here on purpose: one malformed name must not reject the whole batch and
+        // lose every other verdict. Entries are validated per item below; invalid ones
+        // are dropped and surfaced in the response.
+        .array(z.string())
+        .optional()
+        .describe("UPDATE only — the toHaveScreenshot() baseline filenames (e.g. [\"page-001.png\"]) whose captured page/element/region the diff visibly changed, so the committed PNG is stale (SKYR-4298). " +
+        "List only the baselines the change reaches; leave unaffected ones out. These are refreshed at the final skyramp_execute_test run via its rebaselineSnapshots parameter, never by editing the assertion, its maxDiffPixelRatio, or the PNG. " +
+        "Omit when the diff does not explain a screenshot mismatch — that failure stays red."),
     renamedEndpoints: z
         .array(z.object({
         oldPath: z.string().describe("Previous endpoint path"),
@@ -182,6 +192,7 @@ export function registerActionsTool(server) {
             // and passes results here directly — analyzeTestHealthTool never writes assessment
             // data back to the state file.
             const recommendations = [];
+            const droppedRebaselineNotes = [];
             (args.recommendations ?? []).forEach((rec) => {
                 // Schema requires absolute paths; resolve any relative paths defensively
                 // against repoRoot in case the LLM sends a relative path despite the schema.
@@ -294,6 +305,26 @@ export function registerActionsTool(server) {
                         resolvedPomFile = undefined;
                     }
                 }
+                if (rec.action !== DriftAction.Update && rec.rebaselineSnapshots?.length) {
+                    droppedRebaselineNotes.push(`${rec.testFilePath}: rebaselineSnapshots [${rec.rebaselineSnapshots.join(", ")}] ignored on ${rec.action} — a baseline refresh is only meaningful on UPDATE.`);
+                }
+                // Per-entry validation (the schema is deliberately loose, see above).
+                const validBaselines = [];
+                for (const raw of rec.rebaselineSnapshots ?? []) {
+                    const name = raw.trim();
+                    if (!REBASELINE_SNAPSHOT_NAME_RE.test(name)) {
+                        droppedRebaselineNotes.push(`${rec.testFilePath}: rebaselineSnapshots entry ${JSON.stringify(raw)} dropped — must be the bare .png name the test passes to toHaveScreenshot(), e.g. "page-001.png" (no path, commas, or whitespace).`);
+                        continue;
+                    }
+                    if (looksLikeOnDiskBaselineName(name)) {
+                        // Kept — a test can legitimately pass a name like this — but flagged: the
+                        // on-disk file carries Playwright's project/platform suffix, and passing it
+                        // by mistake refreshes nothing (the execution result will say NOT refreshed).
+                        droppedRebaselineNotes.push(`${rec.testFilePath}: rebaselineSnapshots entry "${name}" kept but looks like an on-disk filename (Playwright's project/platform suffix). If the test passes "${name.replace(/-(?:[^-]+-)?(?:darwin|linux|win32)\.png$/i, ".png")}" to toHaveScreenshot(), pass that instead.`);
+                    }
+                    if (!validBaselines.includes(name))
+                        validBaselines.push(name);
+                }
                 recommendations.push({
                     testFilePath: resolvedFile,
                     pomFile: resolvedPomFile,
@@ -306,6 +337,19 @@ export function registerActionsTool(server) {
                     updateInstructions: rec.updateInstructions ?? "",
                     renamedEndpoints: rec.renamedEndpoints ?? [],
                     ...(rec.editSites?.length ? { editSites: rec.editSites } : {}),
+                    // Only an UPDATE refreshes a baseline. A REGENERATEd spec that reuses a
+                    // baseline name still compares against the committed PNG, and DELETE
+                    // removes the spec — neither is a refresh, so the list is dropped (and
+                    // surfaced in the response below rather than silently discarded).
+                    ...(rec.action === DriftAction.Update && validBaselines.length
+                        ? {
+                            rebaselineSnapshots: validBaselines,
+                            // No updateInstructions → the refresh is the whole maintenance and
+                            // the report gate must not expect a spec/POM edit. With
+                            // updateInstructions the gate holds the UPDATE to both.
+                            rebaselineOnly: !rec.updateInstructions,
+                        }
+                        : {}),
                 });
             });
             // Derive the no-action set here instead of asking the LLM to enumerate it.
@@ -340,6 +384,11 @@ export function registerActionsTool(server) {
                         rationale: r.rationale,
                         testType: r.testType,
                         endpoint: r.endpoint,
+                        // Persisted so the report-time working-tree check knows this UPDATE's
+                        // change is the refreshed PNG, not the spec (SKYR-4298).
+                        ...(r.rebaselineSnapshots?.length
+                            ? { rebaselineSnapshots: r.rebaselineSnapshots, rebaselineOnly: r.rebaselineOnly === true }
+                            : {}),
                     })),
                 }, { repo: args.repository, repositoryPath, step: "actions" });
             }
@@ -449,6 +498,7 @@ export function registerActionsTool(server) {
                     suggestedNewFile,
                     updateInstructions: rec.updateInstructions,
                     rationale: rec.rationale,
+                    rebaselineSnapshots: rec.rebaselineSnapshots,
                 }));
             }
             // ── REGENERATE: emit overwrite instructions ──
@@ -500,6 +550,10 @@ export function registerActionsTool(server) {
                 deleteRecommendations.length === 0) {
                 sections.push(`No action required. All existing tests appear healthy.`);
             }
+            if (droppedRebaselineNotes.length > 0) {
+                sections.push(`## rebaselineSnapshots notes (${droppedRebaselineNotes.length})\n\n` +
+                    droppedRebaselineNotes.map((n) => `- ${n}`).join("\n"));
+            }
             sections.push(`**This tool is currently in Early Preview stage. Please verify the results.**`);
             const responseText = sections.join("\n\n");
             // ── Build LLM instructions ──
@@ -534,18 +588,32 @@ export function registerActionsTool(server) {
             // Update context: per-file guidance + current content for the downstream LLM.
             // Including file content avoids re-reads on each Edit turn, reducing token usage.
             const updateContext = updateRecommendations
-                .filter((rec) => !!rec.updateInstructions)
+                .filter((rec) => !!rec.updateInstructions || !!rec.rebaselineSnapshots?.length)
                 .map((rec) => {
                 const editTarget = rec.pomFile ?? rec.testFilePath;
+                const hasEdit = !!rec.updateInstructions;
                 return {
                     file: editTarget,
-                    context: rec.updateInstructions,
+                    // A rebaseline-only entry has nothing to edit: no context, and an
+                    // explicit edit_required: false so the strategy's "make the changes
+                    // described in context" cannot apply to it (rationale is always set,
+                    // so it must not stand in for edit instructions here).
+                    ...(hasEdit ? { context: rec.updateInstructions } : { edit_required: false }),
                     ...(rec.editSites?.length ? { edit_sites: rec.editSites } : {}),
+                    // The baselines to pass as skyramp_execute_test's rebaselineSnapshots for
+                    // the SPEC (testFilePath, which is what runs) — never `file`, which is
+                    // the page object for a POM-backed UPDATE.
+                    ...(rec.rebaselineSnapshots?.length
+                        ? { spec_file: rec.testFilePath, rebaseline_snapshots: rec.rebaselineSnapshots }
+                        : {}),
                 };
             });
             if (updateContext.length > 0) {
                 llmInstructionsObj.update_context = updateContext;
                 llmInstructionsObj.update_strategy = buildUpdateStrategy();
+                if (updateContext.some((u) => "rebaseline_snapshots" in u)) {
+                    llmInstructionsObj.rebaseline_strategy = buildRebaselineStrategy();
+                }
             }
             // REGENERATE context: existing file content gives the generation tool the
             // endpoint URL, auth pattern, test type, and language to replicate.

package/build/tools/test-management/analyzeChangesTool.d.ts

@@ -6,6 +6,7 @@ import type { FrontendFileIntegration } from "../../types/FrontendIntegration.js
 import { TraceFile } from "../../types/RepositoryAnalysis.js";
 import { BranchDiffData } from "../../utils/branchDiff.js";
 import { ScannedEndpoint } from "../../utils/repoScanner.js";
+import { RemovedUiElement } from "../../utils/removedUiElements.js";
 import { TraceParseResult } from "../../utils/trace-parser.js";
 /** Exported for testing: maps a parsed trace result to a TraceFile. */
 export declare function buildTraceFileEntry(tracePath: string, result: TraceParseResult): TraceFile;
@@ -28,6 +29,15 @@ export declare const analyzeChangesInputSchema: {
 export declare const NO_UI_INSTRUCTIONS = "No UI changes detected \u2014 no blueprint capture needed.";
 export declare const NO_RESOLVABLE_URLS_INSTRUCTIONS = "Frontend changes detected but no candidate URLs could be resolved (no route files matched the changed files or their importers, and no frontend baseUrl to fall back to). UI recommendations will be source-grounded only.";
 export declare function buildCaptureInstructions(pages: CandidateUiPage[]): string;
+/**
+ * Instruction block for data-testids the diff removed from pages that survive
+ * (SKYR-4305). The UI analog of the `[removed]` endpoint 404 guard: one UI
+ * candidate per element, asserting the element is gone plus a positive check on a
+ * retained element of the same page. Whole-feature removals never reach here —
+ * collectRemovedUiElements drops elements whose file was deleted or whose page
+ * could not be resolved.
+ */
+export declare function buildRemovedElementsInstructions(elements: RemovedUiElement[]): string;
 /**
  * Instruction block for changed frontend files the server determined have no
  * production importer (SKYR-3855) — dead/orphaned components. Used both to