@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/utils/planMatchKeys.js

@@ -1,20 +1,16 @@
 /**
- * SKYR-3879 Path B — shared match-key computation for the register-plan
- * checkpoint. `computeMatchKeys` runs ONCE, at approval time (inside
- * registerTestPlanTool / the analyze_changes pre-seed), so the two
- * consumers — planGuard (generation-tool hard gate) and submitReportTool
- * (report cross-check) — only ever do a Set/array membership check, never
- * re-derive normalization logic against a live candidate.
+ * Shared match-key computation for the generation-tool plan gate. The generation
+ * tools are called with a scenario name and an endpoint, never a `plannedTestId`,
+ * so this joins a call back to a plan planned test; the report compares ids.
  *
  * Two kinds of key:
  *  - `name:<slug>`               — normalized scenarioName, for multi-step
- *    candidates (batch-scenario / integration) where the agent's own name is
+ *    planned tests (batch-scenario / integration) where the agent's own name is
  *    the natural join key.
  *  - `ep:<testType>:<METHOD>:<path>` — one per step, for single-endpoint
  *    matching (contract tests, or a fallback when names drift between
  *    register and generate).
  */
-import { isParamSegment, isOpaqueIdSegment } from "./routeParsers.js";
 /** Lowercase, collapse non-alphanumeric runs to '-', trim leading/trailing '-'. */
 export function slugifyName(name) {
     return (name ?? "")
@@ -23,25 +19,45 @@ export function slugifyName(name) {
         .replace(/^-+|-+$/g, "");
 }
 /**
- * Normalize a path so param/id segments collapse: `{brace}`, `:colon`,
- * `[bracket]` params in any of routeParsers.ts's syntaxes, plus numeric,
- * UUID, and long-hex id VALUES, all become `:p`. Delegates to
- * routeParsers.ts's `isParamSegment`/`isOpaqueIdSegment` (SKYR-4214 task 5)
- * rather than a second inline copy — this module previously had its own
- * looser hex rule (`/^[0-9a-fA-F-]{16,}$/`, accepting `-`) and no
- * bracket-syntax rule at all, so a Next.js `[id]` segment never collapsed
- * and kept a match key from matching its `{id}`-spelled counterpart (the
- * SKYR-4123 failure mode: a generated test's key stops matching its plan
- * item). The characterization test in
- * `pathSegmentClassification.characterization.test.ts` confirms every
- * previously-agreeing input (UUID, numeric, 16+/24-char hex) still
- * collapses to `:p` after this change — safe within one run because the
- * register-time key and the generation-time query are computed by the same
- * build; a plan file is never persisted across builds. Mirrors
- * discriminators.ts's normalizePath (duplicated rather than imported —
- * that function verifies discriminator claims against a diff, a different
- * concern from plan matching, and keeping them independent avoids coupling
- * this module's stability to phase 1's internal helper).
+ * One path segment that names a parameter rather than a resource, in any of the
+ * route syntaxes a repository writes: OpenAPI "{id}", Express/NestJS ":id", and Next.js
+ * "[id]" / "[...id]" / "[[...id]]" (the double-bracket form needs its own
+ * alternative — it contains an inner "]", which the single-bracket form's
+ * [^\]]+ can never span).
+ */
+// The colon form may carry an Express/Fastify constraint or modifier —
+// `:id(\d+)`, `:id?`, `:id*`, `:id+`. Those are still parameters, and a
+// resource name is never one, so the predicate has to accept them, or a
+// constrained param stops collapsing and its route stops matching.
+const PARAM_SEGMENT_RE = /^\{[^}]+\}$|^:[A-Za-z_]\w*(?:\([^)]*\))?[?*+]?$|^\[\[[^\]]+\]\]$|^\[[^\]]+\]$/;
+export function isParamSegment(segment) {
+    return PARAM_SEGMENT_RE.test(segment);
+}
+/**
+ * One path segment that is an id VALUE rather than a name: a UUID, digits only,
+ * or a long hex run (a Mongo ObjectId is 24). A caller writes a literal id in a
+ * path where the route declares a parameter, and an id can never be a resource
+ * name, so resource derivation must skip it exactly as it skips a parameter.
+ * SKYR-4214: an accepted UUID produced the key
+ * "DELETE::a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11::integration", which matches
+ * nothing, so the planned test escaped dedup entirely.
+ *
+ * The 16-character floor on the hex rule keeps real resource names safe: a name
+ * built only from the letters a-f and digits, 16 characters or longer, is not a
+ * word.
+ */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isOpaqueIdSegment(segment) {
+    // The sign belongs to the value: an edge-case step writes `/orders/-1` to
+    // probe a negative id, and without the sign that segment became the resource
+    // name, so the key could never match real order coverage.
+    return UUID_RE.test(segment) || /^-?\d+$/.test(segment) || /^[0-9a-f]{16,}$/i.test(segment);
+}
+/**
+ * Normalize a path so param and id segments collapse to `:p`.
+ *
+ * The two predicates above are the only rule for it — an earlier inline copy had
+ * no bracket rule, so a Next.js `[id]` stopped matching its `{id}` spelling.
  */
 export function normalizeMatchPath(rawPath) {
     const pathPart = (rawPath ?? "").split("?")[0];
@@ -50,58 +66,43 @@ export function normalizeMatchPath(rawPath) {
         .map((seg) => {
         if (seg === "")
             return seg;
-        // `isParamSegment` covers the well-formed colon family — `:id`,
-        // `:id(\d+)`, `:id?`, `:id*`, `:id+`. The `/^:/` test in front of it is
-        // deliberate breadth for the colon segments that regex rejects, such as
-        // `:1abc` or `:id-x`: a malformed param must still normalize to `:p`,
-        // or a registered `/users/:1abc` stops endpoint-matching `/users/42`.
+        // `isParamSegment` covers only well-formed colon params. The broader
+        // `/^:/` test in front of it catches the ones that regex rejects, such as
+        // `:1abc` or `:id-x`: a malformed param must still normalize to `:p`, or
+        // a registered `/users/:1abc` stops endpoint-matching `/users/42`.
         if (/^:/.test(seg) || isParamSegment(seg) || isOpaqueIdSegment(seg))
             return ":p";
         return seg.toLowerCase();
     })
         .join("/");
 }
+/** The scenario is read back from the stored plan, so `steps` is an array only on
+ *  the validated path. `?? []` keeps a malformed plan from costing the call. */
 function inferTestType(scenario) {
-    return (scenario.testType ?? (scenario.steps.length === 1 ? "contract" : "integration")).toLowerCase();
+    const steps = Array.isArray(scenario?.steps) ? scenario.steps : [];
+    return (scenario?.testType ?? (steps.length === 1 ? "contract" : "integration")).toLowerCase();
 }
-/** Name key (if a name exists) plus one endpoint key per step. */
+/** Name key (if a name exists) plus one endpoint key per step. BOTH kinds carry
+ *  the planned test's test type, or a contract call matches an integration-only
+ *  planned test sharing its name. A slug holds no `:`. */
 export function computeMatchKeys(scenario) {
     const keys = [];
-    const slug = slugifyName(scenario.scenarioName);
-    if (slug)
-        keys.push(`name:${slug}`);
     const testType = inferTestType(scenario);
-    for (const step of scenario.steps ?? []) {
+    const slug = slugifyName(scenario?.scenarioName);
+    if (slug)
+        keys.push(`name:${testType}:${slug}`);
+    for (const step of Array.isArray(scenario?.steps) ? scenario.steps : []) {
         if (!step?.method || !step?.path)
             continue;
         keys.push(`ep:${testType}:${step.method.toUpperCase()}:${normalizeMatchPath(step.path)}`);
     }
     return [...new Set(keys)];
 }
-/** Build the persisted plan item from a ranked Candidate. */
-export function buildApprovedPlanItem(candidate) {
-    return {
-        candidateId: candidate.candidateId,
-        scenarioName: candidate.scenario.scenarioName,
-        testType: inferTestType(candidate.scenario),
-        category: candidate.scenario.category,
-        source: candidate.source,
-        ...(candidate.verifiedDiscriminator ? { verifiedDiscriminator: candidate.verifiedDiscriminator } : {}),
-        ...(candidate.scenario.subjectEndpoints !== undefined
-            ? { subjectEndpoints: candidate.scenario.subjectEndpoints }
-            : {}),
-        matchKeys: computeMatchKeys(candidate.scenario),
-    };
-}
 /**
- * Segment-aligned comparison of two normalized paths that tolerates a
- * base-path prefix on either side (SKYR-4019). Register-time keys and
- * generation-time queries derive their paths from different origins:
- * server-drafted scenario steps can carry router-relative paths
- * (`/orders/{id}`) while the generation tool's query comes from the live
- * endpointURL (`/api/v1/orders/{id}`). The shorter path matches when its
- * segments are a suffix of the longer path's segments — never mid-segment,
- * and never on an all-parameter path (`/:p` would match everything).
+ * Segment-aligned comparison of two normalized paths, tolerating a MOUNT prefix
+ * on either side. The shorter must be the whole tail of the longer, never
+ * mid-segment and never all-parameter, and the extra leading segments must hold
+ * no parameter — which separates `/api/v1` + `/orders` from `/tenants/{id}` + it.
  */
 function normalizedPathsMatch(a, b) {
     if (a === b)
@@ -114,21 +115,55 @@ function normalizedPathsMatch(a, b) {
     if (shorter.every((seg) => seg === ":p"))
         return false;
     const offset = longer.length - shorter.length;
-    return shorter.every((seg, i) => longer[offset + i] === seg);
+    if (!shorter.every((seg, i) => longer[offset + i] === seg))
+        return false;
+    // The extra leading segments are the planned test mount. A parameter among them
+    // means the two paths address different resources.
+    return longer.slice(0, offset).every((seg) => seg !== ":p");
+}
+/** Whether `keys` hold this query's name channel — the same test
+ *  `matchesMatchKeys` applies before it consults the endpoint. */
+function nameAgrees(keys, query) {
+    const nameSlug = query.scenarioName ? slugifyName(query.scenarioName) : "";
+    if (!nameSlug)
+        return false;
+    const wanted = query.testType ? `name:${query.testType.toLowerCase()}:${nameSlug}` : undefined;
+    return keys.some((key) => wanted !== undefined ? key === wanted : key.startsWith("name:") && key.endsWith(`:${nameSlug}`));
+}
+/** Whether the plan holds this query's endpoint, ignoring the name. Shared by
+ *  the name channel — which may no longer answer alone on an endpoint query —
+ *  and by the endpoint channel below. */
+function endpointAgrees(keys, query) {
+    if (!query.path)
+        return false;
+    const normPath = normalizeMatchPath(query.path);
+    const methodFilter = query.method ? query.method.toUpperCase() : undefined;
+    return keys.some((key) => {
+        if (!key.startsWith("ep:"))
+            return false;
+        const parts = key.split(":");
+        if (methodFilter && parts[2] !== methodFilter)
+            return false;
+        return normalizedPathsMatch(parts.slice(3).join(":"), normPath);
+    });
 }
 /**
- * True when `query` matches at least one of `items`' matchKeys:
- *  - by scenarioName slug (`name:<slug>`), or
+ * True when `query` matches `keys`:
+ *  - by testType + scenarioName slug (`name:<testType>:<slug>`), or
  *  - by testType + path (`ep:<testType>:*:<path>`), method-exact when
  *    `query.method` is given, method-agnostic (any method) otherwise — the
  *    contract tool's `method: ""` ("test all methods") case. Path comparison
  *    tolerates a base-path prefix on either side (see normalizedPathsMatch).
+ * The planned test's test type gates BOTH channels: gating the endpoint channel
+ * alone let a contract call pass against an integration-only planned test of the
+ * same name. Where the query carries an endpoint the name match must agree on it
+ * too, since `slugifyName` folds case and every run of non-alphanumerics.
  */
-export function matchesApprovedItem(items, query) {
-    const nameSlug = query.scenarioName ? slugifyName(query.scenarioName) : "";
-    if (nameSlug) {
-        const nameKey = `name:${nameSlug}`;
-        if (items.some((item) => item.matchKeys.includes(nameKey)))
+export function matchesMatchKeys(keys, query) {
+    if (nameAgrees(keys, query)) {
+        if (!query.path)
+            return true;
+        if (endpointAgrees(keys, query))
             return true;
     }
     if (query.testType && query.path) {
@@ -150,22 +185,49 @@ export function matchesApprovedItem(items, query) {
                 return false;
             return normalizedPathsMatch(keyPath, normPath);
         };
-        if (items.some((item) => item.matchKeys.some(epKeyMatches)))
+        if (keys.some(epKeyMatches))
             return true;
     }
     return false;
 }
 /**
- * True when `query` is admissible under the approved plan: it matches a
- * GENERATE item, or it matches an ADDITIONAL item while the plan has at least
- * one GENERATE item. ADDITIONAL is strictly a backfill pool for failed
- * GENERATE items — on a zero-budget plan (`generate: []`, e.g. maxGenerate=0
- * for a config-only PR) there is nothing to backfill, so ADDITIONAL must not
- * admit generation. Shared by planGuard and submitReportTool so the gate and
- * the report cross-check can never disagree on admissibility.
+ * The planned tests whose scenarioName and testType match but whose planned steps
+ * name no endpoint the query addresses — the near miss a boolean cannot report,
+ * where the real disagreement is one step's path spelling. Empty when the query
+ * names no path.
  */
-export function matchesApprovedPlan(plan, query) {
-    if (matchesApprovedItem(plan.generate, query))
-        return true;
-    return plan.generate.length > 0 && matchesApprovedItem(plan.additional, query);
+export function nameMatchedEndpointMismatches(plannedTests, query) {
+    if (!query.path)
+        return [];
+    return plannedTests.filter((plannedTest) => {
+        if (!plannedTest?.scenario)
+            return false;
+        const keys = computeMatchKeys(plannedTest.scenario);
+        return nameAgrees(keys, query) && !endpointAgrees(keys, query);
+    });
+}
+/** The planned tests whose scenarioName matches but whose testType does not — the
+ *  plan holds this scenario and the call asked a different generator for it, so
+ *  "not in the plan" is the wrong thing to say. Empty when the query names no
+ *  type, since `nameAgrees` then matches on the name alone. */
+export function nameMatchedTypeMismatches(plannedTests, query) {
+    const nameSlug = query.scenarioName ? slugifyName(query.scenarioName) : "";
+    if (!nameSlug || !query.testType)
+        return [];
+    const calledType = query.testType.toLowerCase();
+    return plannedTests.filter((plannedTest) => {
+        if (!plannedTest?.scenario)
+            return false;
+        const keys = computeMatchKeys(plannedTest.scenario);
+        // The name channel, minus the type: a key ending in this slug means the plan
+        // holds the scenario, and the segment before it is the type it holds it as.
+        const named = keys.filter((key) => key.startsWith("name:") && key.endsWith(`:${nameSlug}`));
+        return named.length > 0 && !named.some((key) => key === `name:${calledType}:${nameSlug}`);
+    });
+}
+/** True when `query` matches at least one planned test of the registered plan.
+ *  The keys are computed per call rather than stored with the plan, so there is
+ *  one description of a planned test and no second shape to drift from it. */
+export function matchesPlanCandidates(plannedTests, query) {
+    return plannedTests.some((plannedTest) => !!plannedTest?.scenario && matchesMatchKeys(computeMatchKeys(plannedTest.scenario), query));
 }

package/build/utils/rebaselineSnapshots.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+/**
+ * Visual-snapshot baseline names as a Skyramp test passes them to
+ * `toHaveScreenshot()` — e.g. `page-001.png` — and as `skyramp_actions` and
+ * `skyramp_execute_test` accept them in `rebaselineSnapshots` (SKYR-4298).
+ *
+ * Bare filename only: no path separators, and no commas or whitespace, because the
+ * list is joined with commas into `SKYRAMP_UPDATE_SNAPSHOTS` and split again in the
+ * executor, where `a,b.png` would read as two baselines. One definition shared by
+ * both tools so they can never drift apart.
+ */
+export declare const REBASELINE_SNAPSHOT_NAME_RE: RegExp;
+export declare const rebaselineSnapshotNameSchema: z.ZodString;
+/** `page-001.png` → `page-001`. */
+export declare function baselineStem(name: string): string;
+export declare function baselineFileMatchesStem(fileBasename: string, stem: string): boolean;
+/** The directory Playwright keeps a spec's baselines in under the default layout. */
+export declare function snapshotDirFor(specFile: string): string;
+/** Looks like an on-disk baseline filename (`page-001-chromium-linux.png`) rather than the
+ *  name the test passes (`page-001.png`) — the likeliest wrong input, and one the name
+ *  schema accepts. Advisory only: `hero-linux.png` is also a perfectly valid name a test
+ *  can pass, so callers warn and keep the entry; execution authorizes it against the
+ *  verdict and reports whether anything was actually rewritten. */
+export declare function looksLikeOnDiskBaselineName(name: string): boolean;

package/build/utils/rebaselineSnapshots.js

@@ -0,0 +1,65 @@
+import path from "path";
+import { z } from "zod";
+/**
+ * Visual-snapshot baseline names as a Skyramp test passes them to
+ * `toHaveScreenshot()` — e.g. `page-001.png` — and as `skyramp_actions` and
+ * `skyramp_execute_test` accept them in `rebaselineSnapshots` (SKYR-4298).
+ *
+ * Bare filename only: no path separators, and no commas or whitespace, because the
+ * list is joined with commas into `SKYRAMP_UPDATE_SNAPSHOTS` and split again in the
+ * executor, where `a,b.png` would read as two baselines. One definition shared by
+ * both tools so they can never drift apart.
+ */
+export const REBASELINE_SNAPSHOT_NAME_RE = /^[^/\\,\s]+\.png$/i;
+export const rebaselineSnapshotNameSchema = z
+    .string()
+    .trim()
+    .regex(REBASELINE_SNAPSHOT_NAME_RE, {
+    message: 'rebaselineSnapshots entries must be bare .png filenames as passed to toHaveScreenshot(), e.g. "page-001.png" — no path, commas, or whitespace',
+});
+/** `page-001.png` → `page-001`. */
+export function baselineStem(name) {
+    return path.basename(name).replace(/\.png$/i, "");
+}
+/**
+ * Playwright's default snapshot layout, which is what the executor produces: the
+ * baseline for `<stem>.png` lives in `<spec>-snapshots/` as `<stem>-<project>-<platform>.png`
+ * (or `<stem>-<platform>.png` with no project, or `<stem>.png` under a custom
+ * `snapshotPathTemplate`). Safe to assume here because TestExecutionService mounts
+ * its own generated Playwright config over any the repo carries, so a repo cannot
+ * relocate its snapshots out from under this rule.
+ *
+ * The executor's generated config declares no `projects`, but runner.sh passes
+ * `--browser=chromium`, so Playwright names the implicit project "chromium" and a
+ * refresh writes `<stem>-chromium-linux.png` (observed end to end on demoshop).
+ * Baselines the Skyramp executor produced therefore round-trip exactly. A baseline
+ * a repo's own CI wrote under another project name (`<stem>-Desktop-Chrome-linux.png`)
+ * is a different file: the executor's refresh adds its own and leaves that one as
+ * it was — the tool reports what it rewrote, and the repo's own suite is out of
+ * scope for skyramp_execute_test (which never runs it).
+ *
+ * Anchored so a longer baseline cannot vouch for a shorter one: `page-001-wide-chromium-linux.png`
+ * belongs to `page-001-wide.png` and must not satisfy a claim on `page-001.png`.
+ */
+const SNAPSHOT_PLATFORMS = "(?:darwin|linux|win32)";
+export function baselineFileMatchesStem(fileBasename, stem) {
+    // A degenerate stem ("" or dots only, from a name like "..png") would match a wide
+    // set of files; nothing legitimate has one.
+    if (!stem || /^\.+$/.test(stem))
+        return false;
+    const escaped = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp(`^${escaped}(?:-[^-]+-${SNAPSHOT_PLATFORMS}|-${SNAPSHOT_PLATFORMS})?\\.png$`, "i");
+    return re.test(fileBasename);
+}
+/** The directory Playwright keeps a spec's baselines in under the default layout. */
+export function snapshotDirFor(specFile) {
+    return `${specFile}-snapshots`;
+}
+/** Looks like an on-disk baseline filename (`page-001-chromium-linux.png`) rather than the
+ *  name the test passes (`page-001.png`) — the likeliest wrong input, and one the name
+ *  schema accepts. Advisory only: `hero-linux.png` is also a perfectly valid name a test
+ *  can pass, so callers warn and keep the entry; execution authorizes it against the
+ *  verdict and reports whether anything was actually rewritten. */
+export function looksLikeOnDiskBaselineName(name) {
+    return /-(?:[^-]+-)?(?:darwin|linux|win32)\.png$/i.test(name);
+}

package/build/utils/removedUiElements.d.ts

@@ -0,0 +1,22 @@
+export interface RemovedUiElement {
+    /** Lower-cased identifying attribute: `data-testid`, `data-cy`, `data-qa`, `data-section`, … */
+    attribute: string;
+    /** Its literal value. `attribute` + `value` is unique across the result. */
+    value: string;
+    /** Repo-relative frontend file the diff removed it from. */
+    file: string;
+}
+export interface CollectRemovedUiElementsInput {
+    changedFrontendFiles: string[];
+    /** Files with `+++ /dev/null` in the diff — their page is gone, no guard. */
+    deletedFiles: string[];
+    /** Per-file diff slices for the WHOLE diff keyed by repo-relative path (see diffBlocksByPath). */
+    diffByFile: Map<string, string>;
+    /** Absolute paths of discovered existing tests (skyramp + relevant external). */
+    existingTestFiles: string[];
+    /** True when test discovery threw — the existing-test check cannot run, so report nothing. */
+    discoveryFailed?: boolean;
+    /** Injectable for tests; defaults to a tolerant fs read that logs failures. */
+    readFile?: (absPath: string) => string | undefined;
+}
+export declare function collectRemovedUiElements(input: CollectRemovedUiElementsInput): RemovedUiElement[];

package/build/utils/removedUiElements.js

@@ -0,0 +1,106 @@
+/**
+ * Removed UI elements (SKYR-4305) — grounding for the removal guard.
+ *
+ * The recommendation prompt already requires a candidate for every element a PR
+ * removes ("the removal is what this PR ships, so the removal is what gets tested").
+ * A blueprint can never contain a removed element, so this module supplies what the
+ * agent otherwise has to guess: WHICH identifying `data-*` attributes (`data-testid`,
+ * `data-cy`, `data-qa`, `data-test-id`, or another static `data-*`) the diff removed.
+ * The agent finds the page they rendered on. `data-testid` is asserted with `getByTestId`; every
+ * other attribute with `page.locator('[<attribute>="<value>"]')`, so the guard never
+ * silently resolves against the wrong attribute. It drafts nothing and gates nothing — it reduces noise:
+ *
+ *   - an id is reported only when its file survives the change (not in
+ *     `deletedFiles`) — a deleted route/component is maintenance of the tests that
+ *     covered it, not a page to assert on;
+ *   - renames, moves and extractions to another file are excluded by
+ *     `extractRemovedAttributes` (added values are collected across the WHOLE diff);
+ *   - a value an existing discovered test already references is skipped — that test is
+ *     the one to update or delete, a new guard would duplicate it. The match is on the
+ *     VALUE regardless of attribute (a test naming `user-menu-row` as a testid also
+ *     suppresses a `data-section="user-menu-row"` guard) — deliberate over-suppression,
+ *     the safe direction, even though entries are keyed on attribute + value elsewhere. When discovery
+ *     itself failed the list is empty and nothing is reported (fail-closed), because
+ *     "no test references it" cannot be known;
+ *
+ * Every skip is logged at debug with its reason so a missing guard is diagnosable.
+ */
+import * as fs from "fs";
+import { extractAddedAttributeValues, extractRemovedAttributes } from "./frontendSelectors.js";
+import { escapeRegExp } from "./regex.js";
+import { logger } from "./logger.js";
+function defaultReadFile(absPath) {
+    try {
+        return fs.readFileSync(absPath, "utf8");
+    }
+    catch (err) {
+        logger.warning("removedUiElements: could not read existing test (treated as not referencing any removed id)", {
+            file: absPath,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return undefined;
+    }
+}
+/**
+ * Whole-literal match: `order-total` must not be satisfied by `order-total-row`, and
+ * `foo:bar` not by `foo:bar:baz`. The identifier alphabet mirrors the extractor's
+ * value grammar (`[\w:-]`), so every character a value may contain is a
+ * non-boundary here.
+ */
+function referencesLiteral(content, value) {
+    return new RegExp(`(^|[^\\w:-])${escapeRegExp(value)}(?![\\w:-])`).test(content);
+}
+export function collectRemovedUiElements(input) {
+    if (input.discoveryFailed) {
+        logger.warning("removedUiElements: test discovery failed — cannot tell whether an existing test covers a removed id; reporting none");
+        return [];
+    }
+    const readFile = input.readFile ?? defaultReadFile;
+    const deleted = new Set(input.deletedFiles);
+    const skip = (file, reason, extra = {}) => logger.debug(`removedUiElements: skipped ${file} — ${reason}`, extra);
+    // Added values across the ENTIRE diff, so an element extracted into another file is a
+    // move, not a removal.
+    const addedAcrossDiff = new Set();
+    for (const slice of input.diffByFile.values()) {
+        for (const v of extractAddedAttributeValues(slice))
+            addedAcrossDiff.add(v);
+    }
+    // Existing-test contents are read lazily and once: most PRs remove nothing.
+    let testContents;
+    const referencedByExistingTest = (value) => {
+        if (!testContents) {
+            testContents = input.existingTestFiles
+                .map((f) => readFile(f) ?? "")
+                .filter((c) => c.length > 0);
+        }
+        return testContents.some((c) => referencesLiteral(c, value));
+    };
+    const out = [];
+    const seen = new Set();
+    for (const file of input.changedFrontendFiles) {
+        if (deleted.has(file)) {
+            skip(file, "file deleted by the diff (whole surface removed)");
+            continue;
+        }
+        const slice = input.diffByFile.get(file);
+        if (!slice) {
+            skip(file, "no diff slice");
+            continue;
+        }
+        const attrs = extractRemovedAttributes(slice, addedAcrossDiff);
+        if (attrs.length === 0)
+            continue;
+        for (const { attribute, value } of attrs) {
+            const key = `${attribute}=${value}`;
+            if (seen.has(key))
+                continue;
+            if (referencedByExistingTest(value)) {
+                skip(file, `${attribute}="${value}" already referenced by an existing test (maintenance, not a guard)`);
+                continue;
+            }
+            seen.add(key);
+            out.push({ attribute, value, file });
+        }
+    }
+    return out;
+}

package/build/utils/reportVerification.d.ts

@@ -1,4 +1,4 @@
-import { DriftAction } from "../types/TestAnalysis.js";
+import { MaintenanceActionCore } from "../types/TestAnalysis.js";
 /**
  * Enumerate every path that differs from HEAD in the working tree — staged,
  * unstaged, or untracked — as repo-relative paths, via `git status --porcelain`.
@@ -42,11 +42,7 @@ export interface UnchangedFileClaimsInput {
     }[];
     /** Maintenance verdicts (server-derived from skyramp_actions). `pomFile`, when set, is
      *  the file the edit actually lands in — see the UPDATE rule below. */
-    verdicts: {
-        action: DriftAction;
-        testFilePath: string;
-        pomFile?: string;
-    }[];
+    verdicts: Pick<MaintenanceActionCore, "action" | "testFilePath" | "pomFile" | "rebaselineSnapshots" | "rebaselineOnly">[];
     /** owner/repo of the primary repo — used to exempt cross-repo newTest claims
      *  whose files live in a different checkout. */
     primaryRepository?: string;

package/build/utils/reportVerification.js

@@ -1,9 +1,11 @@
 import path from "path";
 import * as fs from "fs/promises";
+import { existsSync } from "fs";
 import { execFile } from "child_process";
 import { promisify } from "util";
 import { testFileMatches } from "./utils.js";
 import { DriftAction } from "../types/TestAnalysis.js";
+import { baselineFileMatchesStem, baselineStem } from "./rebaselineSnapshots.js";
 const execFileAsync = promisify(execFile);
 /**
  * Enumerate every path that differs from HEAD in the working tree — staged,
@@ -137,6 +139,40 @@ export function findUnchangedFileClaims(input) {
         }
         return changedFiles.some((c) => testFileMatches(c, candidate));
     };
+    // A visual-baseline UPDATE (SKYR-4298) edits no source: SmartPlaywright rewrites
+    // the PNG Playwright keeps beside the spec, `<spec>-snapshots/<name>-<project>-
+    // <platform>.png` (the default layout — see baselineFileMatchesStem for why that
+    // is safe to assume). Backed when one of the named baselines changed there AND
+    // still exists: `git status` lists a deleted file as changed too, and a destroyed
+    // baseline is the opposite of a refreshed one. Scoped to the spec's own snapshot
+    // directory so a refreshed baseline of some other spec cannot vouch for this one.
+    const isBackedBySnapshot = (specPath, baselines) => {
+        let specRel = specPath;
+        if (path.isAbsolute(specPath)) {
+            const rel = path.relative(repoRoot, specPath);
+            if (!rel || rel.startsWith("..") || path.isAbsolute(rel))
+                return true;
+            specRel = rel;
+        }
+        // git reports paths with "/" on every platform; path.relative uses the host
+        // separator, so a Windows run would otherwise never match its own snapshot dir.
+        specRel = specRel.split(path.sep).join("/");
+        const snapshotDir = `${specRel}-snapshots/`;
+        const stems = baselines.map(baselineStem).filter(Boolean);
+        return changedFiles.some((c) => {
+            // Same anchoring as testFileMatches: a path-qualified spec must match as a
+            // path segment; a bare basename can only match by directory basename.
+            const inDir = specRel.includes("/")
+                ? c.startsWith(snapshotDir) || c.includes("/" + snapshotDir)
+                : path.basename(path.dirname(c)) === snapshotDir.slice(0, -1);
+            if (!inDir)
+                return false;
+            const base = path.basename(c);
+            if (!stems.some((stem) => baselineFileMatchesStem(base, stem)))
+                return false;
+            return existsSync(path.resolve(repoRoot, c));
+        });
+    };
     // A plan-only run declares its GENERATE list instead of writing files, so
     // skip the claim scan wholesale rather than per-claim: checking it rejects
     // every declaration the guard can see, and the ones it CANNOT see (cross-repo
@@ -165,9 +201,32 @@ export function findUnchangedFileClaims(input) {
         // The edit target, not the spec: for a POM-based test the page object is what
         // gets patched while testFilePath stays the spec (SKYR-4129).
         const editTarget = v.pomFile ?? v.testFilePath;
-        if (!isBacked(editTarget)) {
-            unbacked.push(`testMaintenance ${v.action} claims an edit to "${path.basename(editTarget)}", but that file has no working-tree change`);
+        // Baseline refresh (SKYR-4298): the verdict promises a replaced PNG next to the
+        // spec, and the report says "visual baseline refreshed" on its strength. Two rules:
+        //  - The PNG must have been rewritten. An edit to the spec does not stand in for
+        //    it, otherwise a run that forgot rebaselineSnapshots (or loosened
+        //    maxDiffPixelRatio instead) would report a refresh that never happened.
+        //  - Listing a baseline never exempts the edit the same verdict claimed. Unless the
+        //    verdict is rebaselineOnly (no updateInstructions), the edit target — the POM
+        //    when named, else the spec — still needs its own working-tree change; a
+        //    baseline attached to a selector-rename UPDATE cannot wave the rename through.
+        // A plan-only run executes nothing, so no PNG can be rewritten there; the edit
+        // half is still verified, as for every other UPDATE (SKYR-4250).
+        const baselines = v.rebaselineSnapshots ?? [];
+        if (baselines.length > 0) {
+            const editOk = v.rebaselineOnly === true || isBacked(editTarget);
+            const pngOk = planOnly || isBackedBySnapshot(v.testFilePath, baselines);
+            if (!pngOk) {
+                unbacked.push(`testMaintenance ${v.action} claims a refreshed visual baseline (${baselines.join(", ")}) for "${path.basename(v.testFilePath)}", but no matching PNG was rewritten under its -snapshots directory — the final skyramp_execute_test run must pass rebaselineSnapshots and report it as refreshed; editing the spec does not stand in for the refresh`);
+            }
+            if (!editOk) {
+                unbacked.push(`testMaintenance ${v.action} claims an edit to "${path.basename(editTarget)}" alongside a baseline refresh, but that file has no working-tree change — listing a baseline does not exempt the edit`);
+            }
+            continue;
         }
+        if (isBacked(editTarget))
+            continue;
+        unbacked.push(`testMaintenance ${v.action} claims an edit to "${path.basename(editTarget)}", but that file has no working-tree change`);
     }
     return unbacked;
 }