@skyramp/mcp 0.2.150-rc.mntnc → 0.2.150-rc.ui.mntnc

package/build/prompts/test-maintenance/drift-analysis-prompt.d.ts

@@ -1,4 +1,17 @@
-export declare function buildDriftAnalysisPrompt(stateFile?: string, existingTests?: Array<{
+export type UiDriftParams = {
+    tests: Array<{
+        testFile: string;
+    }>;
+    changedFrontendFiles: string[];
+    blueprintCaptured?: boolean;
+};
+/**
+ * Build the drift analysis prompt.
+ * - apiTests: tests to assess for API endpoint drift (always included unless empty and ui is provided).
+ * - ui: when provided, appends a UI drift section for component/browser tests.
+ *   Omit when no frontend files changed or no UI tests exist.
+ */
+export declare function buildDriftAnalysisPrompt(stateFile: string | undefined, apiTests: Array<{
     testFile: string;
     source?: string;
-}>): string;
+}>, ui?: UiDriftParams): string;

package/build/prompts/test-maintenance/drift-analysis-prompt.js

@@ -1,6 +1,7 @@
 import { buildActionDecisionTree, buildCheckAdditiveFields, buildCheckEndpointExistence, buildCheckResponseShape, buildCheckAuthAndAuthorization, buildCheckBehavioralContract, buildCheckAssignAction, buildDriftOutputChecklist, } from "./driftAnalysisSections.js";
+import { buildUiActionDecisionTree, buildUiCheckRouteExistence, buildUiCheckSelectors, buildUiCheckPageObjects, buildUiCheckBehavioralChanges, buildUiCheckAssignAction, buildUiCheckExportedSymbols, buildUiDriftOutputChecklist, } from "./uiDriftAnalysisSections.js";
 import { PromptPlan } from "../test-recommendation/promptPlan.js";
