@skyramp/mcp 0.2.7 → 0.2.150-rc.mntnc

package/build/prompts/sut-setup/shared.js

@@ -0,0 +1,132 @@
+/**
+ * Path of the Testbot workflow file relative to the repo root. Created by the
+ * Testbot installer and edited in-place by every SUT setup mode.
+ */
+export const TESTBOT_WORKFLOW_PATH = ".github/workflows/skyramp-testbot.yml";
+export var SutSetupMode;
+(function (SutSetupMode) {
+    SutSetupMode["None"] = "none";
+    SutSetupMode["AdaptWorkflow"] = "adapt_workflow";
+    SutSetupMode["DockerCompose"] = "docker_compose";
+})(SutSetupMode || (SutSetupMode = {}));
+/**
+ * Glossary block rendered right after the first mention of "SUT" in each
+ * setup prompt. Shared across modes so the LLM gets a single explicit
+ * definition rather than inferring it from context.
+ */
+export function buildSutDefinitionBlock() {
+    return `**System Under Test (SUT)** — the application services this workflow brings up so Testbot can exercise them end-to-end. The SUT is what runs the PR's source code: backend services (REST/gRPC APIs), their supporting infrastructure (databases, queues, caches), and any frontend UI under test. The SUT does NOT include the test runner itself or Testbot. Bringing up the SUT means building from PR source, starting all required services, seeding any data tests rely on, and exposing a health check that proves the system is ready for traffic.
+
+`;
+}
+export function buildContextBlock(args) {
+    const lines = [];
+    lines.push(`<context>`);
+    lines.push(`Repository path: ${args.repositoryPath}`);
+    lines.push(`Setup mode: ${args.sutSetupMode}`);
+    if (args.sutSourceWorkflowFile)
+        lines.push(`Source workflow file: ${args.sutSourceWorkflowFile}`);
+    if (args.sutSourceDockerComposeFile)
+        lines.push(`Source docker-compose file: ${args.sutSourceDockerComposeFile}`);
+    lines.push(`</context>`);
+    return lines.join("\n");
+}
+export function buildLocalValidationSection() {
+    return `Before reporting success, exercise the adapted workflow locally. Testbot's external fix loop only retries when SUT lifecycle commands are set on the Testbot action. When the SUT is brought up by surrounding GHA steps (skipTargetSetup: 'true'), the fix loop is skipped — so the local check below is the only safety net before the workflow is committed.
+Run commands one at a time in your shell — individual execution pinpoints failures far faster than running the whole workflow at once. Any non-zero exit is a fix-needed signal: adjust the workflow, re-run the failing command, and do not proceed until it passes.
+1. Validate build scripts and helper programs first — run these before anything else so build and auth failures surface cheaply:
+   a. Every helper script the workflow calls (e.g., \`./scripts/*.sh\`, \`make <target>\`, \`./gradlew <task>\`) — run each and confirm exit 0.
+   b. \`.skyramp/sut/get-auth-token.sh\` if present — run it and confirm it prints a non-empty token to stdout.
+   c. Validate any standalone Dockerfile referenced by GHA \`steps:\` (not by a compose service) with \`docker build\`. Do NOT also run \`docker build\` on Dockerfiles that belong to a compose service — \`docker compose build\` (next step) already builds them in one BuildKit graph; doubling up wastes ~5-10 GB of cache per service.
+   d. Every docker-compose file the workflow references — run \`docker compose -f <path> config\` to validate the YAML, then \`docker compose -f <path> build\`.
+   e. **Disk hygiene between heavy builds.** Between any two build commands (Dockerfile, compose, helper scripts that build), if the runner is under ~5 GB free or you see \`no space left on device\`, run \`docker builder prune -af -f && docker image prune -af\` before the next build. This frees BuildKit cache + dangling images without losing the running stack. Skipping this on heavy SUTs (medusa, calcom, mattermost, supabase) exhausts the ~14 GB \`ubuntu-latest\` disk mid-validation.
+2. Validate the SUT lifecycle — choose the branch that matches the chosen pattern:
+   a. If lifecycle commands are set on the Testbot action (skipTargetSetup is unset):
+      i. Run \`targetSetupCommand\` — confirm exit 0.
+      ii. Poll \`targetReadyCheckCommand\` until it exits 0 within \`targetReadyCheckTimeout\` seconds.
+      iii. Run \`targetTeardownCommand\` — confirm cleanup and exit 0.
+   b. If GHA steps wrap the Testbot action (skipTargetSetup: 'true'):
+      i. Extract the shell body of each SETUP step and run them in order. If a step depends entirely on a \${{ secrets.* }} value your shell cannot resolve, note it in <thinking> and skip — do not fabricate a value.
+      ii. Poll \`targetReadyCheckCommand\` until it exits 0.
+      iii. Extract and run each TEARDOWN step's body in order so the next iteration starts clean.
+Only proceed to the success report once setup → health check → teardown all pass.`;
+}
+/**
+ * Returns the canonical "add to the Testbot workflow" block: every input that
+ * controls the SUT lifecycle, auth, and workflow-level setup, followed by the
+ * shared What to do / What not to do guidance (including the sutSetupMode
+ * bootstrap guard). Shared by every SUT setup mode (adapt_workflow and
+ * docker_compose) so the input semantics and rules never drift between prompts.
+ */
+export function buildAddToTestbotWorkflowSection() {
+    return `#### Testbot action inputs - Add target lifecycle commands and auth to Testbot Workflow
+For the full Testbot action input reference (defaults, edge cases, advanced options beyond the ones called out below), see the Testbot README: https://github.com/letsramp/testbot#inputs
+
+Target lifecycle inputs (control how Testbot starts, validates, and stops the SUT):
+1. \`targetSetupCommand\` — shell command that builds and starts all SUT services. Testbot runs this before tests.
+   a. Default when unset: \`docker compose up -d\` (starts existing images, does NOT build).
+   b. For PR-source builds use \`docker compose up -d --build\` or the equivalent for helm/script-based SUTs.
+   c. With a dedicated compose file (reused or generated), point at it explicitly: \`docker compose -f .skyramp/sut/docker-compose.testbot.yml --project-directory . up -d --build\`.
+   d. Override whenever the source workflow's start sequence differs from the default.
+2. \`targetReadyCheckCommand\` — polling command (e.g., \`curl -sf http://localhost:8080/health\`) that Testbot runs repeatedly after setup until it exits 0 (service is ready) or the timeout is reached.
+   a. **CRITICAL: Always set this to a valid target readiness check command.** Required in every pattern: when \`targetSetupCommand\` is explicit, when relying on the \`docker compose up -d\` default, AND when surrounding GHA steps bring the SUT up before the Testbot action (\`skipTargetSetup: 'true'\`). Testbot's fail-early gate throws \`Unable to verify service readiness\` when no readiness signal is available (neither this nor a workspace service \`baseUrl\`) and the action exits non-zero. It is also what gates a backgrounded \`targetSetupCommand\` — without it Testbot can't tell when the service is actually listening.
+3. \`targetReadyCheckTimeout\` — seconds to wait for \`targetReadyCheckCommand\` to succeed.
+   a. Default: \`1800\` (30 min) — sized for cold \`docker compose --build\` runs on multi-service stacks. The loop exits on the first success, so fast services pay no extra cost. Override only if you want to fail faster on stuck setups (e.g. \`'300'\` for a small single-service SUT).
+4. \`targetTeardownCommand\` — shell command that stops and cleans up the SUT after tests (e.g., \`docker compose down -v\`, or \`docker compose -f .skyramp/sut/docker-compose.testbot.yml --project-directory . down -v\` for a dedicated compose file).
+   a. Always set this so each run starts from a clean state.
+   b. Omit only when teardown is handled by surrounding GHA steps with \`if: always()\`.
+5. \`skipTargetSetup\` — when \`'true'\`, Testbot skips running \`targetSetupCommand\` entirely.
+   a. Set this only when GHA steps surrounding the Testbot action already bring the SUT up.
+   b. Leave it unset (or \`'false'\`) when Testbot should run the full lifecycle via the inputs above.
+Auth inputs (used by Testbot to authenticate against the running SUT during test recording and execution):
+6. \`authTokenCommand\` — shell command whose stdout is the auth credential for REST/gRPC API testing (e.g., a Bearer token, API key, or session cookie). Testbot captures the output and injects it as the \`Authorization\` header.
+   a. Set this when the SUT requires authentication for API calls.
+   b. If the source workflow exports a token via a step output or script, wire that same script here (e.g., \`bash .skyramp/sut/get-auth-token.sh\`).
+   c. If the workflow seeds a test user during setup, create \`.skyramp/sut/get-auth-token.sh\` that logs in with those credentials and prints the token.
+   d. Omit when the SUT APIs are unauthenticated.
+7. \`uiCredentials\` — \`username:password\` pair typed into the browser login form during UI test recording (format: \`myuser:mypassword\`).
+   a. Set for any frontend service that requires browser-based login.
+   b. Use \`\${{ secrets.SKYRAMP_UI_CREDENTIALS }}\` if the secret exists, otherwise use credentials seeded during SUT setup.
+Workflow / job level settings (set on the workflow or job, not as \`skyramp/testbot\` action inputs):
+8. Secrets / environment variables — pass every secret/env var the setup needs into the workflow via an \`env:\` block or \`secrets: inherit\`, and add any dependency-resolution steps/jobs the SUT requires.
+9. \`runs-on\` runner label — switch to a larger runner when the SUT needs more disk or memory: heavy Docker builds, large dependency installs, or a multi-service (3+) compose stack. Standard runners run out of disk and crash with \`No space left on device\`. Runner names vary by org — do not hardcode \`large-ubuntu\`. Pick the label by (a) preserving whatever larger label the source workflow already uses (never downgrade to \`ubuntu-latest\`), (b) reusing the label adjacent heavy or integration jobs in \`.github/workflows/\` already use, or (c) falling back to a known GitHub-hosted large label such as \`ubuntu-latest-large\`.
+
+#### What to do
+Edit \`${TESTBOT_WORKFLOW_PATH}\` in place (already created by the Testbot installer) — do NOT recreate it. Add only what the SUT needs onto the existing \`skyramp/testbot\` action step, alongside the inputs the installer already added:
+1. The 4 target lifecycle inputs — \`targetSetupCommand\`, \`targetReadyCheckCommand\`, \`targetReadyCheckTimeout\`, \`targetTeardownCommand\`.
+2. The 2 auth inputs when the SUT needs them — \`authTokenCommand\` and/or \`uiCredentials\`.
+3. Any secrets / environment variables and dependency-resolution steps/jobs the setup needs (input 8).
+4. The \`runs-on\` runner label, if a larger runner is needed (input 9).
+5. Use a daemon/detached form for \`targetSetupCommand\` — \`docker compose up -d --build\`, \`nohup npm start &\`, \`./server &\`, \`pnpm --prefix ./apps/studio start &\`. The command should launch the service and exit; \`targetReadyCheckCommand\` is what gates readiness. Testbot backgrounds foreground-blocking commands (\`npm start\`, \`python app.py\`, \`./server\`) automatically after a 5-minute timeout as a safety net, so they will eventually work — but daemon mode is faster (no 5-minute wait) and surfaces startup crashes clearly via the command's exit code. If no daemon form is available and the repo has no \`docker-compose.yml\`, wrap the foreground command in compose (a \`Dockerfile\` + \`docker-compose.yml\` running \`npm start\`) so it can be launched with \`docker compose up -d --build\`. Only fall back to a GHA pre-step with \`&\` (e.g. \`run: npm start &\`) if Docker is not feasible.
+
+#### What not to do
+1. IMPORTANT — do NOT remove or change the existing \`sutSetupMode\` input (nor \`sutSourceWorkflowFile\` / \`sutSourceDockerComposeFile\`). Leave \`sutSetupMode\` exactly as provided: Testbot flips it to \`none\` automatically after validation succeeds, and the committed \`sutSetupMode\` value is the signal that tells the next CI run to validate this adapted workflow rather than run tests. Deleting it or setting it to \`none\` breaks the bootstrap/validation cycle.
+2. Do not point the SUT at a prebuilt upstream image (e.g. \`image: org/app:latest\` or a fixed commit SHA from \`main\`) for any application service under test. The image will lag the PR and Testbot will validate stale code.
+3. Do not point the SUT at a remote staging or production environment for application services under test. Staging code drifts from PR source and turns Testbot's results into noise. External infra is acceptable only for sidecar dependencies the PR does not change (e.g. a managed test database).
+4. Do not use a foreground-blocking command as \`targetSetupCommand\` (e.g. \`npm start\`, \`pnpm --prefix ./apps/studio start\`, \`python app.py\`, \`prefect server start\`, \`./server\`) — see input 5 in "What to do" above for daemon forms and the compose-wrap fallback.
+5. Do not leave server processes running between fix-loop retries. If \`targetSetupCommand\` starts a direct process (not \`docker compose\`), always set \`targetTeardownCommand\` to kill it (e.g. \`pkill -f "node dist/index.js"\` or \`docker compose down\`). Without teardown, retried setup attempts will fail with \`EADDRINUSE\` because the previous process still holds the port.
+`;
+}
+/**
+ * `buildAddToTestbotWorkflowSection()` output with its leading
+ * `#### Testbot action inputs ...` header stripped — for use as a PromptPlan
+ * step body where the PromptPlan step header replaces the inline `####`.
+ */
+export function buildInputsBody() {
+    const text = buildAddToTestbotWorkflowSection();
+    const firstNewline = text.indexOf("\n");
+    return text.slice(firstNewline + 1);
+}
+export function buildCommonSutErrorsSection() {
+    return `Before finishing, verify the adapted Testbot workflow setup against common errors seen during SUT setup:
+1. port_conflict — another container is already using the port. Pick a free host port or stop the conflicting container.
+2. image_not_found / build_failed — the referenced image does not exist for this SHA, or the build step has the wrong context/Dockerfile path. Build from PR source, do not rely on upstream commit-SHA tags.
+3. healthcheck_timeout — the service is slow to come up. Use \`targetReadyCheckTimeout >= 120\` and ensure the health endpoint actually exists.
+4. connection_refused — the service is not listening on the expected host/port (often binding to 127.0.0.1 inside the container; bind to 0.0.0.0).
+5. dependency_error — required service (DB, cache, queue) is missing from compose or not healthy before the app starts. Add \`depends_on\` with \`condition: service_healthy\`.
+6. permission_denied — script is not executable (\`chmod +x\`) or volume mount has wrong ownership.
+7. auth_endpoint_404 / auth_credentials_invalid — the auth script hits a wrong path, or the database has no seeded user. The auth script must create the user before login when starting from a fresh DB.
+8. missing env vars / secrets — required env vars are unset on the runner. Either default them in the script or pass them through workflow \`env:\`.
+9. no_space_left — the runner ran out of disk space (\`No space left on device\`). This happens on standard runners when the SUT involves large Docker builds, many npm packages, or multiple compose services that pull large images. Switch \`runs-on\` to a larger runner — runner names vary by org, do not hardcode \`large-ubuntu\`. Pick the label by (a) preserving whatever larger label the source workflow already uses, (b) reusing the label adjacent heavy or integration jobs in \`.github/workflows/\` already use, or (c) falling back to a known GitHub-hosted large label such as \`ubuntu-latest-large\`. Indicator: source workflow already specifies a large runner, or the SUT has multi-stage Docker builds / a compose file with 3+ services.
+Do not add an in-prompt fix loop — Testbot's external validator will retry with concrete error context if any of these occur.`;
+}

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

