@skyramp/mcp 0.3.7 → 0.3.9-rc.1

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

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

@@ -33,6 +33,7 @@ import { detectProjectMetadata } from "../../utils/projectMetadata.js";
 import { draftScenariosFromEndpoints, draftResponseShapeScenarios, capScenarios } from "../../utils/scenarioDrafting.js";
 import { mapUnmatchedFilesToImporterEndpoints, buildHopResponseShapeInputs, deriveResourceTokensForFile, deriveResourceToken, extractChangedSymbols, sliceDiffByFile } from "../../utils/importerHop.js";
 import { extractChangedSelectors, MAX_CHANGED_SELECTORS } from "../../utils/frontendSelectors.js";
+import { collectRemovedUiElements, MAX_REMOVED_UI_ELEMENTS } from "../../utils/removedUiElements.js";
 import { buildAnalysisOutputText } from "../../prompts/test-recommendation/analysisOutputPrompt.js";
 import { parseTraceFile, discoverTraceFiles, discoverPlaywrightZips, } from "../../utils/trace-parser.js";
 import { TestSource } from "../../types/TestAnalysis.js";
@@ -359,6 +360,39 @@ If a candidate URL 404s or redirects unexpectedly, navigate from the frontend ba
 
 If \`browser_blueprint\` fails on every candidate URL (app unreachable, all 404s), proceed and log an \`issuesFound\` info entry. Recommendations will be source-grounded; non-UI work is unaffected.`;
 }