-const _plan = new PromptPlan()
+const _apiPlan = new PromptPlan()
     .addPhase("maintenance", "Test Maintenance Assessment", {
     headerLevel: "##",
     stepFormat: "hash",
@@ -14,6 +15,58 @@ const _plan = new PromptPlan()
     .subStep("ASSIGN_ACTION", "Assign action", () => buildCheckAssignAction())
     .step("CALL_TOOL", "Submit recommendations", (p) => buildDriftOutputChecklist(p.stateFile, p.existingTests))
     .done();
-export function buildDriftAnalysisPrompt(stateFile, existingTests) {
-    return `<drift_analysis_rules>\n${_plan.render({ stateFile, existingTests })}\n</drift_analysis_rules>`;
+const _uiPlan = new PromptPlan()
+    .addPhase("ui_maintenance", "UI Test Drift Assessment", {
+    headerLevel: "##",
+    stepFormat: "hash",
+})
+    .step("UI_SYMBOL_PRESCAN", "Exported symbol pre-scan — find additional impacted tests via grep", (p) => buildUiCheckExportedSymbols(p.changedFrontendFiles))
+    .step("UI_ASSESS", "UI Action Decision Tree — assess each UI test against the diff and blueprints", () => buildUiActionDecisionTree())
+    .subStep("UI_ROUTE_EXISTENCE", "Route existence", () => buildUiCheckRouteExistence())
+    .subStep("UI_SELECTORS", "Selector validity", () => buildUiCheckSelectors())
+    .subStep("UI_PAGE_OBJECTS", "Page object/fixture existence", () => buildUiCheckPageObjects())
+    .subStep("UI_BEHAVIOR", "Component behavior changes", () => buildUiCheckBehavioralChanges())
+    .subStep("UI_ASSIGN_ACTION", "Assign action", () => buildUiCheckAssignAction())
+    .step("UI_CALL_TOOL", "Submit recommendations", (p) => buildUiDriftOutputChecklist(p.stateFile, p.tests))
+    .done();
+/**
+ * Build the drift analysis prompt.
+ * - apiTests: tests to assess for API endpoint drift (always included unless empty and ui is provided).
+ * - ui: when provided, appends a UI drift section for component/browser tests.
+ *   Omit when no frontend files changed or no UI tests exist.
+ */
+export function buildDriftAnalysisPrompt(stateFile, apiTests, ui) {
+    const parts = [];
+    // Include API drift when there are API tests, or when UI drift is not running
+    // (ensures skyramp_actions is always reachable even if apiTests is empty).
+    if (apiTests.length > 0 || !ui) {
+        parts.push(`<drift_analysis_rules>\n${_apiPlan.render({ stateFile, existingTests: apiTests })}\n</drift_analysis_rules>`);
+    }
+    if (ui) {
+        const signalNote = ui.blueprintCaptured
+            ? `blueprintCaptured=true — use \`browser_blueprint_diff\` for tests that navigate pages.`
+            : `blueprintCaptured=false — use source diff only. Read each test to determine what it exercises.`;
+        const contextHeader = `<ui_analysis_context>
+**UI Test Drift Analysis Context**
+
+**Signal:** ${signalNote}
+
+**Changed Frontend Files:**
+${ui.changedFrontendFiles.length > 0
+            ? ui.changedFrontendFiles.map(f => `- ${f}`).join("\n")
+            : "(none)"}
+
+**Tests to Assess:**
+${ui.tests.length > 0
+            ? ui.tests.map(t => `- ${t.testFile}`).join("\n")
+            : "(none)"}
+
+**Instructions:**
+For each test above, read it to determine its type, then apply the scope gate from the decision tree. Assign the appropriate action (DELETE, REGENERATE, UPDATE, VERIFY, IGNORE).
+</ui_analysis_context>
+
+`;
+        parts.push(contextHeader + `<ui_drift_analysis_rules>\n${_uiPlan.render({ stateFile, tests: ui.tests, changedFrontendFiles: ui.changedFrontendFiles, blueprintCaptured: ui.blueprintCaptured })}\n</ui_drift_analysis_rules>`);
+    }
+    return parts.join("\n\n");
 }

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

@@ -1,8 +1,9 @@
 /**
- * Modular section builders for the Drift Analysis prompt,
+ * Modular section builders for the API Drift Analysis prompt,
  * mirroring the recommendationSections.ts pattern.
  */
 import { AUTH_MIDDLEWARE_PATTERNS_STR } from "../../utils/workspaceAuth.js";
+import { buildApiAssignAction } from "./driftAnalysisShared.js";
 // TODO: Replace the open-ended diff-line categories below with a two-tier structure:
 // Tier 1 — mechanical patterns (specific token + file-path criteria, zero judgment needed).
 // Tier 2 — residual open-ended scan for anything observable not covered by tier 1.
@@ -177,24 +178,9 @@ Diff signals and actions:
 **Reachability for behavioral changes:** The service/interface scope gate still applies — if the test targets a completely different service or protocol, IGNORE. However, do NOT use the absence of a route or output layer file in the diff as grounds for IGNORE. Behavioral changes (new error branches, new validation, status-code changes) are observable from any test calling the same endpoint, even when the logic lives in an internal handler, middleware, or utility file rather than the route file itself.`;
 }
 export function buildCheckAssignAction() {
-    return `Based on the above checks, choose the action (IGNORE / VERIFY / UPDATE / REGENERATE / DELETE) and provide a 1-2 sentence rationale.
-
-**Every action requires a specific rationale — including IGNORE:**
-- UPDATE / REGENERATE / DELETE: quote the specific diff line that triggered it.
-- VERIFY: name the uncertain element (e.g. "model-only change, cannot confirm field is exposed without checking the output layer").
-- IGNORE: name the changed file(s) from the diff AND explain why they cannot reach this test's endpoint (e.g. "diff only touches \`auth/session-service.js\` — this test targets \`/api/v1/orders\` which has no session dependency"). You must reference at least one specific changed file from the diff. Generic "unrelated endpoint" or "service boundary" without naming the changed file is not sufficient.
-
-- If the Additive Fields check flagged a new field with output layer signal confirmed in the diff → action is UPDATE. If the Additive Fields check returned VERIFY (model-only signal, no output layer change) → action remains VERIFY.
+    return buildApiAssignAction(`- If the Additive Fields check flagged a new field with output layer signal confirmed in the diff → action is UPDATE. If the Additive Fields check returned VERIFY (model-only signal, no output layer change) → action remains VERIFY.
 - **Scope gate:** If the changed code is clearly not reachable through the service or base URL this test targets, assign IGNORE.
-- **When uncertain, use VERIFY not IGNORE:** If the diff touches a model or migration and this test's endpoint reads from that model, assign VERIFY — you cannot confirm from the diff alone whether the field is exposed.
-- **Pre-commit verification — confirm all three before finalizing UPDATE/REGENERATE/DELETE:**
-  1. You can quote a specific diff line this test's endpoint observes that triggered the action.
-  2. The changed code is reachable through this test's service and base URL.
-  3. For REGENERATE: every assertion in the file is invalid, not just some — if you can patch N paths, it is UPDATE.
-  If any check fails, downgrade to VERIFY or IGNORE.
-- **For user-written (external) tests** marked \`[external]\` in the test list:
-  - UPDATE is permitted — targeted edits only (fix renamed URL, add assertion for new field, add a new test case for a new scenario). Match the style of the existing file: use the same test framework, assertion helpers, and request pattern already present.
-  - REGENERATE and DELETE are **not permitted** — assign those actions in your recommendations but \`skyramp_actions\` will surface them as report-only findings for the developer to act on. Do NOT attempt to rewrite or delete a user-authored test file.`;
+- **When uncertain, use VERIFY not IGNORE:** If the diff touches a model or migration and this test's endpoint reads from that model, assign VERIFY — you cannot confirm from the diff alone whether the field is exposed.`);
 }
 export function buildCheckAdditiveFields() {
     return `Even if existing assertions still pass, new response fields on a covered endpoint need a new assertion. A field being optional or nullable does not make it IGNORE — it still needs to be covered.
@@ -225,7 +211,7 @@ export function buildDriftOutputChecklist(stateFile, existingTests) {
         ? `\nNo existing tests were found. Call \`skyramp_actions\` with \`recommendations: []\` and explain in your report why no maintenance was needed (e.g. "no existing tests cover the changed endpoints" or "PR adds a new endpoint with no prior coverage").\n`
         : "";
     const symbolDiscoveryStep = hasTests
-        ? `**Symbol import discovery (before assessing tests):** If the diff adds or modifies class, function, or type definitions, grep the repository for test files that import those symbol names. Add any matched test files not already in the list below to your assessment — these files may need updating even if their path doesn't match the changed resource name. Include all discovered files in the \`recommendations[]\` passed to \`skyramp_actions\` — do NOT edit them directly without going through \`skyramp_actions\` first.`
+        ? `**Symbol import discovery (before assessing tests):** If the diff adds or modifies class, function, or type definitions, grep the repository for test files that import those symbol names. Add any matched test files not already in the list below to your assessment — these files may need updating even if their path doesn't match the changed resource name. Include all discovered files in the \`recommendations[]\` passed to \`skyramp_actions\`.`
         : "";
     const existingTestSection = `**Existing tests (${existingTests?.length ?? 0} total) — assess ALL of the following:**
 ${testList}
@@ -257,7 +243,7 @@ Test: {testFile}
 Action: DELETE
 Rationale: DELETE because {quoted diff signal}; all covered endpoints removed
 \`\`\`
-Include ALL actions — IGNORE, VERIFY, UPDATE, REGENERATE, DELETE — in the \`recommendations[]\` passed to \`skyramp_actions\`. For \`[external]\` tests: \`skyramp_actions\` will apply UPDATE edits and surface REGENERATE/DELETE as report-only findings.
+Include ALL actions — IGNORE, VERIFY, UPDATE, REGENERATE, DELETE — in the \`recommendations[]\` passed to \`skyramp_actions\`.
 Be concise — one line per IGNORE/VERIFY entry.`;
     const sections = [symbolDiscoveryStep, existingTestSection, finalStep].filter(Boolean);
     return `<output_format>

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

@@ -0,0 +1,12 @@
+/** Shared drift prompt sections (assign-action, external test policy) for API and UI prompts. */
+export declare function buildSharedExternalTestPolicy(): string;
+/**
+ * Assign-action section for the API drift prompt.
+ * @param domainNotes  API-specific bullets (additive-fields guidance, scope-gate note).
+ */
+export declare function buildApiAssignAction(domainNotes: string): string;
+/**
+ * Assign-action section for the UI drift prompt.
+ * @param domainNotes  UI-specific bullets (component/widget matching notes).
+ */
+export declare function buildUiAssignAction(domainNotes: string): string;

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

@@ -0,0 +1,60 @@
+/** Shared drift prompt sections (assign-action, external test policy) for API and UI prompts. */
+export function buildSharedExternalTestPolicy() {
+    return `**For user-written (external) tests** marked \`[external]\` in the test list:
+- UPDATE is permitted — pass the exact file that needs editing as \`testFile\`. This can be the test file itself, a snapshot file, a page object, or a fixture. \`skyramp_actions\` will edit that file using \`updateInstructions\`; application source files are automatically rejected.
+- REGENERATE and DELETE: assign these actions when the evidence clearly warrants them (page gone → DELETE, component structure fundamentally changed → REGENERATE). \`skyramp_actions\` handles execution restrictions at apply time — assign the action that the evidence supports. Leave user-authored test files unchanged; edits go only through \`skyramp_actions\` with explicit \`updateInstructions\`. VERIFY means "uncertain, need more context" — assign DELETE or REGENERATE when you have confirmed the failure, and VERIFY only when you genuinely cannot determine impact without more information.`;
+}
+/** Shared boilerplate: VERIFY rule, pre-commit structure, and external policy. */
+function buildAssignActionCore(opts) {
+    return `Based on the above checks, choose the action (IGNORE / VERIFY / UPDATE / REGENERATE / DELETE) and provide a 1-2 sentence rationale.
+
+**Every action requires a specific rationale — including IGNORE:**
+- UPDATE / REGENERATE / DELETE: ${opts.triggerEvidence}.
+- VERIFY: name the uncertain element (e.g. ${opts.verifyExample}).
+- IGNORE: ${opts.ignoreGuidance}.
+
+${opts.domainNotes}
+
+**When uncertain, use VERIFY not IGNORE:** If the diff touches code this test could exercise but you cannot confirm impact without reading more context, assign VERIFY — do not default to IGNORE.
+
+**Pre-commit verification — confirm before finalizing UPDATE/REGENERATE/DELETE:**
+1. You can quote a specific diff line${opts.blueprintSuffix} this test observes that triggered the action.
+2. ${opts.reachabilityCheck}
+3. ${opts.regenerateCheck}
+4. ${opts.deleteCheck}
+If any check fails, downgrade to VERIFY or IGNORE.
+
+${buildSharedExternalTestPolicy()}`;
+}
+/**
+ * Assign-action section for the API drift prompt.
+ * @param domainNotes  API-specific bullets (additive-fields guidance, scope-gate note).
+ */
+export function buildApiAssignAction(domainNotes) {
+    return buildAssignActionCore({
+        triggerEvidence: "quote the specific diff line that triggered it",
+        ignoreGuidance: `name the changed file(s) from the diff AND explain why they cannot reach this test's endpoint (e.g. "diff only touches \`auth/session-service.js\` — this test targets \`/api/v1/orders\` which has no session dependency"). You must reference at least one specific changed file. Generic "unrelated endpoint" or "service boundary" without naming the changed file is not sufficient`,
+        verifyExample: `"model-only change, cannot confirm field is exposed without checking the output layer"`,
+        blueprintSuffix: "",
+        reachabilityCheck: "The changed code is reachable through this test's service and base URL.",
+        regenerateCheck: "For REGENERATE: every assertion in the file is invalid, not just some — if you can patch N paths, it is UPDATE.",
+        deleteCheck: "For DELETE: all covered endpoints no longer exist.",
+        domainNotes,
+    });
+}
+/**
+ * Assign-action section for the UI drift prompt.
+ * @param domainNotes  UI-specific bullets (component/widget matching notes).
+ */
+export function buildUiAssignAction(domainNotes) {
+    return buildAssignActionCore({
+        triggerEvidence: "quote the specific diff line and/or blueprint element that triggered it",
+        ignoreGuidance: `name the specific route or component and why the diff cannot reach it (e.g. "diff only touches \`/api/v1/users\` — this test targets \`/dashboard\`")`,
+        verifyExample: `"component is imported but not directly rendered — cannot confirm impact without reading the parent"`,
+        blueprintSuffix: " or blueprint element",
+        reachabilityCheck: "The changed code is reachable through this test's routes (browser tests) or a render/mount call in the test that references a changed component (component/widget tests).",
+        regenerateCheck: "For REGENERATE: the interaction model changed fundamentally — the test's action sequence has no migration path. If selectors changed but the flow (navigate → interact → assert) can still be expressed with targeted edits, it is UPDATE regardless of how many selectors changed.",
+        deleteCheck: "For DELETE: the route is completely gone (browser tests) or the rendered component was deleted (component/widget tests).",
+        domainNotes,
+    });
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Build the UI Action Decision Tree section.
+ * This is the main entry point for UI drift analysis.
+ */
+export declare function buildUiActionDecisionTree(): string;
+/**
+ * Pre-scan step: agent greps changed files' exported symbols across the test
+ * directory to catch tests that server-side discovery missed — aliased imports,
+ * indirect renders, or any test the blueprint diff doesn't directly reference.
+ */
+export declare function buildUiCheckExportedSymbols(changedFrontendFiles?: string[]): string;
+/**
+ * Check if routes targeted by the UI test still exist.
+ */
+export declare function buildUiCheckRouteExistence(): string;
+/**
+ * Check if selectors used by the UI test still exist in the blueprints.
+ */
+export declare function buildUiCheckSelectors(): string;
+/**
+ * Check if page objects/fixtures referenced by the test still exist.
+ */
+export declare function buildUiCheckPageObjects(): string;
+/**
+ * Check for component behavior changes that affect assertions.
+ */
+export declare function buildUiCheckBehavioralChanges(): string;
+/**
+ * Assign the final UI drift action.
+ */
+export declare function buildUiCheckAssignAction(): string;
+/**
+ * Build the UI drift output checklist.
+ */
+export declare function buildUiDriftOutputChecklist(stateFile?: string, tests?: Array<{
+    testFile: string;
+}>): string;

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

@@ -0,0 +1,226 @@
+/**
+ * UI Drift Analysis prompt sections for Component 2.
+ *
+ * Mirrors the driftAnalysisSections.ts pattern but for UI-specific drift detection.
+ * These sections are included whenever `uiContext.changedFrontendFiles` is non-empty —
+ * both browser tests (Playwright/Cypress/Selenium) and component/widget tests
+ * (RTL/Flutter widget/vue-test-utils/angular-testbed) go through the same gate.
+ * Component tests always use source-only analysis regardless of blueprintCaptured.
+ */
+import { buildUiAssignAction } from "./driftAnalysisShared.js";
+/**
+ * Build the UI Action Decision Tree section.
+ * This is the main entry point for UI drift analysis.
+ */
+export function buildUiActionDecisionTree() {
+    return `<ui_decision_rules>
+For each UI test listed in the \`<ui_analysis_context>\` above, assess whether the test is still valid given the diff (and blueprint diff when blueprints were captured). The diff may have changed:
+- Element selectors (CSS class changes, component restructuring)
+- Page structure (new containers, removed sections)
+- Route paths (URL changes)
+- Component behavior (state changes, visibility conditions)
+
+**Scope gate:** Read each test file to determine its type, then apply the correct gate:
+- **Browser test** (has \`page.goto()\`, \`cy.visit()\`, \`driver.get()\`): check that the test navigates to a page the changed frontend file serves. Infer from the changed file's directory path (e.g. \`modules/bookings/\` → bookings page) or explicit route-path diff signals.
+- **Component/widget test** (has \`render(<…>)\`, \`mount()\`, \`shallowMount()\`): check if it directly renders/mounts a changed component. If none of the rendered components match a changed file, the test is unaffected.
+If neither condition applies, assign **IGNORE** and skip remaining checks.
+
+
+**Severity order (highest first): DELETE > REGENERATE > UPDATE > VERIFY > IGNORE**
+
+**Pre-scan the diff for UI-relevant changes:**
+- Component file changes: \`+ import { NewComponent }\`, \`- <OldComponent />\` / \`+ <NewComponent />\`
+- CSS/Tailwind changes: \`+ className="..."\`, \`+ tw="..."\`, \`+ styles.\`
+- Route changes: \`- path: "/old"\` / \`+ path: "/new"\`
+- Selector changes: \`+ data-testid="..."\`, \`- data-testid="..."\`, \`+ aria-label="..."\`
+- State/visibility changes: \`+ isOpen\`, \`+ isVisible\`, \`+ showModal\`
+
+Build a detection list first: for each matched diff line, write one line: \`{pattern type} — "{diff line}" — affects {route/component}\`.
+
+**Action definitions:**
+- **DELETE**: The test targets a page/route that no longer exists, or all selectors the test uses have been removed and there's no migration path.
+- **REGENERATE**: The interaction model changed so fundamentally that the test flow itself is broken — not just selector values, but the sequence of actions (e.g. a form replaced by a modal, buttons replaced by a dropdown, a multi-step flow collapsed into one). There is no rename mapping; re-recording from scratch is the only viable approach.
+- **UPDATE**: Specific selectors need updating, or assertions need adjustment. The test structure is salvageable with targeted edits.
+- **VERIFY**: The test may be impacted but you cannot confirm breakage without reading more context (e.g. selectors are hidden in a page object file you have not read, or the component is imported indirectly).
+- **IGNORE**: The changed code cannot reach this test's routes or rendered components — the test covers unchanged functionality. If you cannot point to a diff line that affects this test's routes, selectors, or rendered components, the action is IGNORE or VERIFY, not UPDATE.
+
+**Rules:**
+- DELETE when all routes the test covers were removed or all critical selectors are gone.
+- REGENERATE when the interaction model changed fundamentally — the test's sequence of actions is broken with no migration path (e.g. a click-to-update button replaced by an auto-updating stepper; a remove button moved into a dropdown). The number of broken selectors alone does not determine REGENERATE; what matters is whether the flow can still be expressed with targeted edits.
+- UPDATE when specific selectors changed (renamed classes, moved data-testid) but the test flow remains valid.
+- VERIFY when a page object or indirect import hides the affected selectors — read the imported file before escalating to UPDATE.
+- IGNORE when the diff touches unrelated frontend code (different routes, different components).
+
+**Additional rule for component/widget tests** ([rtl], [flutter-widget], [vue-test-utils], [angular-testbed]):
+- Rule #7: Component deleted — source file removed with no re-export → **DELETE** (report-only for external tests). These tests have no navigation; the rendered component is their only target.
+- Skip the route-existence check (step 1.1) for component/widget tests — they have no \`page.goto()\` or equivalent navigation calls.
+- Primary matching signal: read the test to check if it directly renders a changed component — if so, it is impacted.
+</ui_decision_rules>`;
+}
+/**
+ * Pre-scan step: agent greps changed files' exported symbols across the test
+ * directory to catch tests that server-side discovery missed — aliased imports,
+ * indirect renders, or any test the blueprint diff doesn't directly reference.
+ */
+export function buildUiCheckExportedSymbols(changedFrontendFiles) {
+    const files = (changedFrontendFiles ?? []).join(", ") || "the changed frontend files";
+    return `The server pre-discovered the tests listed above using exported symbols and UI signals (testids, aria-labels, i18n keys, CSS classes) from the diff. Before assessing, do a quick complementary grep to catch any tests the server may have missed — aliased imports, indirect renders, or tests using symbols not present in the diff:
+
+1. For each changed frontend file (${files}):
+   a. Read the file and extract exported symbols — component names, function names, hook names, class names.
+   b. Grep the test directory for each symbol name (case-insensitive).
+   c. For any matching test file not already in the \`<ui_analysis_context>\` list — read it and apply the decision tree.
+
+This catches tests that import a changed symbol under an alias, exercise a shared hook, or render the changed component indirectly via a parent.`;
+}
+/**
+ * Check if routes targeted by the UI test still exist.
+ */
+export function buildUiCheckRouteExistence() {
+    return `Does the route/page this UI test navigates to still exist?
+
+**Skip this check for component/widget tests** ([rtl], [flutter-widget], [vue-test-utils], [angular-testbed]) — they render components directly with no navigation calls. Proceed to selector checks.
+
+Diff signals to look for (browser tests only):
+- Route removed: \`- path: "/old-path"\`, \`- @app.route("/old-path")\`, \`- router.get("/old-path")\`
+- Route renamed: paired \`-\` and \`+\` on route definitions with different paths
+- Redirect added: \`+ redirect: "/old-path" → "/new-path"\`, \`+ res.redirect(301, "/new-path")\`
+
+Actions:
+- ALL routes the test uses were removed → **DELETE**
+- SOME routes renamed with no redirect → **UPDATE** (update navigation calls to new URLs)
+- Routes renamed with redirect kept → **UPDATE** (verify redirect behavior, test should still work)
+- Routes unchanged → proceed to selector checks`;
+}
+/**
+ * Check if selectors used by the UI test still exist in the blueprints.
+ */
+export function buildUiCheckSelectors() {
+    return `Do the selectors/locators this UI test uses still match the current UI?
+
+Read the test (and any imported page object/fixture files) to extract the selectors/locators it uses — \`getByTestId(...)\`, \`locator(...)\`, \`.find('...')\`, \`data-testid\`, \`aria-label\`, CSS class names.
+
+Diff signals to look for:
+- CSS class changes: \`- className="old-class"\` / \`+ className="new-class"\`
+- Tailwind changes: \`- tw="p-4"\` / \`+ tw="p-6"\`
+- Test ID changes: \`- data-testid="old-id"\` / \`+ data-testid="new-id"\`
+- ARIA changes: \`- aria-label="Old"\` / \`+ aria-label="New"\`
+- Component restructuring: \`+ <NewWrapper>\` around existing content, \`- <OldWrapper>\`
+
+**When blueprints are available** (\`blueprintCaptured=true\`): compare extracted selectors against \`browser_blueprint_diff\` for the affected page — elements absent from the new blueprint signal breakage.
+
+**When blueprints are not available** (\`blueprintCaptured=false\`): use diff signals only. If a selector the test uses matches a value renamed or removed in the diff, assign UPDATE. If you cannot confirm breakage from the diff alone (e.g. selectors live in a page object you have not read), assign VERIFY rather than guessing.
+
+Actions:
+- Selectors confirmed unchanged (diff or blueprint) → **IGNORE** (no drift)
+- Selectors renamed (class, testid, aria-label changed) → **UPDATE** (patch selector values)
+- Selectors removed with no confirmed replacement → **UPDATE** (find replacement; use blueprint if available, diff otherwise)
+- Major restructuring (most selectors gone) → **REGENERATE** (page structure fundamentally changed)
+- All selectors gone, no replacement elements → **DELETE** (page no longer testable)
+- Cannot confirm without reading page object or additional files → **VERIFY**`;
+}
+/**
+ * Check if page objects/fixtures referenced by the test still exist.
+ */
+export function buildUiCheckPageObjects() {
+    return `Do the page objects or fixture files imported by this UI test still exist, and are their underlying selectors still valid?
+
+**Always follow imports to find page objects — regardless of whether blueprints were captured.**
+Page objects can live anywhere in the repo (not just \`page-objects/\` or \`fixtures/\`). Do not assume a fixed directory. The only reliable way to find them is to follow the spec file's \`import\` statements.
+
+**Protocol for every browser test (Playwright/Cypress/Selenium):**
+1. Read the spec file and collect all local \`import\` statements (skip \`@playwright/test\`, \`vitest\`, etc. — only follow relative or repo-local paths).
+2. For each imported file, read it and extract the selectors it encapsulates — \`locator()\`, \`getByTestId()\`, \`getByRole()\`, \`getByLabel()\`, \`data-test-*\`, \`aria-label\`, CSS class strings.
+3. Compare those selectors against the diff: if a selector value the page object uses was renamed or removed in a \`-\` diff line → the page object needs **UPDATE**.
+4. **Update the page object file, not the spec file** — the page object is the selector source of truth. In the recommendation: set \`testFile\` to the **spec file** (so it shows correctly in the maintenance report) and set \`pomFile\` to the **page object path** (so \`skyramp_actions\` edits the right file). If the edit is rejected at action time, the agent or developer can address it separately.
+5. If the imported file is missing or unreadable → **VERIFY** (cannot confirm without the file).
+
+A clean spec with no raw selector calls is not a reason to assign VERIFY — it is expected when page objects are used. Assign the action based on the POM's selectors.
+
+Diff signals to look for in the spec's imports:
+- Import deleted: \`- import { OldPage } from './pages/OldPage'\` → page object removed
+- Import path changed: paired \`-\`/\`+\` on the same import → page object moved or renamed
+- New import added: \`+ import { NewFixture } from '../fixtures/new'\` → new dependency
+
+Actions:
+- Page object's selectors match a renamed/removed diff value → **UPDATE** (patch the page object)
+- Page object import path changed in the diff → **UPDATE** (fix the import in the spec)
+- Page object file deleted, no replacement found → **UPDATE** (inline selectors or find alternative)
+- Selectors in page object unchanged and diff does not affect them → **IGNORE**
+- **All POM selectors are gone with no migration path in the diff** (the component's interaction model changed fundamentally — no ` + ` lines showing replacement selectors) → **REGENERATE**. Do not stay at VERIFY after reading the POM and confirming this — escalate once you have confirmed the failure.`;
+}
+/**
+ * Check for component behavior changes that affect assertions.
+ */
+export function buildUiCheckBehavioralChanges() {
+    return `Have component behaviors changed in ways that would break test assertions?
+
+Diff signals to look for:
+- State changes: \`+ isLoading\`, \`+ isOpen\`, \`+ showModal\`, \`+ disabled\`
+- Visibility conditions: \`+ if (condition) return null\`, \`+ {condition && <Component />}\`
+- Interaction changes: \`+ onClick={() => setOpen(true)}\`, \`+ require('auth')\`
+- Async behavior: \`+ setTimeout\`, \`+ debounce\`, \`+ async/await\` in handlers
+
+Actions:
+- New loading states → **UPDATE** (add waitFor or assertion for loading state)
+- New conditional rendering → **UPDATE** (update assertions to match new conditions)
+- Auth behavior changed → **UPDATE** (adjust login flow in test)
+- Async delays added → **UPDATE** (add appropriate waits/timeouts)`;
+}
+/**
+ * Assign the final UI drift action.
+ */
+export function buildUiCheckAssignAction() {
+    return buildUiAssignAction(`**Component/widget test matching (source-only):**
+- Read the test to check if it directly renders a changed component — if so, it is impacted.
+- If the test only imports but does not directly render the component, assign VERIFY (component-import signal — cannot confirm impact without reading the parent).
+- If neither signal fires, assign **IGNORE**.`);
+}
+/**
+ * Build the UI drift output checklist.
+ */
+export function buildUiDriftOutputChecklist(stateFile, tests) {
+    const finalStep = `Call \`skyramp_actions\` with \`stateFile: "${stateFile ?? "<stateFile>"}"\` and a \`recommendations\` entry for every test assessed.`;
+    const hasTests = (tests?.length ?? 0) > 0;
+    const testList = hasTests
+        ? tests.map(t => `- ${t.testFile}`).join("\n")
+        : "- (none)";
+    const noTestsNote = !hasTests
+        ? `\nNo existing tests were found. Call \`skyramp_actions\` with \`recommendations: []\`.\n`
+        : "";
+    const existingTestSection = `**Tests (${tests?.length ?? 0} total) — assess ALL of the following:**
+${testList}
+${noTestsNote}
+
+**Execution policy:**
+- Skyramp-generated tests: UPDATE/REGENERATE/DELETE applied automatically by \`skyramp_actions\`. Run via \`skyramp_execute_test\`.
+- External tests (Playwright, Cypress, RTL, etc.): \`skyramp_actions\` applies UPDATE edits to \`testFile\` — which can be the test itself, a snapshot file, a page object, or a fixture. Application source files are automatically rejected. After a successful UPDATE, call \`skyramp_execute_test\` to confirm the patched test passes (the test environment is already running). Record the result as the after-state in the report. For DELETE and REGENERATE on external tests, see the execution policy in the decision rules above.
+
+For each UI test above, output one structured entry in \`recommendations[]\`:
+- **IGNORE**: \`{testFile} — IGNORE: {specific reason the diff cannot reach this test — name the route or component that differs}\`
+- **VERIFY**: \`{testFile} — VERIFY: {uncertain element, e.g. "selectors hidden in page object not yet read"}\` — include in \`recommendations[]\` for developer review
+\`\`\`
+Test: {testFile}
+Action: UPDATE
+Rationale: UPDATE because {quoted diff line}; {selector/route/behavior change}
+UpdateInstructions: {what must change — specific selectors to update, routes to patch, assertions to add}
+\`\`\`
+\`\`\`
+Test: {testFile}
+Action: REGENERATE
+Rationale: REGENERATE because {quoted diff line}; page structure fundamentally changed
+\`\`\`
+\`\`\`
+Test: {testFile}
+Action: DELETE
+Rationale: DELETE because {quoted diff line}; all routes removed or no valid selectors remain
+\`\`\`
+
+**Every assessed test must appear in \`recommendations[]\`** — including IGNORE and VERIFY. IGNORE entries are omitted from \`testMaintenance[]\` in the report (a clean test is not a maintenance action). UPDATE, REGENERATE, DELETE, and VERIFY entries must appear in \`testMaintenance[]\`. A missing entry means the test was not assessed.`;
+    const sections = [existingTestSection, finalStep];
+    return `<ui_output_format>
+Complete ALL of the following:
+
+${sections.join("\n\n")}
+</ui_output_format>`;
+}

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

@@ -154,6 +154,69 @@ function prioritizeAttackSurfaceBundles(items) {
     }
     return reordered;
 }
+/**
+ * Select `count` items from a rank-ordered list, distributing GENERATE slots
+ * EVENLY across the test types present, with spillover.
+ *
+ * Policy (kept identical to the multi-repo prose in testbot-prompts.ts's
+ * "Cross-repo test generation" block — change both together):
+ *  - Protected items first: CRITICAL-priority and attack-surface security_boundary
+ *    scenarios always take a slot before round-robin (they must stay in GENERATE).
+ *  - Bucket the rest by inferred test type (contract vs integration — the same
+ *    inference used when rendering: `testType ?? (steps===1 ? contract : integration)`).
+ *  - Round-robin one item per non-empty bucket per round, in the buckets' order of
+ *    first appearance in the rank-ordered list (so the highest-ranked type wins
+ *    round 1), preserving rank order within each bucket.
+ *  - Spillover: an exhausted bucket is skipped on later rounds, so its freed slots
+ *    go to the next type's next-highest item.
+ *
+ * Degenerate cases match the previous pure rank-order slice exactly: a single type
+ * present, or `count >= items.length`, returns the same items in the same order —
+ * so backend-only / single-type runs are unchanged (no regression).
+ */
+function roundRobinByType(rankOrdered, count) {
+    if (count <= 0)
+        return [];
+    // Everything fits → no need to bucket; identical to the old slice.
+    if (count >= rankOrdered.length)
+        return rankOrdered.slice(0, count);
+    const inferType = (s) => s.testType ?? (s.steps.length === 1 ? "contract" : "integration");
+    // Protected items occupy GENERATE slots first, in rank order.
+    const selected = [];
+    const remaining = [];
+    for (const item of rankOrdered) {
+        if (selected.length < count &&
+            (item.priority === "CRITICAL" || isAttackSurfaceSecurityBoundary(item.scenario))) {
+            selected.push(item);
+        }
+        else {
+            remaining.push(item);
+        }
+    }
+    // Bucket the remainder by inferred type, preserving rank order and first-appearance
+    // bucket order.
+    const order = [];
+    const buckets = new Map();
+    for (const item of remaining) {
+        const t = inferType(item.scenario);
+        if (!buckets.has(t)) {
+            buckets.set(t, []);
+            order.push(t);
+        }
+        buckets.get(t).push(item);
+    }
+    // Round-robin one per non-empty bucket per round until full.
+    while (selected.length < count && order.some((t) => buckets.get(t).length > 0)) {
+        for (const t of order) {
+            if (selected.length >= count)
+                break;
+            const bucket = buckets.get(t);
+            if (bucket.length > 0)
+                selected.push(bucket.shift());
+        }
+    }
+    return selected;
+}
 export function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, authSchemeSnippet, authTypeValue, seed, endpointCount, isUIOnlyPR, hasFrontendChanges = false, hasTraces = false, externalCoverage = new Set(), relevantExternalTestPaths = []) {
     const frontendUrl = "<frontend_url>";
     // Slot allocation:
@@ -183,8 +246,19 @@ export function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValu
         })
         : scored;
     const slotOrderedItems = prioritizeAttackSurfaceBundles(scoredAfterExternalDedup);
-    const generateItems = slotOrderedItems.slice(0, Math.min(backendGenerateCount, slotOrderedItems.length));
-    const rawAdditionalItems = slotOrderedItems.slice(backendGenerateCount, topN);
+    // Distribute the backend GENERATE slots evenly across the test types present
+    // (contract vs integration) with spillover, instead of a pure top-N rank slice —
+    // so a backend change isn't starved of (say) integration coverage just because
+    // contract scenarios out-ranked it. See roundRobinByType.
+    const generateItems = roundRobinByType(slotOrderedItems, Math.min(backendGenerateCount, slotOrderedItems.length));
+    // ADDITIONAL = everything not chosen for GENERATE, in original rank order, capped
+    // at the remaining budget. Computed by set-difference (not a positional slice)
+    // because round-robin may pick items that aren't the first backendGenerateCount by
+    // rank — a positional slice would double-list a generated item or drop one.
+    const generateSet = new Set(generateItems);
+    const rawAdditionalItems = slotOrderedItems
+        .filter((it) => !generateSet.has(it))
+        .slice(0, Math.max(0, topN - backendGenerateCount));
     // Filter additional items whose primary resource + test type already appear in GENERATE
     const generatedCoverage = new Set(generateItems.map((item) => scenarioCoverageKey(item.scenario)));
     const additionalItems = rawAdditionalItems.filter((item) => !generatedCoverage.has(scenarioCoverageKey(item.scenario)));

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

@@ -11,7 +11,12 @@ const FLUTTER_DART_EXT = /\.dart$/i;
 const LIKELY_FRONTEND_EXT = /\.(tsx|jsx)$/i;
 // Ambiguous extensions need directory context to distinguish frontend from backend.
 const AMBIGUOUS_FRONTEND_PATTERN = /\.(tsx?|jsx?|css|scss|less|html?|erb|jsp|asp|jinja2?|twig)$/i;
-const API_DIR_PATTERN = /\/(api|routes?|controllers?|routers?|handlers?|endpoints?|server)\//;
+// /api/ always signals backend — even .tsx files (e.g. Next.js pages/api/*.tsx handlers).
+const STRICT_API_DIR_PATTERN = /\/(api)\//i;
+// Framework route dirs that contain React page components in modern full-stack apps
+// (Medusa Admin, Remix, React Router v6). These only block non-.tsx/.jsx files —
+// a .tsx file in routes/ is a page component, not a route handler.
+const FRAMEWORK_ROUTE_DIR_PATTERN = /\/(routes?|controllers?|routers?|handlers?|endpoints?|server)\//i;
 const FRONTEND_DIR_PATTERN = /(^|\/)(components?|pages?|views?|layouts?|app|src\/app|frontend|client|public|styles?|templates?)\//i;
 /**
  * Returns true if the repository root's `pubspec.yaml` declares a Flutter
@@ -120,7 +125,12 @@ export function isFrontendFile(filePath, { hasFlutterSdkDep = false } = {}) {
         return true;
     if (hasFlutterSdkDep && FLUTTER_DART_EXT.test(filePath))
         return true;
-    if (API_DIR_PATTERN.test(filePath))
+    // /api/ always means backend regardless of extension (Next.js API routes use .tsx).
+    if (STRICT_API_DIR_PATTERN.test(filePath))
+        return false;
+    // routes/, controllers/ etc. block .ts/.js but not .tsx/.jsx — Medusa Admin and
+    // React Router place page components under routes/, not API handlers.
+    if (!LIKELY_FRONTEND_EXT.test(filePath) && FRAMEWORK_ROUTE_DIR_PATTERN.test(filePath))
         return false;
     if (LIKELY_FRONTEND_EXT.test(filePath))
         return true;