@skyramp/mcp 0.4.0-rc.1 → 0.4.0

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

@@ -40,7 +40,7 @@ Matching none does **not** mean IGNORE — first run the selector safety net: ma
 
 Build a detection list first: for each matched diff line, write one line: \`{pattern type} — "{diff line}" — affects {route/component}\`.
 
-**Visual-snapshot baselines.** A test that calls \`toHaveScreenshot("<name>.png")\` pixel-compares a page, element, or region against a committed baseline PNG. For such a test only — this does not widen the detection list for any other test — also treat as a reaching change any appearance edit inside what the call captures: a CSS/Tailwind/styled-components change, a changed literal string that renders, a swapped image or icon, a reordered or added visible element. When such a change reaches what one of those calls captures, the baseline is stale — the assertion's expected value is the image, and it must be refreshed exactly as a text assertion would be corrected. Assign **UPDATE** and list the affected baseline filenames in \`rebaselineSnapshots\` (only those whose captured page/element/region the diff reaches — an unaffected baseline in the same spec stays as it is). The refresh happens at execution via \`skyramp_execute_test\`'s \`rebaselineSnapshots\`; never edit the \`toHaveScreenshot()\` call, raise \`maxDiffPixelRatio\`, delete the assertion, or hand-edit a PNG to make it pass — those hide real regressions. When a pre-edit run reports \`Screenshot comparison failed\` and NO diff line explains the mismatch for that capture, the baseline is not stale: leave the test as it is, keep it \`Fail\`, and record the finding in \`issuesFound\`.
+**Visual-snapshot baselines.** A test that calls \`toHaveScreenshot("<name>.png")\` pixel-compares a page, element, or region against a committed baseline PNG. For such a test only — this does not widen the detection list for any other test — also treat as a reaching change any appearance edit inside what the call captures: a CSS/Tailwind/styled-components change, a changed literal string that renders, a swapped image or icon, a reordered or added visible element. When such a change reaches what one of those calls captures, the baseline is stale — the assertion's expected value is the image, and it must be refreshed exactly as a text assertion would be corrected. Assign **UPDATE** and list the affected baseline filenames in \`rebaselineSnapshots\` (only those whose captured page/element/region the diff reaches — an unaffected baseline in the same spec stays as it is). The refresh happens at execution via \`skyramp_execute_test\`'s \`rebaselineSnapshots\`; never edit the \`toHaveScreenshot()\` call, raise \`maxDiffPixelRatio\`, delete the assertion, or hand-edit a PNG to make it pass — those hide real regressions. When a pre-edit run reports \`Screenshot comparison failed\` and NO diff line explains the mismatch for that capture, the baseline is not stale: assign **VERIFY** (the test must still appear as a maintenance row with its before/after status — never drop it from the verdicts), leave its source as it is, keep it \`Fail\`, and also record the finding in \`issuesFound\`. When the pre-edit run **passed**, nothing is stale (a missing baseline is created by that run): do not list \`rebaselineSnapshots\`. A newly generated test writes its own baseline on its first run and can never be stale, so this applies to existing specs only. The refresh rides the final execution and never costs an extra one: pass the \`rebaselineSnapshots\` list on that single call, and if a screenshot mismatch first appears on that final run, report \`Fail\` rather than adding another run. The execution result names which baselines were refreshed and which were not, and the report row's description carries the refreshed names automatically, so \`afterDetails\` states only the outcome (e.g. \`1 passed in 6.1s\`).
 
 **Rules (assign exactly one action per test; severity order above):**
 - **DELETE** when the test's target is gone: all routes/pages it covers no longer exist; all critical selectors were removed with no migration path; or, for a component/widget test, the component it renders was deleted (source removed with no re-export; report-only for external tests).

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

@@ -458,7 +458,8 @@ ${CONTRACT_MODE_GUIDANCE}
   - \`skyramp_export_zip\` outputPath: \`${repositoryPath}/.skyramp/<test_name>_trace.zip\`
   - \`skyramp_ui_test_generation\`: set \`modularizeCode: false\` and \`codeReuse: true\` (TypeScript/JavaScript Playwright only — the default; leave \`codeReuse\` unset for other languages)
   - **\`browser_assert\`**: the \`browser_navigate\` result states the rule this tool has to satisfy on every page you reach. Call multiple assertions in the same tool call batch when checking independent elements.
-  - **Removal guard — when \`uiContext.removedElements\` is non-empty**: the server lists which elements this PR removed — each identified by a \`data-*\` attribute and value, with the file it came from (renames, moves and deleted files are excluded). Read that file and the route or page files that render it to decide which page each appeared on. Per PAGE: \`browser_navigate\` to it, wait for the app to render, then call \`browser_assert_hidden\` once per listed element using the target the list shows — \`testId: "<value>"\` when the attribute is \`data-testid\`, otherwise \`attribute: "<name>", value: "<value>"\` (e.g. \`attribute: "data-cy"\`); no \`ref\` — the element no longer exists, so no snapshot has one; the tool checks the live page and refuses to record on a blank or un-rendered page. Then at least one \`browser_assert\` on a RETAINED element of the same page verifying its text, value or state. If a UI trace for that page is already planned, record the guard assertions inside that trace; otherwise this is its own trace and spec, \`verify-removed-ui-<page-slug>\`. The generated test asserts \`toBeHidden()\` on \`getByTestId(...)\` or \`page.locator('[data-cy="..."]')\` accordingly. A removed element the server did not list still gets its test (the removal check requires it) — ground that one in the diff and say so in \`reasoning\`.
+  - **Removal guard — when \`uiContext.removedElements\` is non-empty**: the server lists which elements this PR removed — each identified by a \`data-*\` attribute and value, with the file it came from (renames, moves and deleted files are excluded). Read that file and the route or page files that render it to decide which page each appeared on. Per PAGE: \`browser_navigate\` to it, wait for the app to render, then call \`browser_assert_hidden\` once per listed element using the target the list shows — \`testId: "<value>"\` when the attribute is \`data-testid\`, otherwise \`attribute: "<name>", value: "<value>"\` (e.g. \`attribute: "data-cy"\`); no \`ref\` — the element no longer exists, so no snapshot has one; the tool checks the live page and refuses to record on a blank or un-rendered page. Then at least one \`browser_assert\` on a RETAINED element of the same page verifying its text, value or state. If a UI trace for that page is already planned, record the guard assertions inside that trace; otherwise this is its own trace and spec, \`verify-removed-ui-<page-slug>\`. The generated test asserts \`toBeHidden()\` on \`getByTestId(...)\` or \`page.locator('[data-cy="..."]')\` accordingly. A removed element the server did not list still gets its test (the removal check requires it) — ground that one in the diff and prefix its \`reasoning\` with \`[removed-element diff-grounded]\`; prefix \`reasoning\` with \`[removed-element server-listed]\` when the element came from \`uiContext.removedElements\`. **Deleted routes or pages are deleted features, not removed elements**: test the removal through the link or entry point that survives. A trace may still open the retired URL — to assert the app's fallback there, or that the old page's elements are gone — after it has recorded a positive \`browser_assert\` on a surviving page; a trace whose only visited page is the dead URL has no positive companion and is not a guard spec.
+  - **Renames are not removals — on every PR, whatever \`uiContext.removedElements\` holds**: when a test id, \`aria-label\` or other accessible name changed, assert the element by its new identifier and leave the retired identifier alone (no \`browser_assert_hidden\` on it). A rename PR removes nothing, so this rule applies when the removed list is empty.
   - **\`browser_visual_snapshot\` — for visual/appearance checks**: when the instruction asks to take a screenshot, capture a baseline, or verify how a page/element/region *looks* (not its text or value), call \`browser_visual_snapshot\` — it records a \`toHaveScreenshot()\` assertion so the generated test pixel-compares against a baseline on every run. Do NOT use \`browser_take_screenshot\` for this: it captures a throwaway image that is dropped at export and never appears in the generated test (use it only to view the page yourself).
   - **Wait for stable state before the second capture**: After performing an action that affects computed fields (filling a discount, submitting a form, adding an item), check the current page state before calling the second \`browser_blueprint\` (the capture after the action). If a computed field — total, price, count, derived text — still shows its initial empty or zero value (e.g. \`$0.00\`, \`0\`, \`Loading...\`, empty string), that means async data hasn't finished loading yet. Use \`browser_wait_for\` to wait up to 10 seconds for the field to update to a real value (for example, wait for the total to show a non-zero amount like \`$799.99\` instead of \`$0.00\`). Once the field shows a real value, THEN call the second \`browser_blueprint\` to capture stable state. If after 10 seconds the field still hasn't updated, skip the assertion on that field — don't capture and assert a value that hasn't loaded.
   If \`browser_navigate\` fails (app not running / connection refused), apply skip condition (a) above: leave the planned test in your plan, say in \`businessCaseAnalysis\` why it was not written, AND record the outage in \`issuesFound\`.
@@ -533,7 +534,6 @@ ${EXEC_FAIL.EXPECTED_FAILURE}. **Expected failure check (no retry):** If the fai
 
    **If you did confirm the missing or wrong operation in the source, do NOT make the test pass.** Never add a reset, cleanup, or setup call for isolation. Never weaken the assertion — no \`==\` to \`>=\`, no exact value to a range. A failing test whose diagnosis names a pre-existing bug is the most valuable output of this run; a passing version of it reports nothing.
 
-   **Visual snapshots — maintained tests only, and never a third run.** A newly generated test writes its baseline on its first run and cannot be stale, so this applies to an existing spec whose committed baseline the PR made out of date. That mismatch is known from the \`phase: "before"\` run, and the refresh rides the final run: pass the \`rebaseline_snapshots\` list \`skyramp_actions\` returned as \`rebaselineSnapshots\` on that one call. It never costs an extra execution — if a screenshot mismatch on a maintained test first appears on the final run, report \`Fail\`; do not add a run. The execution result names which baselines were refreshed and which were not; the report row's description carries the refreshed names automatically, so \`afterDetails\` states only the outcome (e.g. \`1 passed in 6.1s\`). If no diff line explains a mismatch, keep the test \`Fail\` and add an \`issuesFound\` entry. Never raise \`maxDiffPixelRatio\`, never remove the \`toHaveScreenshot()\` call, never edit or delete a PNG by hand, and never pass \`rebaselineSnapshots\` for a mismatch the diff does not explain.
 ${EXEC_FAIL.INFRA_RETRY}. Apply a targeted fix and retry **once** only for **infrastructure failures** — that means exactly **2 total \`skyramp_execute_test\` calls per test file** for these cases. Examples of infrastructure failures worth fixing:
    - Assertion mismatch from floating-point precision, or an expected value mis-transcribed from the observed response or computed with an arithmetic slip. If application behavior outside the diff explains the mismatch, it is not an infrastructure failure — use step ${EXEC_FAIL.EXPECTED_FAILURE} instead.
    - Import error, syntax error, or missing dependency in the generated test file${FIX_ERRORS_RETRY_HINT}

package/build/recommendation/types.d.ts

@@ -138,6 +138,9 @@ export interface VerifyContext {
      *  survives. A removal guard declares the element that is GONE, so no capture
      *  can hold it and this list is its only grounding. */
     removedUiElements: RemovedUiElement[];
+    /** Identifiers a rename replaced, empty when the diff renames nothing. Only the
+     *  server pairs the two sides of a diff. */
+    retiredUiElements: RemovedUiElement[];
     /** Whether a cited path names a file in any of the run's repositories. Injected
      *  to keep the verifiers filesystem-free. */
     citedFileExists(relativePath: string): boolean;

package/build/recommendation/verifierContracts.d.ts

@@ -201,180 +201,13 @@ export declare const REMOVED_ELEMENT_GUARDED_CONTRACT: {
             readonly message: "The diff removes `{element}` and no planned test says it is gone.";
             readonly suggestion: "Plan a UI test on the page that still renders, asserting this element is absent, and name it in that test's elements. Removing it is what this pull request ships, so the removal is what gets tested. If the diff shows it still rendering under a new identifier it is a rename, not a removal — say so as the answer.";
         };
-    };
-    readonly suggestion: "Does every element this diff removes have a planned test that asserts it is gone?";
-};
-/** In the order of `PLAN_TIME_VERIFIERS`, which decides the order objections are
- *  reported in and carries no priority. References, not copies: iterating this
- *  array, or indexing it with a variable, widens the element to the union of them
- *  all and then no `objections` key resolves. */
-export declare const VERIFIER_CONTRACTS: readonly [{
-    readonly id: "changedFile";
-    readonly declarationFields: readonly ["declarations.changedFile", "declarations.screenEvidence.file"];
-    readonly objections: {
-        readonly notStated: {
-            readonly message: "This test does not state which changed file it targets.";
-            readonly suggestion: "Name the repository-relative file this test is about in `changedFile`, spelled as the diff spells it.";
-        };
-        readonly unrelated: {
-            readonly message: "The file this test names as its changed file is not one this pull request changed.";
-            readonly suggestion: "Name a file from this PR's own diff in `changedFile`, repository-relative and spelled as the diff spells it — or say why this test belongs in the plan without one.";
-        };
-        readonly unknownRepository: {
-            readonly message: "This planned test names a repository this run did not analyze.";
-            readonly suggestion: "Name one of the repositories listed in the evidence, or leave `repository` out on a single-repository run. A name nothing analyzed leaves the planned test with no diff to be checked against.";
-        };
-        readonly screenEvidenceUnrelated: {
-            readonly message: "The file this UI test cites for its screen is not one this pull request changed.";
-            readonly suggestion: "Which changed file renders the screen this test opens — or which changed screen should it open instead? Name that file in `screenEvidence.file`, repository-relative, spelled as the diff spells it.";
+        readonly retired: {
+            readonly message: "This test names `{element}`. The diff pairs it with a new identifier on the same element, which reads as a rename and not a removal.";
+            readonly suggestion: "If this test asserts that identifier absent, assert the element by the one the diff adds instead — a guard on a retired identifier asserts a live element hidden. If the diff replaces the element rather than renaming it, or removes it as well, or the test names it for another reason, say so as the answer.";
         };
     };
-    readonly suggestion: "Which file that this pull request changed does this test target?";
-}, {
-    readonly id: "endpointGrounded";
-    readonly declarationFields: readonly ["steps[]", "testType", "declarations.routes"];
-    readonly objections: {
-        readonly uncited: {
-            readonly message: "A call this test makes cites no file that declares it.";
-            readonly suggestion: "Add a `routes` entry naming the repository file that declares it — the route or operation need not appear verbatim in that file. A route the endpoint catalog missed is evidence of nothing: cite the file and keep the planned test.";
-        };
-        readonly disqualifiedCitation: {
-            readonly message: "The file this test cites for a call cannot be the file that declares it.";
-            readonly suggestion: "Cite the source file that declares it — not a test, not built output, not documentation. Any language or format is accepted, and the route or operation need not appear verbatim in the file.";
-        };
-        readonly uncitedAndDisqualified: {
-            readonly message: "This test has a call with no citation, and a call whose cited file cannot be the file that declares it.";
-            readonly suggestion: "Add `routes` for the call that has none, and point the other citation at the source file that declares its route or operation. Neither need appear verbatim in the file.";
-        };
-    };
-    readonly suggestion: "Which repository file declares this route or operation, and does an entry name that step's `order`?";
-}, {
-    readonly id: "statedDifference";
-    readonly declarationFields: readonly ["steps[]", "testType", "scenarioName", "declarations.differsFrom"];
-    readonly objections: {
-        readonly unexplainedPair: {
-            readonly message: "Another planned test in this plan tests the same endpoint and neither says how they differ.";
-            readonly suggestion: "Two tests on one endpoint is a legitimate plan. This asks HOW they differ, not whether one should go. Add a `differsFrom` entry naming the other planned test and what this one asserts that it does not — or, if one really is redundant, drop it.";
-        };
-        readonly unknownPartner: {
-            readonly message: "A `differsFrom` entry names a partner that is not a planned test in this plan.";
-            readonly suggestion: "Spell the partner's `scenarioName` exactly as it appears in your own planned test list — the match is exact apart from surrounding space, so a difference in case names nothing.";
-        };
-        readonly subjectNotStated: {
-            readonly message: "This test makes more than one call and does not say which one it is about.";
-            readonly suggestion: "Set `declarations.stepUnderTest` to the `order` of the step under test. The other calls are setup, and nothing on the server ranks them for you.";
-        };
-    };
-    readonly suggestion: "Which call is this test about, and what does it assert that the other planned test on the same endpoint does not?";
-}, {
-    readonly id: "existingCoverage";
-    readonly declarationFields: readonly ["declarations.existingTests"];
-    readonly objections: {
-        readonly citedTestMissing: {
-            readonly message: "This planned test names an existing test file that is not in the checkout.";
-            readonly suggestion: "Name the file repository-relative, spelled as the analysis lists it. Drop the entry if it names a test you did not read — naming none is an answer too.";
-        };
-    };
-    readonly suggestion: "Which existing tests did you read on this change, and how does this planned test differ from them?";
-}, {
-    readonly id: "expectedOutcome";
-    readonly declarationFields: readonly ["category", "declarations.expected.outcome", "declarations.expected.why"];
-    readonly objections: {
-        readonly passInShouldFailCategory: {
-            readonly message: "This planned test is categorised \"{category}\" but expects to pass on the app as it stands.";
-            readonly suggestion: "If it catches a defect, it should be red until the defect is fixed — say so. If it pins behaviour that is already correct, change the category.";
-        };
-        readonly executed: {
-            readonly message: "This test failed, but it did not reach the behavior it was written for — it fell over earlier. A failure like this is not a caught bug.";
-            readonly suggestion: "If the blocker is the test's own setup — sign-in, token, a wrong path — fix it and run the test again. If the blocker is the defect this run reports (a route that is not mounted, a server error before the behaviour), answer this objection naming that issue: the failure then stands as evidence of that issue, not as a caught bug.";
-        };
-    };
-    readonly suggestion: "Should this test fail until the defect is fixed, or is the category wrong for a test that pins behaviour the app already has?";
-}, {
-    readonly id: "uiElementGrounded";
-    readonly declarationFields: readonly ["testType", "steps[]", "declarations.elements.items", "declarations.elements.pageUrl", "declarations.asserts", "scenarioName", "description", "declarations.expected.why"];
-    readonly objections: {
-        readonly nogrounding: {
-            readonly message: "This UI test names no `elements.items`, so nothing says the elements it targets are on the page.";
-            readonly suggestion: "Copy the elements this test targets out of the capture of the page it runs on into `elements.items`, and set `elements.pageUrl` to that page. If no captured page holds this test's elements — the changed component mounts nowhere the run reached, or the screen is behind a gate this run could not pass — answer this objection saying which, and leave `elements.items` null.";
-        };
-        readonly duplicate: {
-            readonly message: "`elements.items` names the same element more than once.";
-            readonly suggestion: "List each element once. Two entries that agree on role, name and identifiers describe one element, and the repeat states nothing the first entry did not.";
-        };
-        readonly pagecontext: {
-            readonly message: "This UI test names `elements.items` but no page they came from.";
-            readonly suggestion: "Set `elements.pageUrl` to the `url` of the capture the elements were lifted from. Without it there is no page to look them up on.";
-        };
-        readonly ungrounded: {
-            readonly message: "An element this UI test targets is in no blueprint captured for that page.";
-            readonly suggestion: "Cite what a capture shows you, never what the screen ought to have. A capture shows the page as it stood when it was taken, so an element behind a modal, a dropdown or an accordion is legitimately absent — answer this objection naming the action that reveals it. Otherwise copy the element from the capture as it is spelled there, or point `elements.pageUrl` at the page you actually captured.";
-        };
-    };
-    readonly suggestion: "Which capture of the page does each declared element come from, and for one that is in no capture, which action on that page reveals it?";
-}, {
-    readonly id: "screenRoute";
-    readonly declarationFields: readonly ["declarations.elements.pageUrl", "declarations.screenEvidence.file", "declarations.changedFile"];
-    readonly objections: {
-        readonly mismatch: {
-            readonly message: "The page this UI test opens is not a page that renders the changed file it is about.";
-            readonly suggestion: "Open one of the routes in the evidence, or name the changed file that does render this page in `screenEvidence.file`. `skyramp_resolve_screen` gives the url to open, with the route parameters it can fill. A trace recorded on a screen the diff did not change proves nothing about the change.";
-        };
-        readonly unmounted: {
-            readonly message: "No route this run found renders the file this UI test is about.";
-            readonly suggestion: "If a route in this PR mounts it, name that route in `elements.pageUrl`. If nothing mounts it, the component is unintegrated: say so in one line and keep the planned test out of the browser.";
-        };
-    };
-    readonly suggestion: "Does the page this test opens render the changed file the test is about?";
-}, {
-    readonly id: "coverage";
-    readonly declarationFields: readonly ["changes", "declarations.changes", "declarations.changedFile", "declarations.routes", "declarations.screenEvidence.file", "declarations.startState", "changes[].cases", "changes[].surfaces"];
-    readonly objections: {
-        readonly change: {
-            readonly message: "This declared change has no test in the plan.";
-            readonly suggestion: "Plan a test that exercises it. If this run cannot write one, answer it and set `blocker` to what stopped the run — a service that is not running, a paired branch that no longer exists, the one credential the run holds. An answer with no blocker leaves this open: a change nothing prevented a test from reaching takes the test. Coverage per file is the basic minimum; coverage per change is what the plan is judged by, so a file covered by a shape test still leaves the change it makes untested.";
-        };
-        readonly noChanges: {
-            readonly message: "The plan declares no changes, so nothing says what the pull request must make different.";
-            readonly suggestion: "List the behaviours the pull request description promises, one sentence each, and cite them from the planned tests that test them — or answer in one line that it promises none, which a docs-only or cosmetic change legitimately does.";
-        };
-        readonly unknownChange: {
-            readonly message: "A planned test cites a change id that this plan does not declare.";
-            readonly suggestion: "Spell the change's `id` exactly as your own `changes` list gives it — the match is exact apart from surrounding space. Declare the change if it is missing.";
-        };
-        readonly file: {
-            readonly message: "This changed file has no test in the plan.";
-            readonly suggestion: "Add a planned test that cites it — as `changedFile`, as a `routes` file, or as `screenEvidence.file` — or answer in ONE line why it needs none: config only, covered by the test on the route it serves, or style-only and covered by the UI test on the page it belongs to. This check is a floor, never a cap: it never asks you to plan fewer tests.";
-        };
-        readonly stateTest: {
-            readonly message: "No test in this plan names the state the record is in when {route} mutates it.";
-            readonly suggestion: "Plan one test that puts a record in a stated state — through the API, the UI, or data the app already holds; a record with no rows yet counts — then runs the mutation on it, and name that state as `startState`. If the route can meet a record that is not freshly created, use that state. Only a planned test closes this: there is no answer for it.";
-        };
-        readonly cases: {
-            readonly message: "No test for this change sends the declared case {missing}.";
-            readonly suggestion: "Add the missing values to a test that cites this change, or answer in one line why they need no test.";
-        };
-        readonly reject: {
-            readonly message: "`{param}` accepts `{value}`, a record the plan creates, and no case rejects a record that is not there or belongs to another parent.";
-            readonly suggestion: "Add a reject case on `{param}` with a value that is not that record and a step that sends it, or answer why the route cannot refuse it.";
-        };
-        readonly surface: {
-            readonly message: "No {kind} test cites this change, which is on the {surface}.";
-            readonly suggestion: "Add a test on that surface that cites this change, or answer in one line why that surface needs no test.";
-        };
-    };
-    readonly suggestion: "Which planned test tests each behaviour this change promises and each file it touches, and for one nothing covers, why does it need none?";
-}, {
-    readonly id: "removedElementGuarded";
-    readonly declarationFields: readonly ["declarations.elements.items", "declarations.asserts"];
-    readonly objections: {
-        readonly missing: {
-            readonly message: "The diff removes `{element}` and no planned test says it is gone.";
-            readonly suggestion: "Plan a UI test on the page that still renders, asserting this element is absent, and name it in that test's elements. Removing it is what this pull request ships, so the removal is what gets tested. If the diff shows it still rendering under a new identifier it is a rename, not a removal — say so as the answer.";
-        };
-    };
-    readonly suggestion: "Does every element this diff removes have a planned test that asserts it is gone?";
-}];
+    readonly suggestion: "Does every element this diff removes have a planned test that asserts it is gone, and does no test claim a renamed identifier is gone?";
+};
 /** Fills a contract sentence's `{placeholder}` spans from the run's or the
  *  planned test's own values. A placeholder with no value is left as written rather
  *  than blanked, so a missed key shows up as `{knob}` instead of reading as a gap

package/build/recommendation/verifierContracts.js

@@ -236,24 +236,16 @@ export const REMOVED_ELEMENT_GUARDED_CONTRACT = {
             message: "The diff removes `{element}` and no planned test says it is gone.",
             suggestion: "Plan a UI test on the page that still renders, asserting this element is absent, and name it in that test's elements. Removing it is what this pull request ships, so the removal is what gets tested. If the diff shows it still rendering under a new identifier it is a rename, not a removal — say so as the answer.",
         },
+        // A question, not an accusation, on two counts: the check sees the identifier
+        // NAMED and a plan has no field that says "absent", and the pairing that produced
+        // the list cannot tell a rename from a same-shape replacement.
+        retired: {
+            message: "This test names `{element}`. The diff pairs it with a new identifier on the same element, which reads as a rename and not a removal.",
+            suggestion: "If this test asserts that identifier absent, assert the element by the one the diff adds instead — a guard on a retired identifier asserts a live element hidden. If the diff replaces the element rather than renaming it, or removes it as well, or the test names it for another reason, say so as the answer.",
+        },
     },
-    suggestion: "Does every element this diff removes have a planned test that asserts it is gone?",
+    suggestion: "Does every element this diff removes have a planned test that asserts it is gone, and does no test claim a renamed identifier is gone?",
 };
-/** In the order of `PLAN_TIME_VERIFIERS`, which decides the order objections are
- *  reported in and carries no priority. References, not copies: iterating this
- *  array, or indexing it with a variable, widens the element to the union of them
- *  all and then no `objections` key resolves. */
-export const VERIFIER_CONTRACTS = [
-    CHANGED_FILE_CONTRACT,
-    ENDPOINT_GROUNDED_CONTRACT,
-    STATED_DIFFERENCE_CONTRACT,
-    EXISTING_COVERAGE_CONTRACT,
-    EXPECTED_OUTCOME_CONTRACT,
-    UI_ELEMENT_GROUNDED_CONTRACT,
-    SCREEN_ROUTE_CONTRACT,
-    COVERAGE_CONTRACT,
-    REMOVED_ELEMENT_GUARDED_CONTRACT,
-];
 /** Fills a contract sentence's `{placeholder}` spans from the run's or the
  *  planned test's own values. A placeholder with no value is left as written rather
  *  than blanked, so a missed key shows up as `{knob}` instead of reading as a gap

package/build/recommendation/verifiers/removedElementGuarded.js

@@ -1,3 +1,5 @@
+import { REMOVED_ELEMENT_GUARDED_CONTRACT, fillPlaceholders } from "../verifierContracts.js";
+import { escapeRegExp } from "../../utils/regex.js";
 /** Verifier 9. Every element the diff removed needs a planned test that says it is
  *  gone.
  *
@@ -9,28 +11,53 @@
  *  decide which page the element belongs on, and is not free to leave it out.
  *
  *  This is the direction `uiElementGrounded` does not check. That one asks whether
- *  a declared element is real; this one asks whether a real removal was declared. */
+ *  a declared element is real; this one asks whether a real removal was declared.
+ *
+ *  The retired case is the reverse claim, which nothing else checks: a plan naming an
+ *  identifier the diff renamed, where a guard would assert a live element hidden. It
+ *  sees a MENTION, not an absence claim — the plan has no field for one — so it asks
+ *  rather than accuses. `data-*` only, all the extractor reads; a renamed `aria-label`
+ *  is the prompt's to catch. */
+const { missing: MISSING, retired: RETIRED } = REMOVED_ELEMENT_GUARDED_CONTRACT.objections;
 const text = (value) => (typeof value === "string" ? value.trim() : "");
+function declaresElement(plannedTest, value) {
+    const declared = plannedTest?.declarations;
+    const items = Array.isArray(declared?.elements?.items) ? declared.elements.items : [];
+    return items.some((item) => text(item?.testId) === value || text(item?.stableId) === value);
+}
 /** How a plan names an element. `testId` is the one field that carries the value
  *  for a `data-testid`; a guard on `data-cy` or `data-qa` reaches the plan with
  *  `testId` null, so the value is looked for in the prose the test states too. */
 function namesElement(plannedTest, value) {
-    const declared = plannedTest?.declarations;
-    const items = Array.isArray(declared?.elements?.items) ? declared.elements.items : [];
-    if (items.some((item) => text(item?.testId) === value || text(item?.stableId) === value))
+    if (declaresElement(plannedTest, value))
         return true;
-    return [text(declared?.asserts), text(plannedTest?.plannedTestId)].some((prose) => prose.includes(value));
+    return [text(plannedTest?.declarations?.asserts), text(plannedTest?.plannedTestId)].some((prose) => prose.includes(value));
+}
+/** Whole-identifier match. This case objects on a hit, so `includes` would raise
+ *  `nav-clear` against a test about `nav-clear-state-banner`. */
+function mentionsIdentifier(prose, value) {
+    return new RegExp(`(^|[^\\w:-])${escapeRegExp(value)}(?![\\w:-])`).test(prose);
+}
+/** No `plannedTestId`: the prompt names guard specs `verify-removed-ui-<id>`, so every
+ *  correct one carries the identifier in its name. */
+function retiredIdentifierNamedBy(plannedTest, value) {
+    if (declaresElement(plannedTest, value))
+        return true;
+    return mentionsIdentifier(text(plannedTest?.declarations?.asserts), value);
 }
 /** `attribute=value` identifies an element across the run, so the objection id is
  *  the same string on every registration whatever order the list arrives in. */
 const objectionIdFor = (element) => `removedElementGuarded:${text(element?.attribute)}=${text(element?.value)}`;
+/** Keyed by the test too: one answer must not close another test's objection. */
+const retiredObjectionIdFor = (element, plannedTestId) => `removedElementGuarded:retired:${text(element?.attribute)}=${text(element?.value)}:${plannedTestId || "plan"}`;
 export const removedElementGuarded = {
     name: "removedElementGuarded",
     run(registration, ctx) {
-        const removed = Array.isArray(ctx?.removedUiElements) ? ctx.removedUiElements : [];
-        if (removed.length === 0)
+        const { removedUiElements: removed, retiredUiElements: retired } = ctx;
+        // A rename PR removes nothing, so an empty `removed` is when the retired case runs.
+        if (removed.length === 0 && retired.length === 0)
             return [];
-        const plannedTests = Array.isArray(registration?.plannedTests) ? registration.plannedTests : [];
+        const plannedTests = registration.plannedTests;
         const objections = [];
         const seen = new Set();
         for (const element of removed) {
@@ -47,11 +74,38 @@ export const removedElementGuarded = {
             objections.push({
                 objectionId,
                 verifier: "removedElementGuarded",
-                message: `The diff removes \`${attribute}="${value}"\` and no planned test says it is gone.`,
+                message: fillPlaceholders(MISSING.message, { element: `${attribute}="${value}"` }),
                 evidence: `removed from ${text(element?.file) || "a changed frontend file"}; no planned test names ${value}`,