+/**
+ * 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 function buildRemovedElementsInstructions(elements) {
+    const byPage = new Map();
+    for (const e of elements) {
+        for (const url of e.pageUrls) {
+            if (!byPage.has(url))
+                byPage.set(url, []);
+            byPage.get(url).push(e);
+        }
+    }
+    const target = (e) => e.attribute === "data-testid" ? `testId: "${e.value}"` : `attribute: "${e.attribute}", value: "${e.value}"`;
+    const pageLines = [...byPage.entries()]
+        .map(([url, els], i) => `  ${i + 1}. ${url}\n` + els.map((e) => `       - \`${e.attribute}="${e.value}"\`  (removed from ${e.file}; browser_assert_hidden target: ${target(e)})`).join("\n"))
+        .join("\n");
+    const capNote = elements.length >= MAX_REMOVED_UI_ELEMENTS
+        ? `\n(The list is capped at ${MAX_REMOVED_UI_ELEMENTS} elements; the analyze log records how many were dropped.)`
+        : "";
+    return `**Removed UI elements — grounding for the removal test.** This diff deletes the elements below (identified by a \`data-*\` attribute) from pages that still exist after the change. The budget rule already requires a test asserting a removed element is absent; this list tells you WHICH elements and on WHICH page, which no blueprint can (the elements are gone). Renames, moved/extracted elements, elements in deleted files, files with no production importer, and values an existing test already references were filtered out server-side; the page is attributed through the import graph (the file, or one hop via the files that import it), not observed.
+
+**Removed elements by page:**
+${pageLines}${capNote}
+
+**How to record (Task 2), per page — not per element:** if the plan already has a UI candidate on that page, record the guard inside that trace; otherwise register ONE UI candidate \`verify-removed-ui-<page-slug>\` (\`testType: "ui"\`, category \`breaking_change\`; \`skyramp_register_test_plan\` requires at least one step, so use a placeholder \`GET <page path>\` → 200). \`browser_navigate\` to the page and let the app render, then one \`browser_assert_hidden\` call per element using the target shown above — \`testId\` when the attribute is \`data-testid\`, otherwise \`attribute\` + \`value\` (the generated test then uses \`getByTestId(...)\` or \`page.locator('[data-cy="..."]')\` respectively; no \`ref\` — a removed element has no snapshot ref; 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 — the generated \`toBeHidden()\` assertions must never stand alone. Then \`skyramp_export_zip\` and \`skyramp_ui_test_generation\` as usual.
+
+**Blueprint Citation for these recommendations:** the removed elements will not appear in any blueprint you capture — that is expected. For a \`data-testid\` element set \`targetElements[].testId\` to the value; for any other attribute leave \`testId\` null and name the \`attribute="value"\` pair in \`reasoning\`. Take \`role\`/\`accessibleName\` from the deleted JSX in the diff, set \`pageContext.url\` to the page above, and prefix the recommendation's \`reasoning\` with \`[removed-element]\`.`;
+}
 /**
  * Instruction block for changed frontend files the server determined have no
  * production importer (SKYR-3855) — dead/orphaned components. Used both to
@@ -775,6 +809,7 @@ export function registerAnalyzeChangesTool(server) {
             }
             let existingTests = [];
             let discoveredRelevantExternalPaths = [];
+            let testDiscoveryFailed = false;
             try {
                 const testDiscoveryService = new TestDiscoveryService();
                 // Run-scoped: only the primary call carries testsRepoDir, so never
@@ -799,6 +834,7 @@ export function registerAnalyzeChangesTool(server) {
                 });
             }
             catch (err) {
+                testDiscoveryFailed = true;
                 logger.warning("Test discovery failed, continuing with empty list", {
                     error: err instanceof Error ? err.message : String(err),
                 });
@@ -1379,10 +1415,44 @@ export function registerAnalyzeChangesTool(server) {
                 // the pages that import them.
                 const frontendFileIntegration = checkFrontendFileIntegration(params.repositoryPath, changedFrontendFiles);
                 const candidateUiPages = await enumerateCandidateUiPages(params.repositoryPath, changedFrontendFiles, frontendFileIntegration);
+                // SKYR-4305: data-testids the diff removed from a page that survives —
+                // grounding for the removal test the budget rule requires (a removed
+                // element appears in no blueprint). Purely additive: a failure here must
+                // never cost the analyze call.
+                let removedElements = [];
+                if (diffData?.diffContent) {
+                    try {
+                        removedElements = collectRemovedUiElements({
+                            changedFrontendFiles,
+                            deletedFiles: diffData.deletedFiles ?? [],
+                            diffByFile: getDiffByFile(),
+                            frontendFileIntegration,
+                            candidateUiPages,
+                            existingTestFiles: [
+                                ...existingTests.map((t) => t.testFile),
+                                ...discoveredRelevantExternalPaths,
+                            ],
+                            discoveryFailed: testDiscoveryFailed,
+                        });
+                    }
+                    catch (err) {
+                        logger.warning("removedUiElements: collection failed, continuing without removal-guard grounding", {
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                        removedElements = [];
+                    }
+                }
+                if (removedElements.length > 0) {
+                    logger.info("Removed UI elements detected (removal-guard grounding)", {
+                        count: removedElements.length,
+                        removed: removedElements.map((e) => `${e.attribute}="${e.value}"`),
+                    });
+                }
                 return {
                     changedFrontendFiles,
                     candidateUiPages,
                     frontendFileIntegration,
+                    ...(removedElements.length > 0 ? { removedElements } : {}),
                 };
             })();
             // Derive the UI blueprint-capture instructions the agent acts on after
@@ -1407,6 +1477,9 @@ export function registerAnalyzeChangesTool(server) {
                         : buildCaptureInstructions(uiContext.candidateUiPages)) +
                         (unintegratedFrontendFiles.length > 0
                             ? `\n\n${buildUnintegratedInstructions(unintegratedFrontendFiles)}`
+                            : "") +
+                        (uiContext.removedElements?.length
+                            ? `\n\n${buildRemovedElementsInstructions(uiContext.removedElements)}`
                             : "");
             // ── SKYR-3879 Path B: budget context + pre-seeded approved plan ──
             // Computed BEFORE the state write (not after, alongside the

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

@@ -6,7 +6,7 @@ import { ChangedRoute } from "../../utils/changedRoutes.js";
 declare const registerCandidateSchema: z.ZodObject<{
     scenarioName: z.ZodString;
     description: z.ZodString;
-    category: z.ZodEnum<["new_endpoint", "bug_caught", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>;
+    category: z.ZodEnum<["new_endpoint", "bug_caught", "requirement_conflict", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>;
     priority: z.ZodEnum<["high", "medium", "low"]>;
     testType: z.ZodEffects<z.ZodNativeEnum<typeof TestType>, TestType, TestType>;
     steps: z.ZodArray<z.ZodObject<{
@@ -124,7 +124,7 @@ declare const registerCandidateSchema: z.ZodObject<{
     priority: "high" | "medium" | "low";
     testType: TestType;
     scenarioName: string;
-    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
     steps: {
         path: string;
         method: HttpMethod;
@@ -160,7 +160,7 @@ declare const registerCandidateSchema: z.ZodObject<{
     priority: "high" | "medium" | "low";
     testType: TestType;
     scenarioName: string;
-    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
     steps: {
         path: string;
         method: HttpMethod;

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

@@ -12,7 +12,7 @@ import { CandidateSource, computeCandidateId, scenarioMergeKey, DiscriminatorKin
 import { selectPlan } from "../../recommendation/planRanker.js";
 import { resolveSubjectEndpoints } from "../../utils/subjectEndpoints.js";
 import { collectChangedRouteLines } from "../../utils/changedRoutes.js";
-import { reservedUISlots } from "../../recommendation/budgeters/shared.js";
+import { generateFloors } from "../../recommendation/budgeters/shared.js";
 import { inferScenarioType } from "../../recommendation/diversity.js";
 import { validateDiscriminator } from "../../recommendation/discriminators.js";
 import { isAttackSurfaceSecurityBoundary } from "../../prompts/test-recommendation/recommendationShared.js";
@@ -76,7 +76,7 @@ const discriminatorClaimSchema = z.object({
 const registerCandidateSchema = z.object({
     scenarioName: z.string().min(1).describe("Name for this test/scenario. Reused as the match key against the generation tool's scenarioName — keep it identical when you later call the generation tool."),
     description: z.string().min(1),
-    category: z.enum(SCENARIO_CATEGORIES).describe("Test category — drives ranking (never your own priority tag)."),
+    category: z.enum(SCENARIO_CATEGORIES).describe("Test category — drives ranking (never your own priority tag). `bug_caught` targets a `<bug_found>` flaw from code review. `requirement_conflict` asserts a requirement the PR title/description (or a requirements file it references) states and the implemented behavior contradicts — it fails on the current code by design. Both rank in the top tier but are carved out independently, so a requirement conflict never loses its slot to a code-review bug."),
     priority: z.enum(["high", "medium", "low"]).describe("Your own assessment — recorded, but ranking is derived from category, not this field."),
     testType: z.nativeEnum(TestType).refine((t) => PLAN_TEST_TYPES.has(t), {
         message: `testType must be one of ${[...PLAN_TEST_TYPES].join(", ")}`,
@@ -340,7 +340,26 @@ function renderGenerationDirective(plan) {
             (nonUICount > 0 ? ` Generate the ${tests(nonUICount)} of other types as well.` : ""),
     ];
 }
-function renderPlanText(plan, dropped) {
+/** SKYR-4292: the server cannot count the diff's changed behaviors, so an
+ *  under-budget plan is flagged (not rejected) with what a missing candidate looks
+ *  like. Wipro PR #24 registered 3 candidates against a 20-slot UI-only budget and
+ *  the tool answered "AUTHORITATIVE and FINAL" with no pushback. */
+function renderBudgetCheck(plan, maxTotal) {
+    const filled = plan.generate.length + plan.additional.length;
+    if (filled >= maxTotal)
+        return [];
+    return [
+        "",
+        `### Budget check: ${filled} of ${maxTotal} slots filled`,
+        "Every observable behavior this diff changes — each option value added, removed, renamed or reordered; each label, " +
+            "element, route, state, validation rule, computed value or style value (spacing, size, color, radius, font weight, " +
+            "class name) that renders differently; each removed element, asserted absent — needs a candidate above, however " +
+            "small the change. A change is covered only when an existing test asserts the changed value, not when a test merely " +
+            "reaches the component. If any changed behavior has no candidate, call skyramp_register_test_plan again with your " +
+            "full updated list. If the diff truly changes fewer behaviors than the budget, this plan stands as-is.",
+    ];
+}
+function renderPlanText(plan, dropped, maxTotal) {
     const lines = [];
     lines.push(`## Approved Test Plan (${plan.planId})`);
     lines.push("");
@@ -402,6 +421,7 @@ function renderPlanText(plan, dropped) {
     }
     lines.push("");
     lines.push(...renderGenerationDirective(plan));
+    lines.push(...renderBudgetCheck(plan, maxTotal));
     return lines.join("\n");
 }
 // ── Tool registration ───────────────────────────────────────────────────────
