@skyramp/mcp 0.2.8 → 0.2.10-rc.1

package/build/index.js

@@ -59,13 +59,6 @@ const server = new McpServer({
     },
     instructions: `Skyramp MCP Server — generates and executes API tests (fuzz, contract, integration, E2E, UI).
 
-## Workspace Initialization (REQUIRED before the first Skyramp tool call)
-If the workspace root is a git repo AND \`.skyramp/workspace.yml\` does not exist:
-1. Call \`skyramp_init_scan\` with \`workspacePath\` → follow the returned instructions to discover all services.
-2. Call \`skyramp_init_workspace\` with \`workspacePath\`, \`services\`, and the \`scanToken\` from step 1.
-3. Proceed with the originally requested tool.
-Skip only if: not a git repo, \`.skyramp/workspace.yml\` already exists, or user explicitly declines.
-  
 ## Rules
 - NEVER show CLI commands. NEVER attempt to install or configure the Skyramp CLI. ALWAYS use the MCP tools provided.
 - For UI and E2E tests, there are TWO recording modes:
@@ -103,7 +96,7 @@ Before calling ANY test generation tool, you MUST follow this flow:
 4. **CRITICAL — endpointURL**: The \`endpointURL\` parameter MUST be the full URL to the specific endpoint being tested, NOT just the base URL. Construct it by combining \`api.baseUrl\` with the endpoint path. Example: if \`api.baseUrl\` is \`http://localhost:8000\` and the endpoint is \`/api/v1/products\`, pass \`endpointURL: "http://localhost:8000/api/v1/products"\`. NEVER pass just the base URL (e.g. \`http://localhost:8000\`) as \`endpointURL\`.
 5. **CRITICAL — scenario generation**: When calling \`skyramp_batch_scenario_test_generation\`, ALWAYS pass:
    - \`baseURL\`: The full base URL from \`api.baseUrl\` (e.g., \`http://localhost:3000\`). This determines the scheme, host, and port in the generated trace. Without it, the trace defaults to https:443 which is almost always wrong for local development.
-   - \`authHeader\`: Which HTTP header carries the auth credential. Get it from \`api.authHeader\` in workspace config. Examples: \`Authorization\` (Bearer/Token auth), \`X-Api-Key\` (API key auth), \`Cookie\` (session/cookie auth like NextAuth). Pass \`""\` to skip auth entirely (unauthenticated endpoints or \`api.authType: "none"\`).
+   - \`authHeader\`: Which HTTP header carries the auth credential. Get it from \`api.authHeader\` in workspace config. Examples: \`Authorization\` (Bearer/Token auth), \`X-Api-Key\` (API key auth), \`Cookie\` (session/cookie auth like NextAuth). Pass \`""\` to document the endpoint as unauthenticated in the generated test's assertions (unauthenticated endpoints or \`api.authType: "none"\`).
    - \`authScheme\`: Only when \`authHeader\` is \`Authorization\`. The prefix before the token (e.g., \`"Bearer"\` → \`Authorization: Bearer <token>\`). **Derive from**: (1) OpenAPI spec \`securitySchemes\`/\`securityDefinitions\`, (2) source code auth middleware, (3) workspace \`api.authType\`. **Do NOT guess.**
    - \`authToken\`: The full header value, used verbatim. When omitted, \`SKYRAMP_PLACEHOLDER_TOKEN\` is auto-generated. Only provide when the header needs a specific format (e.g., \`"session=${AUTH_PLACEHOLDER_TOKEN}"\` for Cookie). **Do NOT fabricate token values.**
    - \`apiSchema\` is OPTIONAL — omit it for code-first apps without OpenAPI specs.

package/build/prompts/enhance-assertions/uiAssertionsPrompt.js

@@ -4,6 +4,33 @@ const UI_ASSERTION_CATEGORIES = [
     {
         name: "Critical UI Assertions",
         rules: [
+            {
+                title: "Exercise the changed interaction (dynamic behavior)",
+                description: "When the PR introduces or changes interactive behavior (toggle, theme switch, expand/collapse, dialog open/close, focus management, optimistic update), the test MUST perform the triggering action and assert BOTH the state before AND after the action — not only the default or resting state. WHY: the PR's change IS the transition; a test that asserts only the initial/resting state would still pass even if the interaction were completely broken, so it gives zero coverage of what changed. If the test asserts only the resting state, add the action that triggers the change and assert the resulting transition — never mark this not applicable merely because the generated test lacks an action.",
+                subPoints: [
+                    "Toggle / switch: click the control and assert the observable flips (e.g. data-theme 'light' -> 'dark'), then click again and assert it reverses.",
+                    "Dialog / modal: open it and assert focus moves into the dialog; close via ESC or Cancel and assert focus returns to the trigger.",
+                    "The after-state must differ from the before-state — a single assertion of the unchanged default value does not verify the change.",
+                ],
+                examples: [
+                    {
+                        language: "javascript",
+                        code: `await expect(page.locator('html')).toHaveAttribute('data-theme', 'light');
+await page.getByTestId('theme-toggle').click();
+await expect(page.locator('html')).toHaveAttribute('data-theme', 'dark');`,
+                    },
+                    {
+                        // Python (playwright-python) — same before/after transition pattern
+                        language: "python",
+                        code: `trigger = page.get_by_test_id('delete-recipe')
+trigger.click()
+expect(page.get_by_role('dialog')).to_be_focused()
+page.keyboard.press('Escape')
+# focus returns to the trigger
+expect(trigger).to_be_focused()`,
+                    },
+                ],
+            },
             {
                 title: "Selector constraints",
                 description: "Every assertion uses a selector already in the file. Never invent `data-testid`, role names, or classes.",
@@ -240,7 +267,7 @@ Before editing the given test file, you must output a \`<thinking>\` block. The
 3. Classify each in-scope action / selector / captured response by its applicable assertion category, marking each category APPLICABLE or NOT APPLICABLE.
    - Critical UI Assertions applies when there is a collection / repeated element (\`toHaveCount\`), a pageerror handler, a captured network response, a negative-only or URL-only test needing a positive-path companion, or a tautological locator-by-text + assert-text to replace.
    - Computed Values applies when there is a knowable exact text / value / attribute, including a definition-page displayed value or an image \`src\`.
-   - Post-edit State applies only when the test contains a state-changing action (form fill+submit, save / delete / create / toggle, checkbox click, hover / mouseout, refresh, reload, JS update, form edit); otherwise NOT APPLICABLE.
+   - Post-edit State applies whenever EITHER (a) the test contains a state-changing action (form fill+submit, save / delete / create / toggle, checkbox click, hover / mouseout, refresh, reload, JS update, form edit), OR (b) the PR changes interactive behavior — in case (b), add the triggering action and assert the before/after transition (see "Exercise the changed interaction"). Mark NOT APPLICABLE only when the PR changes no interactive behavior and the test has no state-changing action.
 4. For each in-scope item, output one JSON object using the template below. The output is an array — repeat the object template below once per in-scope item.
    - \`action_or_selector_or_response\`: the selector, action, or captured network response this entry covers.
    - \`assertion_categories\`: an object that MUST contain every category name below as a key. The value of each category is itself an object that MUST contain every rule title under that category as a key. For each rule, the value is an array of assertion lines you will add for this item under that rule. Use \`[]\` only when the rule does not apply to this item — every category key and every rule key must still be present. This forces you to consider every rule for every item.

package/build/prompts/initialize-workspace/initializeWorkspacePrompt.js

@@ -97,6 +97,7 @@ Create one service entry per deployable unit. You MUST include every backend/API
 <api_fields>
 1. api.schemaPath: Path or URL to an OpenAPI or Swagger schema. Search for openapi.json, openapi.yaml, swagger.json, or swagger.yaml files. Framework defaults are: FastAPI serves /openapi.json, Express serves /api-docs, and Spring serves /v3/api-docs. For locally-run services, use a localhost URL. For cloud or externally hosted services (such as Salesforce, Vercel, or Cloudflare), use the actual deployment URL found in config or documentation.
 2. api.baseUrl (required): The base URL where the service is reachable, such as "http://localhost:3000" or "https://api.example.com". Derive from docker-compose ports, app config, README, or environment variables. Use localhost for services run locally and the actual deployment URL for cloud or externally hosted services. NEVER fabricate a URL. Only use URLs found in config files, README, or environment variables.
+   Include the API path prefix (e.g. \`/api\`, \`/api/v1\`, \`/v1\`) when one applies — not just \`host:port\`. A bare host means every test request hits the root and 404s. Derive the prefix from the strongest available signal: OpenAPI \`servers[].url\` or \`basePath\`; the app's routing config (FastAPI \`root_path\`, Express \`app.use('/api/v1', ...)\`, Rails routes prefix, Django \`urlpatterns\` mount); or the longest common leading path across the existing test suite's endpoints. If none of those yield a prefix, leave it bare AND flag it in your summary so the user can review.
 3. api.authType (required): The authentication type. Valid values are: ${AUTH_TYPES_PROMPT_LIST}
    Detect by checking in the following order (language-agnostic, apply whichever signals match):
    a. Dependencies and packages (package.json, requirements.txt, go.mod, Gemfile, composer.json, pom.xml, build.gradle):

package/build/prompts/personas.d.ts

@@ -1,7 +1,7 @@
 /**
  * Skyramp personas injected into tool descriptions and prompts.
  *
- * In TestBot environments (SKYRAMP_FEATURE_TESTBOT=1), the persona is injected
+ * In Testbot environments (SKYRAMP_FEATURE_TESTBOT=1), the persona is injected
  * once via `claude --append-system-prompt` from the testbot GitHub Action
  * (see testbot.git `src/agents/claude.ts` `loadQaPersona()`) rather than
  * repeating it in every tool description. In that case getPersonaPrefix()
@@ -14,7 +14,7 @@
 export declare const SKYRAMP_QA_PERSONA = "You are acting as a Skyramp QA Automation Engineer. Your responsibility is to translate user test intent into precise, deterministic test artifacts \u2014 whether generating API tests from specs, recording browser interactions for UI flows, or maintaining existing test suites. Derive all parameters strictly from the codebase, workspace config, API schemas, and page snapshots. Never guess or hallucinate values.";
 /**
  * Returns the persona prefix for use in tool descriptions.
- * Returns an empty string when running inside TestBot — the testbot action
+ * Returns an empty string when running inside Testbot — the testbot action
  * appends the persona via `claude --append-system-prompt` instead, so we
  * avoid duplicating it in every tool description.
  */

package/build/prompts/personas.js

@@ -2,7 +2,7 @@ import { isTestbotEnabled } from "../utils/featureFlags.js";
 /**
  * Skyramp personas injected into tool descriptions and prompts.
  *
- * In TestBot environments (SKYRAMP_FEATURE_TESTBOT=1), the persona is injected
+ * In Testbot environments (SKYRAMP_FEATURE_TESTBOT=1), the persona is injected
  * once via `claude --append-system-prompt` from the testbot GitHub Action
  * (see testbot.git `src/agents/claude.ts` `loadQaPersona()`) rather than
  * repeating it in every tool description. In that case getPersonaPrefix()
@@ -15,7 +15,7 @@ import { isTestbotEnabled } from "../utils/featureFlags.js";
 export const SKYRAMP_QA_PERSONA = `You are acting as a Skyramp QA Automation Engineer. Your responsibility is to translate user test intent into precise, deterministic test artifacts — whether generating API tests from specs, recording browser interactions for UI flows, or maintaining existing test suites. Derive all parameters strictly from the codebase, workspace config, API schemas, and page snapshots. Never guess or hallucinate values.`;
 /**
  * Returns the persona prefix for use in tool descriptions.
- * Returns an empty string when running inside TestBot — the testbot action
+ * Returns an empty string when running inside Testbot — the testbot action
  * appends the persona via `claude --append-system-prompt` instead, so we
  * avoid duplicating it in every tool description.
  */

package/build/prompts/sut-setup/modes/adaptWorkflowPrompt.js

@@ -1,4 +1,4 @@
-import { TESTBOT_WORKFLOW_PATH, buildContextBlock, buildCommonSutErrorsSection, buildLocalValidationSection, buildInputsBody, buildSutDefinitionBlock, } from "../shared.js";
+import { TESTBOT_WORKFLOW_PATH, buildContextBlock, buildCommonSutErrorsSection, buildLocalValidationSection, buildInputsBody, buildSeedDataDiscoverySection, buildSutDefinitionBlock, buildWorkspaceInitSection, } from "../shared.js";
 import { getPersonaPrefix } from "../../personas.js";
 import { PromptPlan } from "../../test-recommendation/promptPlan.js";
 // ── Step body builders ────────────────────────────────────────────────────────
@@ -70,6 +70,7 @@ function buildAdaptRestrictionsBody() {
 // ── PromptPlan declaration ────────────────────────────────────────────────────
 const _adaptPlan = new PromptPlan()
     .addPhase("adapt", "", { headerLevel: "hidden", stepFormat: "hash" })
+    .step("INIT_WORKSPACE", "Initialise the Skyramp workspace file", () => buildWorkspaceInitSection())
     .step("SCAN", "Understand the System Under Test in this repository", () => "")
     .subStep("READ_SOURCES", "Read workflows and infra files", buildReadSourcesBody)
     .subStep("CLASSIFY_STEPS", "Classify source workflow steps", buildClassifyStepsBody)
@@ -80,6 +81,7 @@ const _adaptPlan = new PromptPlan()
     .subStep("PATTERN_C", "Pattern C — GHA steps replace service startup + Testbot lifecycle validation", buildPatternCBody)
     .subStep("PATTERN_D", "Pattern D — Fully wrapped by GHA steps", buildPatternDBody)
     .step("INPUTS", "Plan the Testbot action inputs", () => buildInputsBody())
+    .step("SEED_DATA", "Discover database seed-data conventions", () => buildSeedDataDiscoverySection())
     .step("ADAPT", "Edit the Testbot workflow and generate SUT files", () => "")
     .subStep("EDIT_WORKFLOW", "Edit the workflow file", buildEditWorkflowBody)
     .subStep("CONFIGURE_AUTH", "Configure auth", buildConfigureAuthBody)

package/build/prompts/sut-setup/modes/dockerComposePrompt.js

@@ -1,4 +1,4 @@
-import { buildContextBlock, buildInputsBody, buildCommonSutErrorsSection, buildLocalValidationSection, buildSutDefinitionBlock, } from "../shared.js";
+import { buildContextBlock, buildInputsBody, buildCommonSutErrorsSection, buildLocalValidationSection, buildSeedDataDiscoverySection, buildSutDefinitionBlock, buildWorkspaceInitSection, } from "../shared.js";
 import { getPersonaPrefix } from "../../personas.js";
 import { PromptPlan } from "../../test-recommendation/promptPlan.js";
 // ── Step body builders ────────────────────────────────────────────────────────
@@ -93,6 +93,9 @@ Steps:
    - The \`--project-directory .\` means build context is the repository root (NOT .skyramp/sut/)
    - Healthchecks for ALL services (testbot relies on \`--wait\`)
    - Simple testbot credentials in environment (admin@testbot.com / testbot)
+   - Never paste cryptographic material into the \`environment:\` section of the compose file. This rule covers RSA and EC private keys, PEM blobs, JWK JSON, OAuth client secrets, and any other signing keypair. In practice, refuse anything that looks like a PEM block (text starting with \`-----BEGIN \` followed by \`PRIVATE KEY\`, \`RSA PRIVATE KEY\`, \`EC PRIVATE KEY\`, \`OPENSSH PRIVATE KEY\`, or \`ENCRYPTED PRIVATE KEY\` and the matching \`-----\`), a JWK in base64url-encoded JSON form (strings starting with \`eyJrdHkiOi\`, which decodes to \`{"kty":\`), or any base64 string longer than about 200 characters that looks like a key. The compose file is committed to the customer's repository, so anything written here lands in their PR diff and stays in git history — including the private half of any keypair. Two cases to handle:
+     1. **Symmetric secrets** — when the app accepts a plain string (\`JWT_SECRET\`, \`SESSION_SECRET\`, signing salts, HMAC keys), use a clearly-marked dummy literal so a code reviewer immediately recognizes it as fake. For example: \`JWT_SECRET: "testbot-dummy-do-not-use-in-production"\`.
+     2. **Asymmetric keys** — when the app requires a real keypair (RS256 JWT signing, gRPC TLS, signing keypairs), do not commit the keys. Instead, generate them inside the container at startup so they exist only for the container's lifetime. First look at the app's source or config to determine what format it expects: PEM, JWK, or raw base64. Then override the service's \`entrypoint\` with a short script that generates a keypair in that format, exports the key bodies into the env vars the app reads, and finally \`exec\`s the app's original command. Pick the tool that matches the format: \`openssl genpkey\` for PEM, \`python -m jwcrypto\` / \`node -e "require('jose')..."\` / \`step crypto jwk create\` for JWK, \`openssl rand -base64\` for a raw secret. Prefer a tool that already exists in the app's runtime image — for instance, a Django service usually has \`jwcrypto\` or \`josepy\` installed already — rather than installing one at startup. Testbot fetches its bearer token via \`get-auth-token.sh\`, which calls the app's login endpoint; the app signs the token with its in-container private key and returns it as an opaque string. The test client never reads the private key directly, so per-container ephemeral keys are enough — no GitHub repo secrets, no out-of-band key sharing.
    - Generous \`start_period\` (30-120s) for CI cold builds
    - For monorepos: may need a builder service that runs first
 
@@ -260,9 +263,11 @@ ${GENERATE_DOCKER_COMPOSE_INSTRUCTIONS}`;
 // ── PromptPlan declaration ────────────────────────────────────────────────────
 const _composePlan = new PromptPlan()
     .addPhase("compose", "", { headerLevel: "hidden", stepFormat: "hash" })
+    .step("INIT_WORKSPACE", "Initialise the Skyramp workspace file", () => buildWorkspaceInitSection())
     .step("SCAN", "Understand the System Under Test in this repository", buildScanComposeBody)
     .step("DECIDE", "Decide SUT setup strategy", buildDecideStrategyBody)
     .step("INPUTS", "Plan the Testbot action inputs", () => buildInputsBody())
+    .step("SEED_DATA", "Discover database seed-data conventions", () => buildSeedDataDiscoverySection())
     .step("BUILD", "Edit the Testbot workflow and generate SUT files", () => "")
     .subStep("PR_ACCURATE", "Build PR-accurate SUT", buildPrAccurateSutSection)
     .subStep("APPLY", "Apply the chosen strategy", buildApplyStrategyBody)

package/build/prompts/sut-setup/shared.d.ts

@@ -21,6 +21,26 @@ export interface SutPromptArgs {
  */
 export declare function buildSutDefinitionBlock(): string;
 export declare function buildContextBlock(args: SutPromptArgs): string;
+/**
+ * Seed-data discovery block — rendered as a SUT-bootstrap step so the agent
+ * looks for existing customer seed conventions BEFORE inventing new ones.
+ * A fresh database makes list / search / filter / pagination endpoint tests
+ * shallow (only HTTP-status assertable, never response content), which
+ * collapses the data-diversity dimension of the eval. Most repos already
+ * have a seed mechanism — wire that in instead of generating one.
+ *
+ * Rendered as a top-level PromptPlan step between INPUTS and the
+ * ADAPT/BUILD step in every SUT setup mode.
+ */
+export declare function buildSeedDataDiscoverySection(): string;
+/**
+ * Workspace file initialisation block — rendered as the first instruction
+ * in every SUT setup mode, before any local validation, workflow editing,
+ * or SUT-file generation. Seeds `.skyramp/workspace.yml` with the service
+ * inventory so testbot's SUT autocommit picks it up alongside the
+ * generated `.skyramp/sut/*` files.
+ */
+export declare function buildWorkspaceInitSection(): string;
 export declare function buildLocalValidationSection(): string;
 /**
  * Returns the canonical "add to the Testbot workflow" block: every input that

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

@@ -31,6 +31,57 @@ export function buildContextBlock(args) {
     lines.push(`</context>`);
     return lines.join("\n");
 }
+/**
+ * Seed-data discovery block — rendered as a SUT-bootstrap step so the agent
+ * looks for existing customer seed conventions BEFORE inventing new ones.
+ * A fresh database makes list / search / filter / pagination endpoint tests
+ * shallow (only HTTP-status assertable, never response content), which
+ * collapses the data-diversity dimension of the eval. Most repos already
+ * have a seed mechanism — wire that in instead of generating one.
+ *
+ * Rendered as a top-level PromptPlan step between INPUTS and the
+ * ADAPT/BUILD step in every SUT setup mode.
+ */
+export function buildSeedDataDiscoverySection() {
+    return `**First, decide if this step applies.** Skip it entirely (in your summary state \`SEED_DATA: N/A — <reason>\`, naming the specific bullet below that applied — e.g. "no stateful service", "no list endpoints in scope", "already seeded by init container") and move on when ANY of the following is true:
+- The SUT has no database / stateful service (it's a pure stateless API, a static asset server, a webhook receiver, etc.).
+- The compose stack contains no database container (no \`postgres\`, \`mysql\`, \`mariadb\`, \`mongodb\`, \`redis\` as the primary store, \`sqlite\`, etc.) and no application-managed persistent store.
+- The PR diff and the existing test surface focus exclusively on auth, single-resource CRUD (POST/GET-one/PUT/DELETE on \`/foo/{id}\`), or compute endpoints — no list / search / filter / pagination / aggregate endpoints will be exercised.
+- You can confirm from the SCAN step's findings that representative records already exist (e.g. seeded by an init container, by a migration, or by the auth/setup flow you already wired).
+
+Only proceed with the rest of this step when the SUT has a database AND the tests will exercise list/search/filter/pagination endpoints. Otherwise an empty database is acceptable and inventing seed data adds noise.
+
+When this step DOES apply: database services usually start empty in CI, so tests against list / search / filter / pagination endpoints will then only see \`[]\` and can assert nothing beyond HTTP status — a low data-diversity outcome. Look for an existing seeding mechanism in the repo and wire it into the SUT bootstrap.
+
+**Discover existing project conventions first** — most repos already have one of:
+1. A named script: \`scripts/seed*\`, \`db/seeds/*\`, \`prisma/seed.{ts,js}\`, \`apps/api/seed/*\`, \`tests/fixtures/seed*\`. Search: \`find . -iname '*seed*' -not -path '*/node_modules/*' -not -path '*/.git/*'\`.
+2. A package.json / Makefile target: \`npm run seed\`, \`npm run db:seed\`, \`pnpm seed\`, \`yarn seed\`, \`make seed\`, \`make fixtures\`. Check \`package.json\` \`scripts\` and the project's \`Makefile\`.
+3. A migration with sample data: Django \`loaddata\`, Rails \`db:seed\`, Knex \`seed:run\`, Prisma \`db seed\`, Alembic data migrations.
+4. A docker-compose init service: existing compose files sometimes have a \`*-seed\`, \`*-fixtures\`, or \`init-*\` service that runs once on bring-up.
+
+**Wire it in:**
+- **Compose init service** — add it (or its dependency) to the testbot compose so \`targetSetupCommand\` brings it up alongside the rest. Use \`depends_on\` with \`condition: service_completed_successfully\` on dependent services so they only start after seeding finishes.
+- **Script needing an admin/API token** (most common) — chain it INTO \`authTokenCommand\` AFTER the token is created and BEFORE the script prints the token to stdout. Route seed stdout/stderr to stderr so the captured token isn't corrupted. Make the seed call best-effort (\`|| echo "seed failed" >&2\`) so a flaky seed doesn't block the run — the token is still returned and PRs whose tests don't need seed data keep working.
+- **Migration with sample data** — ensure the migration runs as part of \`targetSetupCommand\` (some ORMs auto-run on container start, others need an explicit \`migrate\` / \`db:seed\` step before tests can hit the API).
+
+**If NO existing convention is found**, generate a minimal seed step (≥3 entities per primary resource the tests will query, e.g., ≥3 repos / ≥3 issues / ≥3 users for a forge; ≥3 products / ≥3 orders for a shop). Call this out explicitly in your summary so the user knows a richer fixture may be needed for production-quality tests.
+
+**Never** hard-code production data, real customer credentials, or PII in seeds. Seed identifiers should be obviously test-only (\`acme-co\`, \`alpha-svc\`, \`testbot-admin\`).`;
+}
+/**
+ * Workspace file initialisation block — rendered as the first instruction
+ * in every SUT setup mode, before any local validation, workflow editing,
+ * or SUT-file generation. Seeds `.skyramp/workspace.yml` with the service
+ * inventory so testbot's SUT autocommit picks it up alongside the
+ * generated `.skyramp/sut/*` files.
+ */
+export function buildWorkspaceInitSection() {
+    return `Before generating any SUT setup files, check whether \`.skyramp/workspace.yml\` exists at the root of the repository being bootstrapped (the path shown next to "Repository path:" in the context block above — the repo whose PR triggered Testbot; in multi-repo runs this is the primary repo, not the sibling repos checked out as related repos). If it doesn't:
+1. Call \`skyramp_init_scan\` with \`workspacePath\` set to that repository root → follow the returned instructions to discover all services.
+2. Call \`skyramp_init_workspace\` with the same \`workspacePath\`, \`services\`, and the \`scanToken\` from step 1.
+
+Later steps in this SUT bootstrap run write \`.skyramp/sut/*\` files alongside the workspace file. If you need to update per-service \`runtimeDetails.serverStartCommand\` to match the new SUT files, call \`skyramp_init_workspace\` again with \`force: true\` and the full updated services array — never use Edit/Write directly on \`.skyramp/workspace.yml\`. See the \`skyramp_init_workspace\` tool description for the edit-mode contract.`;
+}
 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.
@@ -39,7 +90,7 @@ Run commands one at a time in your shell — individual execution pinpoints fail
    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.
+   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\`, prune docker BuildKit cache and dangling images before the next build (keep the running stack intact). Skipping this on heavy SUTs exhausts the standard runner 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.
@@ -68,8 +119,16 @@ Target lifecycle inputs (control how Testbot starts, validates, and stops the SU
    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.
+2. \`targetReadyCheckCommand\` — polling command Testbot runs repeatedly after setup until it exits 0 (service ready) or the timeout fires.
+   a. **CRITICAL: must cover EVERY service the tests will hit, not just the backend.** Chain checks with \`&&\` so the command exits 0 only when ALL services respond. A single-service check on a multi-service SUT is the leading cause of "element not visible" / "heading not visible" UI test failures — Playwright lands on a partially-rendered page because only the API was up when the gate passed. Inventory of services to include:
+      - Every API service in workspace.yml with an \`api.baseUrl\` → curl an unauthenticated endpoint (health / version / status).
+      - Every UI service with a UI \`baseUrl\` (or a frontend port in compose) → curl \`/\` or a known asset like \`/assets/index.js\` (more reliable than \`/\` for SPAs that hydrate lazily).
+      - Skip auth-required endpoints — they 401 before the SUT is testable and mask the readiness signal.
+      Examples:
+      - API only: \`curl -sf http://localhost:8080/api/health\`
+      - API + UI:  \`curl -sf http://localhost:8080/api/health && curl -sf http://localhost:3000/\`
+      Required in every pattern (explicit \`targetSetupCommand\`, the \`docker compose up -d\` default, AND \`skipTargetSetup: 'true'\`). Without a real readiness signal (neither this nor a workspace service \`baseUrl\`), testbot's fail-early gate throws \`Unable to verify service readiness\` 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.
+   b. Set \`targetReadyCheckDiagnosticsCommand\` to a command that explains why the SUT isn't healthy — output is surfaced in the failure PR comment when the ready check times out. For docker-compose SUTs, scope it to the project's compose file (container state + recent service logs). For non-docker SUTs, a tail of the server log.
 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).
@@ -89,19 +148,20 @@ Auth inputs (used by Testbot to authenticate against the running SUT during test
    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\`.
+9. \`runs-on\` runner label — leave whatever value the Testbot installer wrote and the source workflow used. Don't override it. Picking a runner SKU is an account-level decision that depends on provisioning the agent can't see from inside the repo; a wrong choice queues the job forever with no runner ever picking it up. If the SUT genuinely doesn't fit on the chosen runner, the disk-pressure mitigation in "Common failure modes" #9 handles it; an unprovisioned-runner stall does not.
 
 #### 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).
+4. Leave the existing \`runs-on\` value untouched (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.
+6. Stack-specific testability flags — some frameworks gate test-harness affordances behind a container env var. Common cases: Flutter web needs \`IS_TESTING=true\` so \`ensureSemantics()\` exposes the widget tree to Playwright (without it every selector finds nothing even though the app is up); some React/Angular builds need \`NODE_ENV\` / framework-specific build flags for \`testID\` propagation. Set these in the compose \`environment:\` block on the affected service (or as a \`Dockerfile ENV\`) — NOT as a shell var in \`targetSetupCommand\`. The var must be in the container's env at boot, not just the shell that runs the setup command. If selectors find nothing but the app is up, check for a missing flag like this first.
 
 #### 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.
+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. In case of multi-mode containers (\`Dockerfile.bdd\`, \`Dockerfile.e2e\`, \`Dockerfile.integration\`, \`Dockerfile.test\`), create the necessary file in \`.skyramp/sut/\` with a PR-sourced build (e.g. \`.skyramp/sut/Dockerfile.bdd\` referenced from the testbot compose's \`build:\`). Do not edit existing Dockerfiles or compose files in the repo. If the multi-mode container's bootstrap step depends on a seeded user, ensure SEED_DATA creates it before this container tries to log in.
 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.
@@ -127,6 +187,6 @@ export function buildCommonSutErrorsSection() {
 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.
+9. no_space_left — the runner ran out of disk space (\`No space left on device\`). Prune the docker BuildKit cache and dangling images at the start of both \`targetSetupCommand\` and \`targetTeardownCommand\` so each fix-loop retry begins with a clean slate; without it, cache from the previous attempt accumulates across retries on heavy SUTs. Do not change \`runs-on\` — see input 9 above.
 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/actionsInstructions.js

@@ -15,7 +15,11 @@ export function buildFileRenameStrategy() {
 }
 /** Strategy string for in-place UPDATE edits. */
 export function buildUpdateStrategy() {
-    return `For each file in update_context, apply the changes described in context. Preserve all existing test logic — only add or adjust what is described in context. After applying all edits, call skyramp_enhance_assertions with each updated file path.`;
+    return `For each file in update_context, apply the changes described in context. Preserve all existing test logic — only add or adjust what is described in context.
+
+UPDATE is an in-place edit to the existing baseline file — do not create a new test file to cover the same page or component.
+
+After applying all edits, call skyramp_enhance_assertions with each updated file path.`;
 }
 /** Strategy string for REGENERATE — call generation tool to overwrite the file. */
 export function buildRegenerateStrategy() {

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, repoPaths?: string[]): string;

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

@@ -1,6 +1,8 @@
 import { buildActionDecisionTree, buildCheckAdditiveFields, buildCheckEndpointExistence, buildCheckResponseShape, buildCheckAuthAndAuthorization, buildCheckBehavioralContract, buildCheckAssignAction, buildDriftOutputChecklist, } from "./driftAnalysisSections.js";
+import { buildUiActionDecisionTree, buildUiCheckRouteExistence, buildUiCheckSelectors, buildUiCheckPageObjects, buildUiCheckBehavioralChanges, buildUiCheckAssignAction, buildUiDriftOutputChecklist, } from "./uiDriftAnalysisSections.js";
+import { RECOMMENDATIONS_INSTRUCTION, buildSymbolDiscoveryStep } from "./driftAnalysisShared.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 +16,64 @@ 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_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, repoPaths) {
+    const parts = [];
+    // Emit symbol discovery once at the top regardless of how many sections follow.
+    // Placing it inside each plan's checklist caused duplication on mixed diffs.
+    const hasAnyTests = apiTests.length > 0 || (ui?.tests?.length ?? 0) > 0;
+    const discovery = buildSymbolDiscoveryStep(hasAnyTests, repoPaths);
+    if (discovery)
+        parts.push(discovery);
+    // 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, blueprintCaptured: ui.blueprintCaptured })}\n</ui_drift_analysis_rules>`);
+    }
+    parts.push(RECOMMENDATIONS_INSTRUCTION);
+    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.
@@ -213,7 +199,7 @@ To determine which applies: look at whether an explicit output layer (DTO, seria
 **Do not assign IGNORE because the field is optional or nullable** — "won't break existing assertions" is not the bar. The bar is "does the test now cover this endpoint's full contract?" A new field, even optional, means the contract changed and the test is incomplete.`;
 }
 export function buildDriftOutputChecklist(stateFile, existingTests) {
-    const finalStep = `Call \`skyramp_actions\` with \`stateFile: "${stateFile ?? "<stateFile>"}"\` and a \`recommendations\` entry for every test assessed.`;
+    const finalStep = `Call \`skyramp_actions\` with \`stateFile: "${stateFile ?? "<stateFile>"}"\`.`;
     const hasTests = (existingTests?.length ?? 0) > 0;
     const testList = hasTests
         ? existingTests.map((t) => {
@@ -224,9 +210,6 @@ 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}
@@ -257,9 +240,8 @@ 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.
-Be concise — one line per IGNORE/VERIFY entry.`;
-    const sections = [symbolDiscoveryStep, existingTestSection, finalStep].filter(Boolean);
+Be concise — one line per VERIFY/IGNORE entry.`;
+    const sections = [existingTestSection, finalStep];
     return `<output_format>
 Complete ALL of the following:
 

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

@@ -0,0 +1,20 @@
+/** Shared drift prompt sections (assign-action, external test policy, symbol discovery) for API and UI prompts. */
+/**
+ * Build the symbol-discovery grep instruction — unified for API and UI tests.
+ * Two-pass: hunk-context symbols (what changed) + full file exports (what exists),
+ * covering aliases, indirect renders, and shared hooks the diff doesn't mention.
+ */
+export declare function buildSymbolDiscoveryStep(hasTests: boolean, repoPaths?: string[]): string;
+/** One source of truth for the recommendations[] contract passed to skyramp_actions. */
+export declare const RECOMMENDATIONS_INSTRUCTION = "Pass VERIFY, UPDATE, REGENERATE, and DELETE entries to `recommendations[]`. Omit IGNORE.";
+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;