@@ -136,7 +136,9 @@ Actions:
 **UPDATE vs REGENERATE — the deciding question is whether the root response wrapper changed:**
 - **REGENERATE** only when a new top-level envelope object wraps the entire payload or the root key is renamed so that essentially every existing assertion must change.
 - **UPDATE** for everything else. If you can describe the fix as "patch these N assertion paths", it is UPDATE regardless of how many paths there are.
-- When every assertion in the file is invalid, it is REGENERATE. When you can still patch individual paths, it is UPDATE.`;
+- When every assertion in the file is invalid, it is REGENERATE. When you can still patch individual paths, it is UPDATE.
+
+**Non-test consumer check:** When the diff removes or renames response fields, also grep the repository for non-test source files that import or reference the changed schema type (e.g. \`grep -r "WorkQueueStatusDetail" src/\`). If any client model, SDK class, or serializer references the old field names, add a VERIFY entry for each such file in your recommendations so the developer is alerted — these are not test files but they will break at runtime.`;
 }
 export function buildCheckAuthAndAuthorization() {
     return `Has the authentication or authorization for this endpoint changed?
@@ -180,7 +182,7 @@ export function buildCheckAssignAction() {
 **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 specific reason the changed code 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"). Generic "unrelated endpoint" or "service boundary" without a diff reference is not sufficient.
+- 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.
 - **Scope gate:** If the changed code is clearly not reachable through the service or base URL this test targets, assign IGNORE.
@@ -222,12 +224,16 @@ export function buildDriftOutputChecklist(stateFile, existingTests) {
     const noTestsNote = !hasTests
         ? `\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.`
+        : "";
     const existingTestSection = `**Existing tests (${existingTests?.length ?? 0} total) — assess ALL of the following:**
 ${testList}
 ${noTestsNote}
 **UPDATE scope notes:**
 - UPDATE is an in-place edit — do not recommend creating a new file for an already-tested endpoint.
 - If a new HTTP method is added to a resource, emit a separate UPDATE entry for every existing test file that covers that resource (contract, integration, UI).
+- **When multiple test files cover the same changed resource, prefer the most resource-specific file** (e.g. a file whose name directly reflects the changed resource) over a generic shared test file. Only UPDATE both if the change affects base types shared across both files.
 
 For each test above, output one entry:
 - **IGNORE**: \`{testFile} — IGNORE: {reason the diff cannot reach this test's endpoint}\`
@@ -253,7 +259,7 @@ 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.
 Be concise — one line per IGNORE/VERIFY entry.`;
-    const sections = [existingTestSection, finalStep];
+    const sections = [symbolDiscoveryStep, existingTestSection, finalStep].filter(Boolean);
     return `<output_format>
 Complete ALL of the following:
 

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

@@ -127,7 +127,7 @@ An unintegrated non-route component has no DOM node in the running app and canno
         return `${canInline ? "Read the \`<diff>\` above" : `Read the diff file at \`${p.diffFilePath}\``} and identify every new or modified API endpoint — route registrations, handler methods, controller annotations. Then use the **Router Mounting / Nesting** section above to reconstruct the full URL path for each endpoint by chaining all parent router prefixes down to the handler (e.g. a handler in a file with \`prefix="/reviews"\` that is mounted at \`/{product_id}\` under a router mounted at \`/api/v1/products\` → full path \`/api/v1/products/{product_id}/reviews\`).
 ${diffHasJavaFiles ? JAVA_SPRING_NOTE : ""}
 For each endpoint found: note the HTTP method, full path, and source file.
-${preDetectedEndpoints ? "The endpoint catalog above already lists some changed endpoints — verify and augment with anything it missed." : "No endpoints were pre-detected in the changed files — extract them from the diff."}
+${preDetectedEndpoints ? "The endpoint catalog above already lists some changed endpoints — verify and augment with anything it missed. **If a changed file contains many endpoints (hub/routing files like api.go, routes.py, router.ts), cross-reference against the diff hunks to identify only the endpoints whose handler code actually changed — do not include neighboring routes whose code was untouched.**" : "No endpoints were pre-detected in the changed files — extract them from the diff."}
 **Also identify removed endpoints**: Look for deleted route annotations (lines starting with \`-\` in the diff) in modified files (files that still exist but had routes deleted). A removed endpoint is a route definition present in the base branch but absent in the current branch. Cross-reference against the scanned endpoint listing below — if a deleted route annotation's endpoint still appears there (e.g. moved to another file), it is NOT removed. Only flag endpoints that are truly gone from the codebase.
 **CRITICAL — Query params vs body:** For GET endpoints (especially search/filter/list),
 identify which parameters are URL query params vs request body. Look at framework-specific

package/build/prompts/testbot/testbot-prompts.d.ts

@@ -1,7 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type Service } from "../../workspace/workspace.js";
 export declare function getTestbotPrompt(prTitle: string, prDescription: string, summaryOutputFile: string, repositoryPath: string, baseBranch?: string, maxRecommendations?: number, maxGenerate?: number, _maxCritical?: number, // Reserved — accepted for API compat but not yet wired into prompt
-prNumber?: number, userPrompt?: string, services?: Service[], stateOutputFile?: string, uiCredentials?: string, testsRepoDir?: string): string;
+prNumber?: number, userPrompt?: string, services?: Service[], uiCredentials?: string, testsRepoDir?: string): string;
 /**
  * Read services from .skyramp/workspace.yml. Returns empty array if
  * the workspace file doesn't exist or can't be parsed.

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

@@ -2,7 +2,6 @@ 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 { buildDriftAnalysisPrompt } from "../test-maintenance/drift-analysis-prompt.js";
 import { getTraceRecordingPromptText } from "../../playwright/traceRecordingPrompt.js";
 import { isContractConsumerModeEnabled } from "../../utils/featureFlags.js";
 import { resolveServiceDetailsRef } from "../../utils/utils.js";
@@ -19,7 +18,7 @@ const CONTRACT_MODE_GUIDANCE = CONSUMER_MODE_ENABLED
   Both modes (\`providerMode: true, consumerMode: true\`): For diff that contains BOTH provider signals (such as new/modified endpoint handlers, route changes this service owns) AND consumer signals (outbound HTTP client calls to another service, no new endpoint handlers).`
     : `  Always add \`providerMode: true\` — the tool generates provider-side contract tests only.`;
 export function getTestbotPrompt(prTitle, prDescription, summaryOutputFile, repositoryPath, baseBranch, maxRecommendations = MAX_RECOMMENDATIONS, maxGenerate = MAX_TESTS_TO_GENERATE, _maxCritical = MAX_CRITICAL_TESTS, // Reserved — accepted for API compat but not yet wired into prompt
-prNumber, userPrompt, services, stateOutputFile, uiCredentials, testsRepoDir) {
+prNumber, userPrompt, services, uiCredentials, testsRepoDir) {
     maxGenerate = Math.min(Math.max(maxGenerate, 0), maxRecommendations);
     // For follow-up requests: emit the @skyramp-testbot header + guardrails + retrieve-recommendations step.
     // For first-run prompts: emit the full Task 1 analysis + maintenance section.
@@ -42,7 +41,7 @@ Verify the prompt inside <USER_PROMPT> is related to adding or removing tests fr
 - If the prompt matches one or more tests in the Additional Recommendations → proceed to Task 1 (Skip Analysis).
 
 ### Task 1: Retrieve Previous Recommendations
-Call \`skyramp_analyze_changes\` with \`repositoryPath\`: "${repositoryPath}", \`scope\`: "branch_diff"${baseBranch ? `, \`baseBranch\`: "${baseBranch}"` : ""}${prNumber ? `, \`prNumber\`: ${prNumber}` : ""}${stateOutputFile ? `, \`stateOutputFile\`: "${stateOutputFile}"` : ""}${testsRepoDir ? `, \`testsRepoDir\`: "${testsRepoDir}"` : ""}.
+Call \`skyramp_analyze_changes\` with \`repositoryPath\`: "${repositoryPath}", \`scope\`: "branch_diff"${baseBranch ? `, \`baseBranch\`: "${baseBranch}"` : ""}${prNumber ? `, \`prNumber\`: ${prNumber}` : ""}${testsRepoDir ? `, \`testsRepoDir\`: "${testsRepoDir}"` : ""}.
 This will fetch the previous TestBot report from the PR comments and return deduplicated recommendations.
 Use those recommendations as your baseline. Only add or remove tests that the user requested AND that appear in the Additional Recommendations. Then proceed straight to Task 2: Generate New Tests.
 `
@@ -51,7 +50,7 @@ Use those recommendations as your baseline. Only add or remove tests that the us
 
 ## Task 1: Analyze & Maintain
 
-1. Call \`skyramp_analyze_changes\` with \`repositoryPath\`: "${repositoryPath}", \`scope\`: "branch_diff", \`topN\`: ${maxRecommendations}, \`maxGenerate\`: ${maxGenerate}${baseBranch ? `, \`baseBranch\`: "${baseBranch}"` : ""}${prNumber ? `, \`prNumber\`: ${prNumber}` : ""}${stateOutputFile ? `, \`stateOutputFile\`: "${stateOutputFile}"` : ""}${testsRepoDir ? `, \`testsRepoDir\`: "${testsRepoDir}"` : ""}.
+1. Call \`skyramp_analyze_changes\` with \`repositoryPath\`: "${repositoryPath}", \`scope\`: "branch_diff", \`topN\`: ${maxRecommendations}, \`maxGenerate\`: ${maxGenerate}${baseBranch ? `, \`baseBranch\`: "${baseBranch}"` : ""}${prNumber ? `, \`prNumber\`: ${prNumber}` : ""}${testsRepoDir ? `, \`testsRepoDir\`: "${testsRepoDir}"` : ""}.
 
    **Follow all instructions returned by \`skyramp_analyze_changes\`** — its response opens with a **UI Blueprint Capture** section that tells you which candidate URLs to capture (and how) before you write any UI recommendation \`reasoning\`.${uiCredentials ? " If the section lists candidate URLs, log in once via the credentials in your <ui-credentials> context before navigating to them." : ""}
 
@@ -63,7 +62,13 @@ Use those recommendations as your baseline. Only add or remove tests that the us
 
 2. **Maintain existing tests:**
 
-${buildDriftAnalysisPrompt()}
+   a. Call \`skyramp_analyze_test_health\` with \`stateFile\` (from \`skyramp_analyze_changes\` output). **Do NOT read application source files** (routes, models, controllers) — all change information you need is in the \`skyramp_analyze_changes\` output and the diff.
+
+   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 or REGENERATE. Run them 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.
 
 3. **Code review:** From the \`skyramp_analyze_changes\` output and the existing test files you read for maintenance, note any logic bugs. Do NOT read additional source files just for code review — use what is already available from the analysis and test file reads. Common patterns to flag:
    - Computed fields not recalculated after mutation (e.g. \`total_amount\` unchanged after items are added/removed)
@@ -286,7 +291,7 @@ ${userPrompt ? "Generate only the tests that the user requested from the Additio
 - 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.
 - **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.
+  **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:**
   - **(a) App is unreachable** — \`browser_navigate\` fails or connection is refused.
   - **(b) Unintegrated non-route component** — the changed file is a leaf component (not a framework route/entrypoint) that has no integration point in the running app. To confirm:
@@ -466,9 +471,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.
 
-**Execution timing:**
-- **beforeStatus** (maintained tests only): execute each maintained test file **once at the start** (before any edits) to capture \`beforeStatus\`. This is the only execution allowed before edits.
-- **Final execution**: Do NOT call \`skyramp_execute_test\` again until ALL maintenance edits AND ALL new test generation/enhancement are complete. Then execute every test file once — maintained files (for \`afterStatus\`) and new files together. Run independent files in parallel (same tool call batch).
+**Final execution (mandatory):** Do NOT call \`skyramp_execute_test\` until ALL maintenance edits AND ALL new test generation/enhancement are complete.
 - 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.
 
@@ -494,16 +497,24 @@ In these cases:
 
 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.
 
-Call \`skyramp_submit_report\` with \`summaryOutputFile\`: "${summaryOutputFile}". Field names, types, and formats are defined in the tool's parameter schema — follow them exactly.
+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.
 
 - **additionalRecommendations**: AT MOST ${maxRecommendations - maxGenerate} items.
   - For \`testType: "contract"\` entries: **\`primaryEndpoint\` is required** (e.g. \`"GET /api/v1/users/{user_id}"\`). The tool will reject the submission without it — do not omit it or you will be forced to resubmit.
   - For \`testType: "integration"\` or \`"e2e"\` entries: omit \`primaryEndpoint\` — use \`description\` to list the endpoints involved instead.
-- **testMaintenance**: Use \`[]\` **only** if no existing Skyramp tests were found in the repository. If existing tests were found (any score), include one entry per test. Set \`action\` to the exact drift action you chose from the Action Decision Matrix (\`UPDATE\`, \`REGENERATE\`, \`DELETE\`, \`VERIFY\`, or \`IGNORE\`). For UPDATE/REGENERATE/DELETE tests that were modified and executed, populate all fields from real before/after execution results. For VERIFY/IGNORE tests (not modified), derive \`beforeStatus\` from the \`skyramp_analyze_test_health\` health score (typically \`"Pass"\` if drift score is 0 and no health issues were flagged), set \`afterStatus\` to \`"Skipped"\`, and use \`afterDetails\` to explain why (e.g. "IGNORE: drift score 0 — endpoint not modified in this PR"). Do **not** add entries for tests that were not returned by the health analysis.
+- **testMaintenance**: Use \`[]\` **only** if no existing Skyramp tests were found in the repository. If existing tests were found (any score), include one entry per test. Set \`action\` to the exact drift action you chose from the Action Decision Matrix (\`UPDATE\`, \`REGENERATE\`, \`DELETE\`, \`VERIFY\`, or \`IGNORE\`). For UPDATE/REGENERATE/DELETE tests that were modified and executed, populate \`beforeDetails\` and \`afterDetails\` from what you observed in \`skyramp_execute_test\` output — one line each, no newlines. For passing runs write the count and timing (e.g. \`"4 passed in 15.09s"\`). For failing runs write the test name and failure reason (e.g. \`"1 failed: test_foo - assert X == Y — shared-state pollution"\`). For VERIFY/IGNORE tests (not modified), omit \`beforeDetails\` and \`afterDetails\`. Do **not** add entries for tests that were not returned by the health analysis.
+- **testResults**: For UI/E2E test entries, include the \`videoPath\` field if \`skyramp_execute_test\` returned one.
 
 ---
 
 ${getTraceRecordingPromptText({ outputDir: `${repositoryPath}/.skyramp`, modularize: false })}`;