@@ -544,10 +564,11 @@ export function registerRegisterTestPlanTool(server) {
             // changes would silently plan zero UI tests (runs 32419025266,
             // 32431042133, 32431106864) — reject so the agent self-corrects in one
             // step, exactly like the empty-candidates rejection above.
-            if (reservedUISlots(budgetContext) > 0 &&
-                !allCandidates.some((c) => inferScenarioType(c.scenario) === TestType.UI)) {
-                errorResult = toolError("This run has frontend changes, so the plan reserves a UI slot — but no submitted or recovered " +
-                    "candidate has testType 'ui'. Resubmit your full candidate list including at least one UI candidate " +
+            const uiFloor = generateFloors(budgetContext).ui;
+            if (uiFloor > 0 && !allCandidates.some((c) => inferScenarioType(c.scenario) === TestType.UI)) {
+                errorResult = toolError(`This run has frontend changes, so the plan MUST include UI tests — at least ${uiFloor} of the ` +
+                    "GENERATE slots are held for them, and more are open to UI candidates on rank. No submitted or " +
+                    "recovered candidate has testType 'ui'. Resubmit your full candidate list including UI candidates " +
                     "for the changed frontend (see uiContext.changedFrontendFiles).");
                 return errorResult;
             }
@@ -576,7 +597,7 @@ export function registerRegisterTestPlanTool(server) {
                 return errorResult;
             }
             return {
-                content: [{ type: "text", text: renderPlanText(approvedPlan, result.dropped) }],
+                content: [{ type: "text", text: renderPlanText(approvedPlan, result.dropped, budgetContext.maxTotal) }],
             };
         }
         catch (error) {

package/build/types/RepositoryAnalysis.d.ts

@@ -1119,7 +1119,7 @@ export declare const scenarioStepSchema: z.ZodObject<{
 export declare const draftedScenarioSchema: z.ZodObject<{
     scenarioName: z.ZodString;
     description: z.ZodString;
-    category: z.ZodEnum<["new_endpoint", "bug_caught", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>;
+    category: z.ZodEnum<["new_endpoint", "bug_caught", "requirement_conflict", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>;
     priority: z.ZodEnum<["high", "medium", "low"]>;
     steps: z.ZodArray<z.ZodObject<{
         order: z.ZodNumber;
@@ -1231,7 +1231,7 @@ export declare const draftedScenarioSchema: z.ZodObject<{
     description: string;
     priority: "high" | "medium" | "low";
     scenarioName: string;
-    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
     steps: {
         path: string;
         method: string;
@@ -1268,7 +1268,7 @@ export declare const draftedScenarioSchema: z.ZodObject<{
     description: string;
     priority: "high" | "medium" | "low";
     scenarioName: string;
-    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
     steps: {
         path: string;
         method: string;
@@ -1607,7 +1607,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         draftedScenarios: z.ZodArray<z.ZodObject<{
             scenarioName: z.ZodString;
             description: z.ZodString;
-            category: z.ZodEnum<["new_endpoint", "bug_caught", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>;
+            category: z.ZodEnum<["new_endpoint", "bug_caught", "requirement_conflict", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>;
             priority: z.ZodEnum<["high", "medium", "low"]>;
             steps: z.ZodArray<z.ZodObject<{
                 order: z.ZodNumber;
@@ -1719,7 +1719,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -1756,7 +1756,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -1799,7 +1799,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -1842,7 +1842,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -2743,7 +2743,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -2956,7 +2956,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;

package/build/types/TestAnalysis.d.ts

@@ -41,6 +41,18 @@ export interface MaintenanceActionCore {
      *  downstream stage that reasons about the edit needs both — notably the report-time
      *  working-tree check, which otherwise calls a POM-backed UPDATE unbacked (SKYR-4129). */
     pomFile?: string;
+    /** Visual-snapshot baselines (toHaveScreenshot filenames, e.g. "page-001.png") an UPDATE
+     *  refreshes because the diff changed how the captured page/element looks (SKYR-4298).
+     *  The edit lands in the PNG under `<spec>-snapshots/`, not in the spec, so the
+     *  report-time working-tree check must accept that PNG as the UPDATE's backing, and
+     *  the final `skyramp_execute_test` must receive the list as `rebaselineSnapshots`. */
+    rebaselineSnapshots?: string[];
+    /** True when the UPDATE carries rebaselineSnapshots and no updateInstructions: the
+     *  refresh is its whole maintenance, so no edit to the spec/POM is expected. When false
+     *  (or absent) with baselines listed, the report-time check requires BOTH the edit and
+     *  the rewritten PNG — a listed baseline must never exempt the selector edit the same
+     *  verdict claimed (SKYR-3883 stays in force). */
+    rebaselineOnly?: boolean;
 }
 /** Normalized internal recommendation built from LLM-supplied args.recommendations. */
 export interface DriftRecommendation extends MaintenanceActionCore {

package/build/types/TestExecution.d.ts

@@ -60,6 +60,10 @@ export interface TestExecutionOptions {
     playwrightSaveStoragePath?: string;
     dockerNetwork?: string;
     useHostNetwork?: boolean;
+    /** Visual-snapshot baselines (toHaveScreenshot filenames, e.g. "page-001.png") this run
+     *  replaces instead of comparing against — forwarded to SmartPlaywright as
+     *  SKYRAMP_UPDATE_SNAPSHOTS (SKYR-4298). Only for an intended UI change the diff explains. */
+    rebaselineSnapshots?: string[];
 }
 /**
  * Progress callback for reporting execution status

package/build/types/TestRecommendation.d.ts

@@ -12,7 +12,7 @@ export declare enum Novelty {
     EXISTING = "existing"
 }
 /** All categories including internal ones. */
-export declare const SCENARIO_CATEGORIES: readonly ["new_endpoint", "bug_caught", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"];
+export declare const SCENARIO_CATEGORIES: readonly ["new_endpoint", "bug_caught", "requirement_conflict", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"];
 export type ScenarioCategory = typeof SCENARIO_CATEGORIES[number];
 /** Categories valid for tool submissions (excludes internal-only categories). */
 export declare const TEST_CATEGORIES: readonly ["business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"];
@@ -21,3 +21,13 @@ export type TestCategory = typeof TEST_CATEGORIES[number];
 export declare const CATEGORY_PRIORITY: Record<ScenarioCategory, PriorityTier>;
 /** Map internal-only categories to their external equivalent for tool submission. */
 export declare function externalCategory(cat: ScenarioCategory): TestCategory;
+/**
+ * Categories whose scenarios target a specific identified defect — a code flaw
+ * (`bug_caught`) or a stated requirement the code contradicts
+ * (`requirement_conflict`). They survive external-test dedup: an existing test on
+ * the same endpoint exercises the surface, not the flaw, so removing them would
+ * drop the only test that fails on the defect.
+ */
+export declare const FLAW_TARGETING_CATEGORIES: readonly ["bug_caught", "requirement_conflict"];
+/** Whether `category` targets a specific identified defect (see {@link FLAW_TARGETING_CATEGORIES}). */
+export declare function isFlawTargetingCategory(category: ScenarioCategory | undefined): boolean;

package/build/types/TestRecommendation.js

@@ -17,6 +17,14 @@ export var Novelty;
 const INTERNAL_CATEGORIES = [
     "new_endpoint", // MEDIUM - diff-direct scenario; where a test came from, not a guarantee of a slot
     "bug_caught", // CRITICAL - tests targeting a specific <bug_found> flaw identified during enrichment
+    // CRITICAL - tests asserting a requirement the PR title/description (or a
+    // requirements file it references) states, which the implemented behavior
+    // contradicts. Separate from bug_caught deliberately (SKYR-4291): labelled
+    // bug_caught, a requirement-vs-code mismatch competed with the code-review
+    // flaws for the same promotion and lost it on severity. Its own category means
+    // its own carve-out here, first place in the promotion order SKYR-4275's bound
+    // hands out, and its own coverage gate.
+    "requirement_conflict",
 ];
 /** External categories valid for tool submissions, ordered by priority. */
 const CATEGORIES = [
@@ -59,6 +67,12 @@ export const CATEGORY_PRIORITY = {
     // fill GENERATE.
     new_endpoint: PriorityTier.MEDIUM,
     bug_caught: PriorityTier.CRITICAL, // tests targeting a <bug_found> flaw — always in GENERATE
+    // A stated requirement the implementation contradicts is the point of the PR,
+    // so it sits in the same top tier as bug_caught. Being its own category, it is
+    // carved out separately in planRanker and takes the FIRST slot of the promotion
+    // bound SKYR-4275 sets — the code-review flaws promote into what is left, so a
+    // requirement conflict is never the finding that loses on severity.
+    requirement_conflict: PriorityTier.CRITICAL,
     business_rule: PriorityTier.HIGH, // formula/business-logic bugs are high priority
     security_boundary: PriorityTier.HIGH,
     data_integrity: PriorityTier.HIGH,
@@ -75,5 +89,25 @@ export function externalCategory(cat) {
         return "crud";
     if (cat === "bug_caught")
         return "business_rule";
+    // The stated requirement IS the business rule the test asserts — same landing
+    // spot as bug_caught, so a requirement-conflict test reads as a rule check in
+    // the customer-facing report rather than an unrecognised label.
+    if (cat === "requirement_conflict")
+        return "business_rule";
     return cat;
 }
+/**
+ * Categories whose scenarios target a specific identified defect — a code flaw
+ * (`bug_caught`) or a stated requirement the code contradicts
+ * (`requirement_conflict`). They survive external-test dedup: an existing test on
+ * the same endpoint exercises the surface, not the flaw, so removing them would
+ * drop the only test that fails on the defect.
+ */
+export const FLAW_TARGETING_CATEGORIES = [
+    "bug_caught",
+    "requirement_conflict",
+];
+/** Whether `category` targets a specific identified defect (see {@link FLAW_TARGETING_CATEGORIES}). */
+export function isFlawTargetingCategory(category) {
+    return category !== undefined && FLAW_TARGETING_CATEGORIES.includes(category);
+}

package/build/utils/AnalysisStateManager.d.ts

@@ -5,6 +5,7 @@ import { RepositoryAnalysis, AnalysisScope } from "../types/RepositoryAnalysis.j
 import { PRTestContext } from "./pr-comment-parser.js";
 import { ParsedDiffEndpoint } from "./routeParsers.js";
 import type { CandidateUiPage } from "./uiPageEnumerator.js";
+import type { RemovedUiElement } from "./removedUiElements.js";
 import type { FrontendFileIntegration } from "../types/FrontendIntegration.js";
 import type { ApprovedPlanItem } from "../types/Recommendation.js";
 import type { ExternalTestRunRecord } from "../types/ExternalTestExecution.js";
@@ -135,6 +136,12 @@ export interface UiAnalysisContext {
      * the agent running its own grep mid-task. Same order as changedFrontendFiles.
      */
     frontendFileIntegration?: FrontendFileIntegration[];
+    /**
+     * data-testids the diff removed from files whose page survives (SKYR-4305).
+     * Present only when non-empty. The testbot records a removal guard
+     * (`toBeHidden()` on the id + a positive sibling assertion) for each entry.
+     */
+    removedElements?: RemovedUiElement[];
 }
 /**
  * SKYR-3879 Path B — the server-side selection checkpoint's persisted result.