-                suggestion: "Plan a UI test on the page that still renders, asserting this element is absent, and name it in that test's elements. Removing it is what this pull request ships, so the removal is what gets tested. If the diff shows it still rendering under a new identifier it is a rename, not a removal — say so as the answer.",
+                suggestion: MISSING.suggestion,
             });
         }
+        // Also removed somewhere means removed, whatever one hunk's pairing made of it.
+        // Keyed the way the rest of the contract keys an element: `data-cy="legacy"` going
+        // away says nothing about `data-testid="legacy"` being renamed.
+        const removedKeys = new Set(removed.map((element) => `${text(element?.attribute)}=${text(element?.value)}`).filter((key) => key !== "="));
+        for (const element of retired) {
+            const value = text(element?.value);
+            const attribute = text(element?.attribute);
+            if (!value || !attribute || removedKeys.has(`${attribute}=${value}`))
+                continue;
+            for (const plannedTest of plannedTests) {
+                if (!retiredIdentifierNamedBy(plannedTest, value))
+                    continue;
+                const plannedTestId = text(plannedTest?.plannedTestId);
+                const objectionId = retiredObjectionIdFor(element, plannedTestId);
+                if (seen.has(objectionId))
+                    continue;
+                seen.add(objectionId);
+                objections.push({
+                    objectionId,
+                    verifier: "removedElementGuarded",
+                    ...(plannedTestId ? { plannedTestId } : {}),
+                    message: fillPlaceholders(RETIRED.message, { element: `${attribute}="${value}"` }),
+                    evidence: `${text(element?.file) || "a changed frontend file"} pairs ${value} with a new identifier on the same element, which reads as a rename; planned test ${plannedTestId || "(unnamed)"} names ${value}`,
+                    suggestion: RETIRED.suggestion,
+                });
+            }
+        }
         return objections;
     },
 };

