@skyramp/mcp 0.3.0-rc.1 → 0.3.0

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

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { MAX_TESTS_TO_GENERATE, MAX_RECOMMENDATIONS, MAX_CRITICAL_TESTS, PATH_PARAM_UUID_GUIDANCE, AUTH_CONFLICT_ERROR_MSG, } from "../test-recommendation/recommendationSections.js";
+import { TASK_ANALYZE_MAINTAIN, TASK_GENERATE, TASK_SUBMIT, taskRef } from "../test-recommendation/recommendationShared.js";
 import { getTraceRecordingPromptText } from "../../playwright/traceRecordingPrompt.js";
 import { isContractConsumerModeEnabled } from "../../utils/featureFlags.js";
 import { resolveServiceDetailsRef } from "../../utils/utils.js";
@@ -130,7 +131,7 @@ ${hasRelatedRepos ? `
 
    b. Write \`updateInstructions\` for each UPDATE or REGENERATE test before calling \`skyramp_actions\` — articulating the change first prevents file content from overriding diff-based reasoning.
 
-   c. Call \`skyramp_execute_test\` with \`phase: "before"\` and \`stateFile\` for every test whose action is UPDATE, REGENERATE, or DELETE. Run them sequentially, not in parallel. This captures the pre-edit baseline — do not skip even if you expect the test to fail.
+   c. Call \`skyramp_execute_test\` with \`phase: "before"\` and \`stateFile\` for every UPDATE/REGENERATE/DELETE test. Exclude tests marked \`[external]\`. Run them sequentially, not in parallel. This captures the pre-edit baseline — do not skip even if you expect the test to fail.
 
    d. Call \`skyramp_actions\` with \`stateFile\` (from \`skyramp_analyze_changes\` output) and apply the edits it returns.
 
@@ -355,6 +356,7 @@ ${task1Section}
 ${userPrompt ? "Generate only the tests that the user requested from the Additional Recommendations. The rules below still apply." : "Drift-based maintenance (Task 1) is complete. This step only processes the GENERATE list. Exception: if a GENERATE item targets a resource with an existing `[skyramp]` contract test, UPDATE that test file (see covered-resource handling below) — a new test case added to an existing file counts toward the budget and is reported in `newTestsCreated`."}
 
 - **MANDATORY — use the pre-ranked GENERATE list as-is**: The Execution Plan's GENERATE section governs ADD actions. You MUST generate exactly those scenarios in the exact order listed. Do NOT substitute, rename, or replace a GENERATE item. If parameter grounding uncovers a distinct bug-catching scenario not already in the GENERATE or ADDITIONAL list, generate it after all planned GENERATE items are complete and report it in \`newTestsCreated\` — this is an additional test driven by source-code analysis and does not count against the GENERATE budget.${hasRelatedRepos ? `\n  - **Multi-repo exception:** this run has related repositories, so the per-repo GENERATE lists are NOT final — they are candidates re-selected by the cross-repo round-robin described in Task 1's "Cross-repo test generation". Follow that pooled, type-distributed selection instead of any single repo's GENERATE list. (In single-repo runs the GENERATE list IS final — generate it exactly as-is.)` : ""}
+- **Do not fabricate tests outside the GENERATE list.** New test files cover NEW observable surface only — a new endpoint, or a newly-integrated component/route not already covered by an existing test. Changes that only modify, delete, or add fields to an EXISTING covered endpoint or component are maintenance: handle them in ${taskRef(TASK_ANALYZE_MAINTAIN)} by UPDATE/DELETE of the existing test, never by creating a new spec. If the GENERATE list is empty (deletion-only, cosmetic, or modification-of-existing PRs with no new surface), create zero new tests and proceed to ${taskRef(TASK_SUBMIT)} — do not invent a new spec to have something to report.
 - Scenario JSON files are always new files — always generate them for new methods. Every generated scenario JSON must have a corresponding new integration test generated from it via \`skyramp_integration_test_generation\`.
 - Covered-resource handling (aligns with Execution Plan Step 0): When a GENERATE item targets a resource that already has an existing test file covering the same endpoint:
   - If the existing test source is \`[external]\`, skip the resource entirely — the external test already provides coverage. Do NOT UPDATE, REGENERATE, or DELETE external tests.
@@ -362,9 +364,9 @@ ${userPrompt ? "Generate only the tests that the user requested from the Additio
     - Contract tests: UPDATE the existing Skyramp test file (add the new method's test cases). A new test case is a new test even if the file already exists — report in \`newTestsCreated\` and count toward the budget.
     - Integration/scenario tests: Always generate as a new file via the scenario pipeline (\`skyramp_batch_scenario_test_generation\` → \`skyramp_integration_test_generation\`), even if an existing integration test covers the same resource. A new multi-step scenario (e.g. create → PATCH → verify recalculation) is a distinct test file. Report in \`newTestsCreated\` and count toward the budget.
     - UI tests: Always generate as a new file. Report in \`newTestsCreated\`.
-  Keep advancing until you have created exactly ${maxGenerate} new test files OR exhausted all candidates.
+  Keep advancing until you have created exactly as many new test files as your committed Budget Plan's generate count (at most ${maxGenerate}) OR exhausted all candidates. If your Budget Plan is 0 total, ${taskRef(TASK_GENERATE)} produces zero tests.
 - Example: If enrichment reveals that sending \`discount_value\` without \`discount_type\` silently orphans the value (a concrete bug), complete all planned GENERATE items first, then generate this discovered scenario as an extra test and report it in \`newTestsCreated\`.
-- Total generated: Follow the "Budget: N generate" line in the Execution Plan. Process every GENERATE-tagged item in order. Backfill from ADDITIONAL candidates (highest-ranked first) until \`newTestsCreated\` reaches ${maxGenerate} or all candidates are exhausted.
+- Total generated: your committed Budget Plan's generate count (from the Execution Plan's Scope Assessment, at most ${maxGenerate}) is the single source of truth for how many tests to create. Process every GENERATE-tagged item in order, then backfill from ADDITIONAL candidates (highest-ranked first) until \`newTestsCreated\` reaches that generate count or all candidates are exhausted. If your Budget Plan is 0 total (the Execution Plan's zero-classified default or cosmetic-only override applies), skip generation and backfilling entirely and proceed to ${taskRef(TASK_SUBMIT)}'s zero-test report path.
 - **UI test priority**: If the PR scope assessment shows any UI/E2E budget OR \`uiContext.changedFrontendFiles\` is non-empty (the deterministic server signal — populated for all supported frontend file types including \`.tsx\`/\`.jsx\`/\`.vue\`/\`.svelte\`/\`.dart\`), you MUST attempt to generate at least one UI test. Use \`browser_navigate\` to the app's base URL — if the app responds, record a trace and generate the test.
   **Flutter web apps:** Skyramp's Playwright tools automatically enable Flutter's accessibility semantics tree on every \`browser_navigate\` call — you do NOT need to manually click \`flt-semantics-placeholder\` or add any activation step to the trace. Do NOT log an \`issuesFound\` entry about Flutter canvas rendering or accessibility activation — this is handled transparently. **Do NOT skip test generation or abstain from recording based on what you see in the Flutter source code** (e.g. \`SemanticsBinding.ensureSemantics()\` commented out, \`IS_TESTING\` flag absent, or similar) — Skyramp enables accessibility from the browser side regardless of the app's Dart code. Proceed with \`browser_navigate\` and test recording as normal. **Start at the app's root URL** (e.g. \`{baseUrl}/\`) — do NOT \`browser_navigate\` straight to a deep sub-route (e.g. \`/authors\`, \`/orders/13\`). Flutter \`go_router\` SPAs route from the root: deep-linking on a cold page load often fails to render the expected screen (the route's widgets never mount, so the trace captures the wrong page). Load the root, let the app's own routing/auth-redirect render, then reach target screens by interaction. **After the initial login, navigate using in-app controls only** (tab buttons, links, back buttons) — do NOT call \`browser_navigate\` to a different URL after login. Flutter web apps are SPAs: a \`browser_navigate\` to a new URL after login triggers a full page reload which clears the auth session, causing redundant re-login cycles in the generated test. Use button clicks to reach target screens instead.
   **Skip only if one of these conditions is met:**
@@ -546,7 +548,7 @@ Do NOT use \`page.waitForTimeout()\` with fixed delays. Do NOT retry more than o
 4. **Wait**: Do NOT proceed to test execution until steps 1–3 are complete and the verification checklist in the \`skyramp_enhance_assertions\` tool result has been validated for EVERY generated test file.
 Do not make any changes other than the assertion enhancements described above. For example: do not modify auth headers, cookies, tokens, env vars, or imports that the generation tool already set correctly — those are correct by construction and changing them breaks auth or execution.
 
-**Final execution (mandatory):** Do NOT call \`skyramp_execute_test\` until ALL maintenance edits AND ALL new test generation/enhancement are complete. Run these calls sequentially, not in parallel.
+**Final execution (mandatory):** Do NOT call \`skyramp_execute_test\` until ALL maintenance edits AND ALL new test generation/enhancement are complete. Run these calls sequentially, not in parallel. Exclude tests marked \`[external]\`.
 - Only report test results for files you actually ran.
 **Auth**: If \`skyramp_analyze_changes\` reports an auth token or \`SKYRAMP_TEST_TOKEN\` is set, pass it in **every** \`skyramp_execute_test\` call from the first attempt — do NOT wait for a 401/403 to discover auth is needed.
 
@@ -568,7 +570,7 @@ In these cases:
 - \`businessCaseAnalysis\` must be a one-sentence summary of what the PR actually does (do NOT leave it blank)
 - \`additionalRecommendations\` must be \`[]\` — do NOT recommend tests for a no-surface PR
 
-Otherwise: in \`newTestsCreated\`, you must have exactly ${maxGenerate} budget-counting new tests for the planned GENERATE items. Only new files (ADD) created for those planned GENERATE items count toward this ${maxGenerate} target — GENERATE items converted to UPDATE do not. You may also include at most one additional discovered-scenario file in \`newTestsCreated\` (the bug-catching test generated after all planned items); that extra test does **not** count against the ${maxGenerate} budget. If you have fewer than ${maxGenerate} budget-counting new tests, backfill from the remaining ADDITIONAL candidates before proceeding. Only proceed with fewer than ${maxGenerate} budget-counting new tests if all candidates failed after retry AND the fallback single-contract test also failed.
+Otherwise (your Budget Plan is non-zero): in \`newTestsCreated\`, you must have exactly as many budget-counting new tests as your committed Budget Plan's generate count (at most ${maxGenerate}). Only new files (ADD) created for the planned GENERATE items count toward this target — GENERATE items converted to UPDATE do not. You may also include at most one additional discovered-scenario file in \`newTestsCreated\` (the bug-catching test generated after all planned items); that extra test does **not** count against the budget. If you have fewer budget-counting new tests than your generate count, backfill from the remaining ADDITIONAL candidates before proceeding. Only proceed with fewer if all candidates failed after retry AND the fallback single-contract test also failed.
 
 Call \`skyramp_submit_report\` with \`summaryOutputFile\`: "${summaryOutputFile}" and \`stateFile\` (from \`skyramp_analyze_changes\` output) — the stateFile is required for execution outcome tracking. Field names, types, and formats are defined in the tool's parameter schema — follow them exactly.
 

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

@@ -3,7 +3,7 @@ jest.unstable_mockModule("../../workspace/workspace.js", () => ({
     WorkspaceConfigManager: jest.fn(),
 }));
 jest.unstable_mockModule("../../services/AnalyticsService.js", () => ({
-    AnalyticsService: { pushMCPToolEvent: jest.fn() },
+    AnalyticsService: { pushMCPToolEvent: jest.fn(() => Promise.resolve()) },
 }));
 jest.unstable_mockModule("../../playwright/traceRecordingPrompt.js", () => ({
     getTraceRecordingPromptText: () => "",

package/build/services/AnalyticsService.js

@@ -4,6 +4,41 @@ import * as path from "path";
 import { fileURLToPath } from "url";
 import { getEntryPoint, getCIPlatform, getRepositoryInfo, } from "../utils/telemetry.js";
 import { logger } from "../utils/logger.js";
+/**
+ * Timeout (ms) for the native FFI analytics call. 5 s is long enough for a
+ * single HTTPS POST to the telemetry endpoint (p99 < 1 s in normal conditions)
+ * but short enough that a hung DNS lookup or unresponsive backend won't stall
+ * the MCP tool response pipeline — the tool result must not be delayed by
+ * best-effort telemetry.
+ */
+const ANALYTICS_TIMEOUT_MS = 5000;
+/**
+ * Race a promise against a timeout. Resolves/rejects with whichever settles
+ * first; the losing branch is left to run (fire-and-forget) but cannot affect
+ * the caller.
+ */
+function withTimeout(promise, ms, label) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label}: timed out after ${ms}ms`)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+/**
+ * Safely invoke the native pushToolEvent FFI call. Wraps the call in a timeout
+ * so a hung Go network call cannot block forever, and catches any synchronous
+ * throw from the native binding (e.g. if the Go runtime panicked on a prior
+ * call and the shared library is in a bad state).
+ */
+async function safePushToolEvent(entryPoint, toolName, errorMessage, params) {
+    try {
+        await withTimeout(pushToolEvent(entryPoint, toolName, errorMessage, params), ANALYTICS_TIMEOUT_MS, "pushToolEvent");
+    }
+    catch (error) {
+        logger.error("safePushToolEvent failed", { error: error instanceof Error ? error.message : String(error) });
+        // Swallow — analytics must never crash the server.
+    }
+}
 export class AnalyticsService {
     static async pushTestGenerationToolEvent(toolName, result, params) {
         const analyticsResult = {};
@@ -33,7 +68,7 @@ export class AnalyticsService {
             // process.cwd() is set by the IDE and may not be the user's repo.
             const repoPath = params.repositoryPath || params.workspacePath;
             Object.assign(params, await getRepositoryInfo(repoPath));
-            await pushToolEvent(getEntryPoint(), toolName, errorMessage, params);
+            await safePushToolEvent(getEntryPoint(), toolName, errorMessage, params);
         }
         catch (error) {
             logger.error("Error pushing MCP tool event", { error: error });
@@ -53,7 +88,7 @@ export class AnalyticsService {
         if (ciPlatform) {
             params.ciPlatform = ciPlatform;
         }
-        await pushToolEvent(getEntryPoint(), "mcp_server_crash", errorMessage, params);
+        await safePushToolEvent(getEntryPoint(), "mcp_server_crash", errorMessage, params);
     }
 }
 /**

package/build/services/TestDiscoveryService.d.ts

@@ -12,13 +12,32 @@ export interface TestDiscoveryOptions {
      *   exist but resource names are unresolvable — most files score 0 (low-relevance)
      *   and are excluded; only the few that happen to match the sentinel are kept.
      * - Empty array `[]`: PR mode with no endpoints from diff or scanner — API/integration
-     *   external tests are excluded entirely; UI tests may still be promoted via hasFrontendChanges.
+     *   external tests are excluded entirely; UI tests may still be promoted via changedFrontendFiles.
      * - `undefined`: full-repo mode — external tests capped at MAX_EXTERNAL_FULL_REPO.
      */
     changedResources?: string[];
-    /** True when the diff contains frontend files — promotes UI test files for framework
-     *  detection regardless of changedResources. Orthogonal to API relevance scoring. */
-    hasFrontendChanges?: boolean;
+    /** Raw changed symbol names (e.g. ["DeploymentCreate"]). Content-grep fallback so an
+     *  external test that references a changed type by name — but whose path/URL matches no
+     *  changed resource (e.g. a schema unit test) — is still surfaced (SKYR-3924). */
+    changedSymbols?: string[];
+    /** True when `changedResources` are precise (derived from specific changed schema/model
+     *  symbols, not the `["unknown"]` sentinel or a broad set). Lets the URL content-match
+     *  bucket skip the MAX_CONTENT_PROMOTED cap — a direct HTTP call to the changed endpoint
+     *  is high-confidence, and the specific resource set naturally bounds the match count. */
+    preciseResources?: boolean;
+    /** Repo-relative paths of the changed frontend (non-test) files — their presence is the
+     *  frontend-change signal that drives UI-test promotion (Step 2). When present, promotion
+     *  is scoped to tests whose name/path/imports are relevant to these files — a frontend PR
+     *  must not pull in the whole monorepo's UI test suite (SKYR-3941). When absent, Step 2 is
+     *  skipped (no UI promotion). */
+    changedFrontendFiles?: string[];
+    /** Selector literals (data-testid values, CSS class tokens) added or removed by the diff.
+     *  UI-test promotion pass 3 ("selector-edge"): a page object / spec couples to a changed
+     *  component by SELECTOR, not by filename or import, so passes 1-2 miss it. Any external
+     *  test-owned file (including page objects, which are not *.test/*.spec) whose body
+     *  references one of these literals is promoted. Both added and removed values are passed
+     *  so a page object still holding a renamed selector's OLD value is caught. */
+    changedSelectors?: string[];
 }
 export declare class TestDiscoveryService {
     private readonly EXCLUDED_DIRS;
@@ -47,7 +66,22 @@ export declare class TestDiscoveryService {
      * Example: "test_orders_api.py" vs ["orders"] → score 1.
      */
     private scoreRelevance;
+    /**
+     * Derive relevance tokens from the changed frontend files, for scoring UI tests in Step 2
+     * the same way scoreRelevance scores against changed API resources. For each file we emit:
+     *  - the basename stem (e.g. "OrderSearch" → "ordersearch") — matches co-located tests like
+     *    OrderSearch.test.tsx, the dominant convention;
+     *  - its sub-tokens, split on delimiters AND camelCase boundaries ("OrderSearch" →
+     *    "order","search") — matches hyphenated/underscored test names like order-search.spec.tsx;
+     *  - the parent directory name — the signal when the basename is generic (orders/index.tsx).
+     * Generic tokens (index, components, utils, …) and tokens shorter than 3 chars are dropped so
+     * a shared dir or an index file doesn't match every UI test in the repo.
+     */
+    private deriveFrontendResourceTokens;
     private readonly MAX_CONTENT_PROMOTED;
+    private readonly MAX_UI_PROMOTED;
+    private readonly UI_IMPORT_MATCH_WEIGHT;
+    private readonly GENERIC_FRONTEND_TOKENS;
     /**
      * Partition external test files into relevant (score > 0) and low-relevance (score = 0).
      * Two-pass: filename token overlap first (primary); content-based endpoint path scan

package/build/services/TestDiscoveryService.js

@@ -3,6 +3,7 @@ import * as path from "path";
 import { logger } from "../utils/logger.js";
 import { TestSource } from "../types/TestAnalysis.js";
 import { TestType } from "../types/TestTypes.js";
+import { buildPathSignatures } from "../utils/pathSignatures.js";
 import fg from "fast-glob";
 export class TestDiscoveryService {
     EXCLUDED_DIRS = [
@@ -104,7 +105,7 @@ export class TestDiscoveryService {
         // Full-repo mode (changedResources is undefined):
         //   No diff context — all external files treated as potentially relevant.
         //   Cap at MAX_EXTERNAL_FULL_REPO to avoid reading hundreds of files.
-        const { changedResources, hasFrontendChanges } = options;
+        const { changedResources, changedSymbols, preciseResources, changedFrontendFiles, changedSelectors } = options;
         let relevantExternal;
         // Includes .e2e.ts — Playwright/Cypress tests that navigate pages. These get
         // testType="e2e" from path detection but are never named *.test.ts or *.spec.ts
@@ -117,7 +118,7 @@ export class TestDiscoveryService {
         // for tests that are misnamed relative to the endpoint they exercise.
         if (changedResources?.length) {
             ({ relevant: relevantExternal } =
-                this.partitionByRelevance(classified.external, changedResources, classified.contentCache));
+                this.partitionByRelevance(classified.external, changedResources, classified.contentCache, changedSymbols, preciseResources));
         }
         else if (changedResources !== undefined) {
             relevantExternal = [];
@@ -125,10 +126,93 @@ export class TestDiscoveryService {
         else {
             relevantExternal = classified.external.slice(0, this.MAX_EXTERNAL_FULL_REPO);
         }
-        // Step 2 — UI test promotion (driven by hasFrontendChanges, independent of Step 1).
-        if (hasFrontendChanges) {
+        // Step 2 — UI test promotion, driven by the presence of changed frontend files and
+        // independent of Step 1. Scoped by relevance to those files, mirroring Step 1's API
+        // discipline: a frontend PR must not pull in the whole monorepo's UI test suite (SKYR-3941).
+        // Absent a changed-frontend-file list, Step 2 is skipped (no UI promotion).
+        if (changedFrontendFiles?.length) {
             const alreadyRelevant = new Set(relevantExternal);
-            const promoted = classified.external.filter(f => UI_TEST_EXT.test(f) && !alreadyRelevant.has(f));
+            const uiCandidates = classified.external.filter(f => UI_TEST_EXT.test(f) && !alreadyRelevant.has(f));
+            // Pass 1 — filename/path relevance: tokens derived from the changed frontend files.
+            const feTokens = this.deriveFrontendResourceTokens(changedFrontendFiles);
+            // Pass 2 — import-edge relevance: module-path signatures of the changed files, matched
+            // against test bodies so a test that imports a changed component (from './PriceLabel')
+            // is caught even when its name shares no token — the recall case a filename-only filter
+            // drops (a checkout test that renders a changed child component). Reuses the same
+            // buildPathSignatures used by frontendIntegration/importerHop; this is Step 2's analog
+            // of Step 1's content-scan fallback. Skip generic basenames (index/app/…): their
+            // signature (`/index'`) would match every barrel import — those are already covered by
+            // pass 1's parent-directory token.
+            const importSignatures = changedFrontendFiles
+                .filter(f => {
+                const stem = path.basename(f).replace(/\.[^.]+$/, "").toLowerCase();
+                return stem.length >= 3 && !this.GENERIC_FRONTEND_TOKENS.has(stem);
+            })
+                .flatMap(f => buildPathSignatures(f));
+            let promoted;
+            if (feTokens.length === 0 && importSignatures.length === 0) {
+                // No relevance signal is derivable — every changed frontend file is a generic
+                // entrypoint (index.tsx / app.tsx / …) whose tokens are filtered out, and none
+                // yields an import signature. A root/entrypoint change is broadly impactful, so
+                // fall back to promoting all UI candidates rather than degenerate to zero — still
+                // bounded by MAX_UI_PROMOTED so it can't re-flood a large monorepo's suite.
+                promoted = uiCandidates.slice(0, this.MAX_UI_PROMOTED);
+                const dropped = uiCandidates.length - promoted.length;
+                logger.info(`UI test promotion: no relevance signal from generic-only frontend changes — capped promote-all fallback (${promoted.length}/${uiCandidates.length} promoted${dropped > 0 ? `, ${dropped} dropped by MAX_UI_PROMOTED` : ""})`);
+            }
+            else {
+                let scored = uiCandidates
+                    .map(f => {
+                    const nameScore = this.scoreRelevance(f, feTokens);
+                    const content = classified.contentCache.get(f) ?? "";
+                    const importsChanged = content.length > 0 && importSignatures.some(sig => content.includes(sig));
+                    return { f, score: nameScore + (importsChanged ? this.UI_IMPORT_MATCH_WEIGHT : 0) };
+                })
+                    .filter(x => x.score > 0)
+                    .sort((a, b) => b.score - a.score)
+                    .map(x => x.f);
+                if (scored.length > this.MAX_UI_PROMOTED) {
+                    logger.info(`UI test promotion: ${scored.length} tests matched ${changedFrontendFiles.length} changed frontend file(s); capping to ${this.MAX_UI_PROMOTED} highest-scoring (SKYR-3941 backstop)`);
+                    scored = scored.slice(0, this.MAX_UI_PROMOTED);
+                }
+                logger.info(`UI test promotion scoped to ${scored.length}/${uiCandidates.length} UI test(s) relevant to changed frontend files`);
+                promoted = scored;
+            }
+            // Pass 3 — selector-edge: a page object / spec couples to a changed component by
+            // SELECTOR (data-testid value or CSS class), not by filename or import, so passes
+            // 1-2 miss it. Crucially the candidate pool here is the FULL external set, not just
+            // UI_TEST_EXT: a page object like `table.component.ts` is classified external (via
+            // the page-objects/ dir pattern) with content cached, but is not a *.test/*.spec
+            // file, so it never enters `uiCandidates`. Promote any not-yet-relevant external
+            // file whose body references a changed selector literal (matched against both the
+            // added and removed diff values, so a page object still holding a renamed selector's
+            // OLD value is caught). Bounded by MAX_UI_PROMOTED.
+            // Combined cap: MAX_UI_PROMOTED is a single Step-2 ceiling, so pass 3 may only add up
+            // to what pass 1/2 left — otherwise the two independent caps could promote 2x and
+            // re-flood discovery (the exact failure SKYR-3941 guards against). Compute the headroom
+            // up front and skip the O(external × selectors) content scan entirely when pass 1/2
+            // already filled the budget.
+            const selectorHeadroom = Math.max(0, this.MAX_UI_PROMOTED - promoted.length);
+            if (changedSelectors?.length && selectorHeadroom > 0) {
+                const alreadyPromoted = new Set([...alreadyRelevant, ...promoted]);
+                const selectorMatched = classified.external
+                    .filter((f) => {
+                    if (alreadyPromoted.has(f))
+                        return false;
+                    const content = classified.contentCache.get(f) ?? "";
+                    return content.length > 0 && changedSelectors.some((sel) => content.includes(sel));
+                })
+                    // Sort for a deterministic cap — filesystem/glob traversal order is not stable
+                    // across environments, so which files survive MAX_UI_PROMOTED must not depend on it.
+                    .sort();
+                if (selectorMatched.length > 0) {
+                    const capped = selectorMatched.slice(0, selectorHeadroom);
+                    logger.info(`UI test promotion: ${selectorMatched.length} test/page-object file(s) reference a changed selector (pass 3, selector-edge)` +
+                        (capped.length < selectorMatched.length ? `; added ${capped.length} (MAX_UI_PROMOTED headroom after pass 1/2)` : ""));
+                    if (capped.length > 0)
+                        promoted = [...promoted, ...capped];
+                }
+            }
             const promotedSet = new Set(promoted);
             // Promote snapshot/fixture siblings of scored AND newly promoted UI tests.
             // Include promoted files so siblings are found on UI-only PRs where
@@ -188,9 +272,59 @@ export class TestDiscoveryService {
             return parts.length > 1 && parts.every(p => p.length >= 3 && expanded.has(p));
         }).length;
     }
+    /**
+     * Derive relevance tokens from the changed frontend files, for scoring UI tests in Step 2
+     * the same way scoreRelevance scores against changed API resources. For each file we emit:
+     *  - the basename stem (e.g. "OrderSearch" → "ordersearch") — matches co-located tests like
+     *    OrderSearch.test.tsx, the dominant convention;
+     *  - its sub-tokens, split on delimiters AND camelCase boundaries ("OrderSearch" →
+     *    "order","search") — matches hyphenated/underscored test names like order-search.spec.tsx;
+     *  - the parent directory name — the signal when the basename is generic (orders/index.tsx).
+     * Generic tokens (index, components, utils, …) and tokens shorter than 3 chars are dropped so
+     * a shared dir or an index file doesn't match every UI test in the repo.
+     */
+    deriveFrontendResourceTokens(changedFrontendFiles) {
+        const out = new Set();
+        const add = (t) => {
+            const v = t.toLowerCase();
+            if (v.length >= 3 && !this.GENERIC_FRONTEND_TOKENS.has(v))
+                out.add(v);
+        };
+        for (const f of changedFrontendFiles) {
+            const segs = f.replace(/\\/g, "/").split("/").filter(Boolean);
+            const base = segs[segs.length - 1] ?? "";
+            const stem = base.replace(/\.[^.]+$/, ""); // drop extension
+            add(stem); // whole stem (e.g. "ordersearch", "order-search")
+            for (const t of stem.split(/[-_.]+|(?<=[a-z0-9])(?=[A-Z])/))
+                add(t); // sub-tokens
+            const parent = segs[segs.length - 2];
+            if (parent && !parent.startsWith("__"))
+                add(parent);
+        }
+        return [...out];
+    }
     // Max additional tests promoted via content-based scoring on top of filename matches.
     // Content matches are lower-confidence than filename matches — cap to avoid token bloat.
     MAX_CONTENT_PROMOTED = 5;
+    // Backstop cap on scoped UI-test promotion (Step 2). The relevance filter against the
+    // changed frontend files does the real bounding; this only guards a pathological match
+    // (e.g. a change to a widely-shared component). Highest-scoring tests survive truncation.
+    MAX_UI_PROMOTED = 50;
+    // Weight added to a UI test's relevance score when it imports a changed frontend file by
+    // module path (import-edge match, Step 2 pass 2). Set high above any filename-token score
+    // so import matches — the strongest "this test exercises the changed code" signal —
+    // always survive the MAX_UI_PROMOTED cap ahead of name-only matches.
+    UI_IMPORT_MATCH_WEIGHT = 100;
+    // Generic path/name tokens that carry no feature signal — excluded when deriving relevance
+    // tokens from changed frontend files so a changed index.tsx or a shared "components" dir
+    // doesn't match every UI test in the repo.
+    GENERIC_FRONTEND_TOKENS = new Set([
+        "index", "app", "main", "root", "styles", "style", "css", "scss", "types", "type",
+        "constants", "utils", "util", "helpers", "helper", "components", "component", "pages",
+        "page", "routes", "route", "src", "common", "shared", "hooks", "hook", "lib", "context",
+        "providers", "provider", "store", "stores", "api", "test", "tests", "spec", "specs",
+        "mocks", "mock", "fixtures", "fixture", "assets", "config",
+    ]);
     /**
      * Partition external test files into relevant (score > 0) and low-relevance (score = 0).
      * Two-pass: filename token overlap first (primary); content-based endpoint path scan
@@ -198,8 +332,9 @@ export class TestDiscoveryService {
      * (e.g. test_checkout_flow.py testing /api/orders scores 0 by name but matches in content).
      * Content matches are capped at MAX_CONTENT_PROMOTED to bound token impact.
      */
-    partitionByRelevance(files, changedResources, contentCache) {
+    partitionByRelevance(files, changedResources, contentCache, changedSymbols, preciseResources) {
         const nameMatched = [];
+        const symbolMatched = [];
         const contentCandidates = [];
         // Precompile content patterns once — avoids 20 resources × 150 files = 3K compilations.
         const contentPatterns = contentCache
@@ -212,22 +347,58 @@ export class TestDiscoveryService {
                 return new RegExp(`["'\`][^"'\`]*/${escaped}`, "i");
             })
             : [];
+        // Exact, case-sensitive word-boundary match on a changed type name (e.g.
+        // `DeploymentCreate`). Catches an external test that references the changed schema/model
+        // by name but whose path/URL matches no changed resource — a schema unit test
+        // constructing it directly (SKYR-3924). High-confidence, so not subject to the content cap.
+        const symbolPatterns = contentCache
+            ? (changedSymbols ?? []).map(s => new RegExp(`\\b${s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`))
+            : [];
+        // Endpoint-call patterns: an HTTP-method call to a path containing the changed resource
+        // (e.g. `client.post("/deployments/")`). A direct call to the changed endpoint is
+        // high-confidence — distinct from a file that merely mentions the resource string.
+        const endpointCallPatterns = contentCache
+            ? changedResources.map(r => {
+                const escaped = r.toLowerCase()
+                    .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+                    .replace(/-|\//g, "[-/]");
+                return new RegExp(`\\b(?:get|post|put|patch|delete|request|fetch)\\b[^\\n]{0,60}["'\`][^"'\`]*/${escaped}`, "i");
+            })
+            : [];
+        const strongContent = [];
         for (const f of files) {
             if (this.scoreRelevance(f, changedResources) > 0) {
                 nameMatched.push(f);
+                continue;
             }
-            else if (contentPatterns.length > 0) {
-                const content = contentCache.get(f) ?? "";
-                if (content && contentPatterns.some(p => p.test(content))) {
-                    contentCandidates.push(f);
-                }
+            const content = contentCache?.get(f) ?? "";
+            if (!content)
+                continue;
+            if (symbolPatterns.some(p => p.test(content))) {
+                symbolMatched.push(f);
+            }
+            else if (endpointCallPatterns.some(p => p.test(content))) {
+                strongContent.push(f); // direct call to the changed endpoint — high-confidence
+            }
+            else if (contentPatterns.some(p => p.test(content))) {
+                contentCandidates.push(f); // loose mention of the resource — low-confidence, capped
             }
         }
-        const contentMatched = contentCandidates.slice(0, this.MAX_CONTENT_PROMOTED);
-        if (contentMatched.length > 0) {
-            logger.info(`Content-based relevance: promoting ${contentMatched.length} test(s) (capped at ${this.MAX_CONTENT_PROMOTED})`);
-        }
-        return { relevant: [...nameMatched, ...contentMatched] };
+        // Precise resource sets (schema-diff preload): keep high-confidence endpoint-call matches
+        // uncapped (bounded by the specific resource), still cap loose mentions. Otherwise cap all
+        // content matches together (original behavior).
+        const contentMatched = preciseResources
+            ? [...strongContent, ...contentCandidates.slice(0, this.MAX_CONTENT_PROMOTED)]
+            : [...strongContent, ...contentCandidates].slice(0, this.MAX_CONTENT_PROMOTED);
+        if (symbolMatched.length > 0 || contentMatched.length > 0) {
+            // Report what actually landed in contentMatched — the non-precise branch caps
+            // strong+loose together, so strongContent may be truncated too. Deriving both
+            // counts from contentMatched.length avoids a misleading negative "loose" count.
+            const strongIn = Math.min(strongContent.length, contentMatched.length);
+            const looseIn = contentMatched.length - strongIn;
+            logger.info(`Relevance: ${symbolMatched.length} symbol + ${strongIn} endpoint-call + ${looseIn} loose content`);
+        }
+        return { relevant: [...nameMatched, ...symbolMatched, ...contentMatched] };
     }
     /**
      * Process test files in parallel batches with concurrency control