+    // TODO: merge stateFile and summaryOutputFile into a single file (follow-up PR).
+    // Currently the stateFile path is derived server-side from RUNNER_TEMP (GitHub Actions only);
+    // other CI systems (Jenkins, GitLab, Buildkite) require the caller to set RUNNER_TEMP.
+    // Once merged, the path flows through summaryOutputFile — already testbot-controlled and
+    // CI-agnostic — eliminating the RUNNER_TEMP dependency and the LLM confusion that motivated
+    // removing stateOutputFile from the prompt schema. Remove the RUNNER_TEMP branch in
+    // AnalysisStateManager.ts when this is done.
 }
 function escapeXml(value) {
     return value
@@ -578,10 +589,6 @@ export function registerTestbotPrompt(server) {
                 .string()
                 .optional()
                 .describe("Natural language prompt from the user (via @skyramp-testbot comment) to add or remove specific recommendations."),
-            stateOutputFile: z
-                .string()
-                .optional()
-                .describe("Absolute path where skyramp_analyze_changes should write its state file. When provided, the caller can locate the file without log parsing."),
             uiCredentials: z
                 .string()
                 .optional()
@@ -597,7 +604,7 @@ export function registerTestbotPrompt(server) {
         },
     }, async (args) => {
         const services = await readWorkspaceServices(args.repositoryPath);
-        let prompt = getTestbotPrompt(args.prTitle, args.prDescription, args.summaryOutputFile, args.repositoryPath, args.baseBranch, args.maxRecommendations, args.maxGenerate, args.maxCritical, args.prNumber, args.userPrompt, services.length ? services : undefined, args.stateOutputFile, args.uiCredentials, args.testsRepoDir);
+        let prompt = getTestbotPrompt(args.prTitle, args.prDescription, args.summaryOutputFile, args.repositoryPath, args.baseBranch, args.maxRecommendations, args.maxGenerate, args.maxCritical, args.prNumber, args.userPrompt, services.length ? services : undefined, args.uiCredentials, args.testsRepoDir);
         if (args.workspaceValidationFailed) {
             prompt = buildWorkspaceRecoveryPrefix(args.repositoryPath) + prompt;
         }

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

@@ -25,26 +25,6 @@ function callWithServices(services) {
     undefined, // userPrompt
     services);
 }
-function callWithStateOutputFile(stateOutputFile) {
-    return getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath, undefined, // baseBranch
-    undefined, // maxRecommendations
-    undefined, // maxGenerate
-    undefined, // maxCritical
-    undefined, // prNumber
-    undefined, // userPrompt
-    undefined, // services
-    stateOutputFile);
-}
-function callFollowUpWithStateOutputFile(stateOutputFile) {
-    return getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath, undefined, // baseBranch
-    undefined, // maxRecommendations
-    undefined, // maxGenerate
-    undefined, // maxCritical
-    undefined, // prNumber
-    "add more tests", // userPrompt — triggers follow-up path
-    undefined, // services
-    stateOutputFile);
-}
 describe("buildServiceContext (via getTestbotPrompt)", () => {
     it("renders full service with all fields", () => {
         const prompt = callWithServices([
@@ -122,27 +102,6 @@ describe("buildServiceContext (via getTestbotPrompt)", () => {
         expect(prompt).toContain("</REPOSITORY PATH>\nUse the Skyramp MCP server tools");
     });
 });
-describe("stateOutputFile in getTestbotPrompt", () => {
-    it("includes stateOutputFile in skyramp_analyze_changes call for first-run prompt", () => {
-        const stateFile = "/tmp/skyramp/analyze-changes-state.json";
-        const prompt = callWithStateOutputFile(stateFile);
-        // The prompt must pass stateOutputFile to skyramp_analyze_changes
-        expect(prompt).toContain(`\`stateOutputFile\`: "${stateFile}"`);
-    });
-    it("includes stateOutputFile in skyramp_analyze_changes call for follow-up prompt", () => {
-        const stateFile = "/tmp/skyramp/analyze-changes-state.json";
-        const prompt = callFollowUpWithStateOutputFile(stateFile);
-        expect(prompt).toContain(`\`stateOutputFile\`: "${stateFile}"`);
-    });
-    it("omits stateOutputFile from skyramp_analyze_changes call when not provided", () => {
-        const prompt = callWithStateOutputFile(undefined);
-        expect(prompt).not.toContain("stateOutputFile");
-    });
-    it("omits stateOutputFile from follow-up prompt when not provided", () => {
-        const prompt = callFollowUpWithStateOutputFile(undefined);
-        expect(prompt).not.toContain("stateOutputFile");
-    });
-});
 describe("uiCredentials in getTestbotPrompt", () => {
     function callWithUiCredentials(uiCredentials) {
         return getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath, undefined, // baseBranch
@@ -152,7 +111,6 @@ describe("uiCredentials in getTestbotPrompt", () => {
         undefined, // prNumber
         undefined, // userPrompt
         undefined, // services
-        undefined, // stateOutputFile
         uiCredentials);
     }
     // The instructions text references `<ui-credentials>` in prose (backticked);
@@ -261,7 +219,6 @@ describe("testsRepoDir in getTestbotPrompt", () => {
         undefined, // prNumber
         undefined, // userPrompt
         undefined, // services
-        undefined, // stateOutputFile
         undefined, // uiCredentials
         testsRepoDir);
     }
@@ -273,7 +230,6 @@ describe("testsRepoDir in getTestbotPrompt", () => {
         undefined, // prNumber
         "add more tests", // userPrompt — triggers follow-up path
         undefined, // services
-        undefined, // stateOutputFile
         undefined, // uiCredentials
         testsRepoDir);
     }

package/build/resources/sutSetupResource.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSutSetupResource(server: McpServer): void;

package/build/resources/sutSetupResource.js

@@ -0,0 +1,45 @@
+import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { logger } from "../utils/logger.js";
+import { resourceText } from "../utils/utils.js";
+import { AnalyticsService } from "../services/AnalyticsService.js";
+import { getAdaptWorkflowPrompt } from "../prompts/sut-setup/modes/adaptWorkflowPrompt.js";
+import { getDockerComposePrompt } from "../prompts/sut-setup/modes/dockerComposePrompt.js";
+import { SutSetupMode } from "../prompts/sut-setup/shared.js";
+export function registerSutSetupResource(server) {
+    logger.info("Registering SUT setup resource");
+    // RFC 6570 {+rest} (reserved expansion) captures the entire query string
+    // including the leading "?". This avoids the SDK's per-param regex which
+    // fails on empty query-param values.
+    const template = new ResourceTemplate("skyramp://prompts/skyramp_testbot_sut{+rest}", { list: undefined });
+    server.registerResource("skyramp_testbot_sut", template, {
+        title: "Skyramp Testbot SUT Setup",
+        description: "Returns mode-specific instructions for SUT (System Under Test) setup. " +
+            "Modes: none, adapt_workflow, docker_compose.",
+        mimeType: "text/plain",
+    }, async (uri) => {
+        const param = (name, fallback) => uri.searchParams.get(name) ?? fallback;
+        const mode = param("sutSetupMode", SutSetupMode.None);
+        const args = {
+            repositoryPath: param("repositoryPath", "."),
+            sutSetupMode: mode,
+            sutSourceWorkflowFile: param("sutSourceWorkflowFile", ""),
+            sutSourceDockerComposeFile: param("sutSourceDockerComposeFile", ""),
+        };
+        let prompt;
+        switch (mode) {
+            case SutSetupMode.AdaptWorkflow:
+                prompt = getAdaptWorkflowPrompt(args);
+                break;
+            case SutSetupMode.DockerCompose:
+                prompt = getDockerComposePrompt(args);
+                break;
+            case SutSetupMode.None:
+                prompt = "sutSetupMode is 'none'. No SUT setup required.";
+                break;
+            default:
+                prompt = `Unknown SUT setup mode: '${mode}'. Valid modes: none, adapt_workflow, docker_compose.`;
+        }
+        AnalyticsService.pushMCPToolEvent("skyramp_testbot_sut_resource", undefined, { mode }).catch(() => { });
+        return resourceText(uri.toString(), prompt);
+    });
+}

package/build/resources/testbotResource.js

@@ -25,7 +25,7 @@ export function registerTestbotResource(server) {
         const maxCrit = parseInt(uri.searchParams.get("maxCritical") || "", 10);
         const repositoryPath = param("repositoryPath", ".");
         const services = await readWorkspaceServices(repositoryPath);
-        const prompt = getTestbotPrompt(param("prTitle", ""), param("prDescription", ""), param("summaryOutputFile", ""), repositoryPath, uri.searchParams.get("baseBranch") || undefined, isNaN(maxRec) ? MAX_RECOMMENDATIONS : maxRec, isNaN(maxGen) ? MAX_TESTS_TO_GENERATE : maxGen, isNaN(maxCrit) ? MAX_CRITICAL_TESTS : maxCrit, isNaN(prNum) ? undefined : prNum, uri.searchParams.get("userPrompt") || undefined, services.length ? services : undefined, uri.searchParams.get("stateOutputFile") || undefined, uri.searchParams.get("uiCredentials") || undefined, uri.searchParams.get("testsRepoDir") || undefined);
+        const prompt = getTestbotPrompt(param("prTitle", ""), param("prDescription", ""), param("summaryOutputFile", ""), repositoryPath, uri.searchParams.get("baseBranch") || undefined, isNaN(maxRec) ? MAX_RECOMMENDATIONS : maxRec, isNaN(maxGen) ? MAX_TESTS_TO_GENERATE : maxGen, isNaN(maxCrit) ? MAX_CRITICAL_TESTS : maxCrit, isNaN(prNum) ? undefined : prNum, uri.searchParams.get("userPrompt") || undefined, services.length ? services : undefined, uri.searchParams.get("uiCredentials") || undefined, uri.searchParams.get("testsRepoDir") || undefined);
         AnalyticsService.pushMCPToolEvent("skyramp_testbot_prompt", undefined, {}).catch(() => { });
         // Return the original URI — clients may use it to re-fetch the resource,
         // and the caller already has these params. Credentials never appear in

package/build/services/TestDiscoveryService.d.ts

@@ -46,8 +46,8 @@ export declare class TestDiscoveryService {
      */
     private scoreRelevance;
     /**
-     * Partition external test files into relevant (score > 0) and low-relevance (score = 0)
-     * based on file path/name overlap with the changed resource names from the PR diff.
+     * Partition external test files into relevant (score > 0) and low-relevance (score = 0).
+     * Signal: path/name token overlap with changedResources.
      */
     private partitionByRelevance;
     /**

package/build/services/TestDiscoveryService.js

@@ -102,9 +102,7 @@ export class TestDiscoveryService {
                 this.partitionByRelevance(classified.external, changedResources));
         }
         else if (changedResources !== undefined) {
-            // PR mode with an explicit empty endpoint list from diff parsing — don't flood
-            // context with irrelevant external tests. The LLM will work from Skyramp tests
-            // and scanned endpoints only.
+            // PR mode with no path-resolvable endpoints — no path-based scoring available.
             relevantExternal = [];
             otherExternal = [];
         }
@@ -151,27 +149,39 @@ export class TestDiscoveryService {
         // Use the last two path segments to avoid false matches from deeply-nested dirs
         const segments = normalized.split("/").slice(-2).join("/");
         const tokens = new Set(segments.split(/[/\-_.]+/).filter(Boolean));
+        // Expand tokens with plural/singular variants so "deployment" matches
+        // "deployments" and vice versa. Only strip trailing "s" when the result
+        // is ≥4 chars (avoids "pas"→"pa") and doesn't end in "ss" (avoids "pass"→"pas").
+        const expanded = new Set(tokens);
+        for (const t of tokens) {
+            if (t.endsWith("s") && !t.endsWith("ss") && t.length > 4)
+                expanded.add(t.slice(0, -1));
+            else if (!t.endsWith("s"))
+                expanded.add(t + "s");
+        }
         return changedResources.filter(r => {
             const rLower = r.toLowerCase();
-            // Direct single-token match (e.g. "orders" in file path tokens)
-            if (tokens.has(rLower))
+            if (expanded.has(rLower))
                 return true;
-            // Compound resource names (e.g. "order-items" from /api/order-items) — check
-            // that ALL hyphen/underscore-separated parts appear as individual tokens.
-            // This handles test_order_items.py correctly matching resource "order-items".
+            // Compound resource names (e.g. "order-items") — all parts must appear as tokens.
             const parts = rLower.split(/[-_]/);
-            return parts.length > 1 && parts.every(p => p.length >= 3 && tokens.has(p));
+            return parts.length > 1 && parts.every(p => p.length >= 3 && expanded.has(p));
         }).length;
     }
     /**
-     * Partition external test files into relevant (score > 0) and low-relevance (score = 0)
-     * based on file path/name overlap with the changed resource names from the PR diff.
+     * Partition external test files into relevant (score > 0) and low-relevance (score = 0).
+     * Signal: path/name token overlap with changedResources.
      */
     partitionByRelevance(files, changedResources) {
         const relevant = [];
         const other = [];
         for (const f of files) {
-            (this.scoreRelevance(f, changedResources) > 0 ? relevant : other).push(f);
+            if (this.scoreRelevance(f, changedResources) > 0) {
+                relevant.push(f);
+            }
+            else {
+                other.push(f);
+            }
         }
         return { relevant, other };
     }

package/build/services/TestExecutionService.d.ts

@@ -3,6 +3,15 @@ export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.28";
 export declare const PLAYWRIGHT_CONFIG_FILES: string[];
 export declare const EXCLUDED_MOUNT_ITEMS: string[];
 export declare const MOUNT_NULL_ITEMS: string[];
+/**
+ * Check if a test type requires browser execution (UI/E2E)
+ */
+export declare function isBrowserTest(testType: string): boolean;
+/**
+ * Generate a deterministic unique subdirectory name for video output
+ * based on the test file path
+ */
+export declare function getVideoSubdir(testFile: string): string;
 /**
  * Detect session file paths referenced in test files
  * Looks for storageState patterns in TypeScript/JavaScript/Python/Java/C# test files