package/build/tools/executeSkyrampTestTool.js

@@ -212,6 +212,14 @@ export function authorizeRebaseline(stateData, testFile, requested) {
             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.`,
         };
     }
+    // SKYR-4334: the before-run is the evidence. If it passed, no baseline is stale — either the
+    // committed picture already matches, or there was no picture and that run just created one.
+    // A refresh here would rewrite a current picture and let the report claim a fix that fixed nothing.
+    if (entry.executionBefore.status === TestExecutionStatus.Pass) {
+        return {
+            error: `rebaselineSnapshots refused: the phase: "before" run of ${path.basename(testFile)} passed, so no visual baseline is stale (a missing baseline is created by that run). There is nothing to refresh — leave the test as it is and record it as VERIFY, not UPDATE.`,
+        };
+    }
     return {};
 }
 /**

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

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { logger } from "../../utils/logger.js";
 import { StateManager, } from "../../utils/AnalysisStateManager.js";
 import { TestSource, DriftAction, RecommendationPriority, EstimatedWork } from "../../types/TestAnalysis.js";
+import { TestExecutionStatus } from "../../types/TestExecution.js";
 import { TestType } from "../../types/TestTypes.js";
 import * as fs from "fs";
 import * as path from "path";
@@ -325,14 +326,34 @@ export function registerActionsTool(server) {
                     if (!validBaselines.includes(name))
                         validBaselines.push(name);
                 }
+                // SKYR-4334: a refresh is only meaningful when the recorded phase: "before" run showed
+                // a mismatch. If that run passed, nothing is stale (a missing picture is created by
+                // that run), so the list is dropped here rather than refused later by
+                // skyramp_execute_test — and a rebaseline-only UPDATE has nothing left to do, so it
+                // is recorded as VERIFY. When no before-run is recorded yet, the execute-time gate
+                // still applies.
+                let actionForVerdict = rec.action;
+                let rationaleForVerdict = rec.rationale;
+                if (rec.action === DriftAction.Update && validBaselines.length) {
+                    const beforeRun = catalogByFile.get(resolvedFile)?.executionBefore;
+                    if (beforeRun?.status === TestExecutionStatus.Pass) {
+                        const dropped = validBaselines.splice(0, validBaselines.length);
+                        const rebaselineOnly = !rec.updateInstructions?.trim();
+                        droppedRebaselineNotes.push(`${rec.testFilePath}: rebaselineSnapshots [${dropped.join(", ")}] dropped — the phase: "before" run passed, so no baseline is stale (a missing baseline is created by that run). ${rebaselineOnly ? "Recorded as VERIFY: there is nothing to maintain." : "The UPDATE is held to its spec/POM edit only."}`);
+                        if (rebaselineOnly) {
+                            actionForVerdict = DriftAction.Verify;
+                            rationaleForVerdict = `${rec.rationale} [rebaseline dropped: the pre-edit run passed, so the baseline is not stale]`;
+                        }
+                    }
+                }
                 recommendations.push({
                     testFilePath: resolvedFile,
                     pomFile: resolvedPomFile,
-                    action: rec.action,
+                    action: actionForVerdict,
                     testType: rec.testType,
                     endpoint: rec.endpoint,
                     priority: rec.priority ?? RecommendationPriority.Medium,
-                    rationale: rec.rationale,
+                    rationale: rationaleForVerdict,
                     estimatedWork: rec.estimatedWork ?? EstimatedWork.Small,
                     updateInstructions: rec.updateInstructions ?? "",
                     renamedEndpoints: rec.renamedEndpoints ?? [],
@@ -341,13 +362,13 @@ export function registerActionsTool(server) {
                     // 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
+                    ...(actionForVerdict === 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,
+                            rebaselineOnly: !rec.updateInstructions?.trim(),
                         }
                         : {}),
                 });

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

@@ -66,6 +66,8 @@ export interface AnalyzeChangesData {
      */
     uiContext?: {
         removedElements?: RemovedUiElement[];
+        /** Identifiers a rename replaced. Never guard these; the removal check reads them. */
+        retiredElements?: RemovedUiElement[];
     };
     /** Set when the call returned before analysis, and why. */
     /** The one instruction the result keeps: which tool comes next. */
@@ -141,18 +143,41 @@ export declare const analyzeChangesOutputSchema: {
             file: string;
             attribute: string;
         }>, "many">>;
+        retiredElements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            attribute: z.ZodString;
+            value: z.ZodString;
+            file: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            file: string;
+            attribute: string;
+        }, {
+            value: string;
+            file: string;
+            attribute: string;
+        }>, "many">>;
     }, "strip", z.ZodTypeAny, {
         removedElements?: {
             value: string;
             file: string;
             attribute: string;
         }[] | undefined;
+        retiredElements?: {
+            value: string;
+            file: string;
+            attribute: string;
+        }[] | undefined;
     }, {
         removedElements?: {
             value: string;
             file: string;
             attribute: string;
         }[] | undefined;
+        retiredElements?: {
+            value: string;
+            file: string;
+            attribute: string;
+        }[] | undefined;
     }>>;
     nextStep: z.ZodOptional<z.ZodString>;
 };

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

@@ -15,7 +15,7 @@ import { AnalysisScope } from "../../types/RepositoryAnalysis.js";
 import { computeBranchDiff, changedFileNames, } from "../../utils/branchDiff.js";
 import { detectProjectMetadata } from "../../utils/projectMetadata.js";
 import { diffBlocksByPath } from "../../utils/branchDiff.js";
-import { collectRemovedUiElements } from "../../utils/removedUiElements.js";
+import { collectUiIdentifierChanges } from "../../utils/removedUiElements.js";
 import { parseTraceFile, discoverTraceFiles, discoverPlaywrightZips, } from "../../utils/trace-parser.js";
 import { TestSource } from "../../types/TestAnalysis.js";
 /** Exported for testing: maps a parsed trace result to a TraceFile. */
@@ -101,6 +101,11 @@ export const analyzeChangesInputSchema = {
         .default(false)
         .describe("When true, diffs the base ref against the working tree (captures uncommitted and unstaged changes). Use for local-dev workflows. Defaults to false (CI mode — committed changes only)."),
 };
+/** Both halves of `uiContext` carry the same record, so the shape is declared once.
+ *  It mirrors `RemovedUiElement`; the assignment below fails to compile if either drifts. */
+const uiIdentifierShape = z.object({ attribute: z.string(), value: z.string(), file: z.string() });
+const _uiIdentifierShapeMatchesType = {};
+void _uiIdentifierShapeMatchesType;
 /** SKYR-4182: structuredContent needs a declared outputSchema, and the schema
  *  has to accept the early exit as well as a full analysis — hence the optional
  *  fields. */
@@ -134,9 +139,8 @@ export const analyzeChangesOutputSchema = {
         .optional(),
     uiContext: z
         .object({
-        removedElements: z
-            .array(z.object({ attribute: z.string(), value: z.string(), file: z.string() }))
-            .optional(),
+        removedElements: z.array(uiIdentifierShape).optional(),
+        retiredElements: z.array(uiIdentifierShape).optional(),
     })
         .optional(),
     nextStep: z.string().optional(),
@@ -529,9 +533,10 @@ export function registerAnalyzeChangesTool(server) {
                 // check requires, since a removed element appears in no blueprint.
                 // Purely additive: a failure here must never cost the analyze call.
                 let removedElements = [];
+                let retiredElements = [];
                 if (diffData?.diffContent) {
                     try {
-                        removedElements = collectRemovedUiElements({
+                        ({ removed: removedElements, retired: retiredElements } = collectUiIdentifierChanges({
                             // Every changed file that is not a test. A removed `data-testid`
                             // is found by reading the diff, not by the file's extension.
                             changedFrontendFiles: (diffData.changedFiles ?? []).filter((f) => !isTestFile(f)),
@@ -542,13 +547,14 @@ export function registerAnalyzeChangesTool(server) {
                                 ...discoveredRelevantExternalPaths,
                             ],
                             discoveryFailed: testDiscoveryFailed,
-                        });
+                        }));
                     }
                     catch (err) {
                         logger.warning("removedUiElements: collection failed, continuing without removal-guard grounding", {
                             error: err instanceof Error ? err.message : String(err),
                         });
                         removedElements = [];
+                        retiredElements = [];
                     }
                 }
                 if (removedElements.length > 0) {
@@ -557,7 +563,7 @@ export function registerAnalyzeChangesTool(server) {
                         removed: removedElements.map((e) => `${e.attribute}="${e.value}"`),
                     });
                 }
-                return removedElements.length > 0 ? { removedElements } : {};
+                return { removedElements, retiredElements };
             })();
             // The server proposes no tests. It returns the analysis; the agent
             // drafts its own plan from it and registers that through
@@ -667,7 +673,9 @@ export function registerAnalyzeChangesTool(server) {
                     ...(wsSchemaPath ? { openApiSpecPath: wsSchemaPath } : {}),
                     openApiSpecLoaded: specFetchSucceeded,
                 },
-                ...(uiContext?.removedElements?.length ? { uiContext } : {}),
+                // Removed half only. No prompt describes `retiredElements`, and beside the guard
+                // list it reads as more guards to record; the plan checks read the state file.
+                ...(uiContext?.removedElements.length ? { uiContext: { removedElements: uiContext.removedElements } } : {}),
                 nextStep: "skyramp_analyze_test_health, with this stateFile",
             });
         }

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

@@ -547,6 +547,7 @@ export async function buildVerifyContext(state) {
         // removal guard names an element that renders nowhere, so this list is the
         // only thing that can tell an honest one from an invented element.
         removedUiElements: sections.flatMap((section) => section.data?.uiContext?.removedElements ?? []),
+        retiredUiElements: sections.flatMap((section) => section.data?.uiContext?.retiredElements ?? []),
         citedFileExists: makeCitedFileCheck(state),
         routesRenderingFile: makeScreenRouteResolver(state),
     };

package/build/utils/AnalysisStateManager.d.ts

@@ -125,6 +125,8 @@ export interface UiAnalysisContext {
      * (`toBeHidden()` on the id + a positive sibling assertion) for each entry.
      */
     removedElements?: RemovedUiElement[];
+    /** Identifiers a rename replaced. Read by the removal check. */
+    retiredElements?: RemovedUiElement[];
 }
 /** A pre-existing Skyramp-generated test the reuse pass edited to import from a
  *  shared utils file (STEP 5c / the sibling-inline advisory). Keyed by ABSOLUTE

package/build/utils/frontendSelectors.d.ts

@@ -41,8 +41,10 @@ export declare function extractAddedAttributeValues(diff: string): string[];
  *     element's handlers does not pair. An element whose changed lines carry nothing
  *     but the identifier pairs by tag alone: a relabelled rename (`clear-state` →
  *     `reset-session`, "Clear State" → "Reset Session") and a same-shape replacement
- *     are the same diff, and the tie goes to rename — a guard on a retired identifier
- *     passes vacuously, and the agent still reads the diff for what the list lacks. A paired added element is consumed, so one addition
+ *     are the same diff, and the tie goes to rename. So `retired` is what the pairing
+ *     made of the hunk, not a fact about the diff: a same-shape replacement lands there
+ *     too, and the removal check then asks the run about a guard that is right. The
+ *     objection is answerable and the run keeps the test. A paired added element is consumed, so one addition
  *     suppresses one removal, not every removal in the hunk. SKYR-4339: pairing by tag
  *     alone consumed a genuinely removed `<a href="#">` with a genuinely added
  *     `<a href="https://…">` in the same hunk (judgement eval RG03), so the guard was
@@ -52,4 +54,11 @@ export declare function extractAddedAttributeValues(diff: string): string[];
  * (`toBeHidden()` on `getByTestId(value)` for `data-testid`, on
  * `locator('[<attribute>="<value>"]')` for any other `data-*`).
  */
+/** `retired` is the identifier a rename replaced. Only the pairing below knows it,
+ *  and it used to be discarded there. */
+export interface AttributeChanges {
+    removed: RemovedAttribute[];
+    retired: RemovedAttribute[];
+}
 export declare function extractRemovedAttributes(fileDiff: string, addedValuesElsewhere?: Iterable<string>): RemovedAttribute[];
+export declare function extractAttributeChanges(fileDiff: string, addedValuesElsewhere?: Iterable<string>): AttributeChanges;

package/build/utils/frontendSelectors.js

@@ -119,42 +119,10 @@ export function extractAddedAttributeValues(diff) {
     }
     return [...out];
 }
-/**
- * Identifying `data-*` attributes one file's diff REMOVED: literals on `-` lines, minus the
- * cases where the element still renders somewhere:
- *
- *   - **moved / extracted** — the same value appears on a `+` line of this file or, via
- *     `addedValuesElsewhere`, anywhere else in the diff (a component extracted into a new
- *     file is the common shape);
- *   - **not an element** — a `-` line counts only when it opens a JSX/HTML tag or is a
- *     wrapped attribute line of a tag opened above it, on a changed or an unchanged
- *     line (the tag is carried until the `>` that closes it; a `>` inside a quoted
- *     value, a `{…}` expression or an `=>` arrow is content and does not close it). A deleted comment, docs snippet, story arg or page-object
- *     `getByTestId(...)` call that merely mentions the attribute is not an element
- *     removal — the element itself may well survive on an unchanged context line;
- *   - **renamed** — a rename cannot be told apart by literal identity (old and new
- *     value differ by definition), so it is paired structurally: within the same hunk,
- *     each removed ELEMENT is paired with AT MOST ONE added element that opens the same
- *     tag, carries a NEW identifying attribute, and keeps every other attribute NAME
- *     the removed element set on its changed lines (a rename may add attributes or
- *     edit their values, never drop one). With the tag kept on a context line, the
- *     changed lines are exactly the attributes that differ, so an in-place rename
- *     compares only what it touched while an in-place replacement that drops the old
- *     element's handlers does not pair. An element whose changed lines carry nothing
- *     but the identifier pairs by tag alone: a relabelled rename (`clear-state` →
- *     `reset-session`, "Clear State" → "Reset Session") and a same-shape replacement
- *     are the same diff, and the tie goes to rename — a guard on a retired identifier
- *     passes vacuously, and the agent still reads the diff for what the list lacks. A paired added element is consumed, so one addition
- *     suppresses one removal, not every removal in the hunk. SKYR-4339: pairing by tag
- *     alone consumed a genuinely removed `<a href="#">` with a genuinely added
- *     `<a href="https://…">` in the same hunk (judgement eval RG03), so the guard was
- *     never listed.
- *
- * Feeds `uiContext.removedElements` (SKYR-4305) — the grounding for a removal guard
- * (`toBeHidden()` on `getByTestId(value)` for `data-testid`, on
- * `locator('[<attribute>="<value>"]')` for any other `data-*`).
- */
 export function extractRemovedAttributes(fileDiff, addedValuesElsewhere = []) {
+    return extractAttributeChanges(fileDiff, addedValuesElsewhere).removed;
+}
+export function extractAttributeChanges(fileDiff, addedValuesElsewhere = []) {
     const addedAnywhere = new Set(addedValuesElsewhere);
     for (const v of extractAddedAttributeValues(fileDiff))
         addedAnywhere.add(v);
@@ -196,7 +164,9 @@ export function extractRemovedAttributes(fileDiff, addedValuesElsewhere = []) {
         return t.includes(">");
     };
     const out = [];
+    const retired = [];
     const seen = new Set();
+    const seenRetired = new Set();
     for (const hunk of hunks) {
         // Group changed lines into elements per side: an element starts on the line that
         // opens its tag and carries on until the `>` that closes the opening tag, so a
@@ -269,6 +239,16 @@ export function extractRemovedAttributes(fileDiff, addedValuesElsewhere = []) {
             });
             if (partner) {
                 partner.consumed = true;
+                for (const a of r.ids) {
+                    // Pairing does not require the id to change: an edited line pairs with itself.
+                    if (addedAnywhere.has(a.value))
+                        continue;
+                    const key = `${a.attribute}=${a.value}`;
+                    if (!seenRetired.has(key)) {
+                        seenRetired.add(key);
+                        retired.push(a);
+                    }
+                }
                 continue;
             }
             for (const a of r.ids) {
@@ -280,5 +260,5 @@ export function extractRemovedAttributes(fileDiff, addedValuesElsewhere = []) {
             }
         }
     }
-    return out;
+    return { removed: out, retired };
 }

package/build/utils/removedUiElements.d.ts

@@ -19,4 +19,11 @@ export interface CollectRemovedUiElementsInput {
     /** Injectable for tests; defaults to a tolerant fs read that logs failures. */
     readFile?: (absPath: string) => string | undefined;
 }
+/** `retired` holds the identifiers a rename replaced. No existing-test filter: that
+ *  filter answers "is this maintenance", which a false guard is not. */
+export interface UiIdentifierChanges {
+    removed: RemovedUiElement[];
+    retired: RemovedUiElement[];
+}
 export declare function collectRemovedUiElements(input: CollectRemovedUiElementsInput): RemovedUiElement[];
+export declare function collectUiIdentifierChanges(input: CollectRemovedUiElementsInput): UiIdentifierChanges;

package/build/utils/removedUiElements.js

@@ -26,7 +26,7 @@
  * 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 { extractAddedAttributeValues, extractAttributeChanges } from "./frontendSelectors.js";
 import { escapeRegExp } from "./regex.js";
 import { logger } from "./logger.js";
 function defaultReadFile(absPath) {
@@ -51,9 +51,12 @@ function referencesLiteral(content, value) {
     return new RegExp(`(^|[^\\w:-])${escapeRegExp(value)}(?![\\w:-])`).test(content);
 }
 export function collectRemovedUiElements(input) {
+    return collectUiIdentifierChanges(input).removed;
+}
+export function collectUiIdentifierChanges(input) {
+    // Only the REMOVED half reads the existing tests, so only that half fails closed.
     if (input.discoveryFailed) {
-        logger.warning("removedUiElements: test discovery failed — cannot tell whether an existing test covers a removed id; reporting none");
-        return [];
+        logger.warning("removedUiElements: test discovery failed — cannot tell whether an existing test covers a removed id; reporting removals as none, retired identifiers as normal");
     }
     const readFile = input.readFile ?? defaultReadFile;
     const deleted = new Set(input.deletedFiles);
@@ -76,7 +79,9 @@ export function collectRemovedUiElements(input) {
         return testContents.some((c) => referencesLiteral(c, value));
     };
     const out = [];
+    const retired = [];
     const seen = new Set();
+    const seenRetired = new Set();
     for (const file of input.changedFrontendFiles) {
         if (deleted.has(file)) {
             skip(file, "file deleted by the diff (whole surface removed)");
@@ -87,7 +92,15 @@ export function collectRemovedUiElements(input) {
             skip(file, "no diff slice");
             continue;
         }
-        const attrs = extractRemovedAttributes(slice, addedAcrossDiff);
+        const changes = extractAttributeChanges(slice, addedAcrossDiff);
+        for (const { attribute, value } of changes.retired) {
+            const key = `${attribute}=${value}`;
+            if (seenRetired.has(key))
+                continue;
+            seenRetired.add(key);
+            retired.push({ attribute, value, file });
+        }
+        const attrs = input.discoveryFailed ? [] : changes.removed;
         if (attrs.length === 0)
             continue;
         for (const { attribute, value } of attrs) {
@@ -102,5 +115,5 @@ export function collectRemovedUiElements(input) {
             out.push({ attribute, value, file });
         }
     }
-    return out;
+    return { removed: out, retired };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/mcp",
-  "version": "0.4.0-rc.1",
+  "version": "0.4.0",
   "main": "build/index.js",
   "exports": {
     ".": "./build/index.js",