@skyramp/mcp 0.2.150-rc.ldw → 0.2.150-rc.ldw-4

package/build/commands/commandLibrary.d.ts

@@ -1,5 +1,4 @@
 import type { OneClickCommandId, OneClickCommandDef } from "../types/OneClickCommands.js";
-export declare function getCommand(id: OneClickCommandId): OneClickCommandDef;
 export declare function getAllCommands(): OneClickCommandDef[];
 export declare function getCommandIds(): OneClickCommandId[];
 /**

package/build/commands/commandLibrary.js

@@ -18,13 +18,6 @@ function getCommandLibrary() {
     }
     return commands;
 }
-export function getCommand(id) {
-    const cmd = getCommandLibrary()[id];
-    if (!cmd) {
-        throw new Error(`Unknown one-click command: ${id}`);
-    }
-    return cmd;
-}
 export function getAllCommands() {
     return Object.values(getCommandLibrary()).filter((cmd) => Boolean(cmd));
 }

package/build/commands/localDevTestChangesCommand.js

@@ -48,7 +48,7 @@ const localDevTestChangesSteps = [
 File to check/create only if the tool did not already install it:
 - Cursor: \`.cursor/skills/local-dev/SKILL.md\`
 - Claude Code: \`.claude/skills/local-dev/SKILL.md\`
-Agents without repo-local skill support skip skill creation. Also ensure the MCP config has the required env vars set (SKYRAMP_FEATURE_LOCAL_DEV=1 automatically enables contract consumer mode too).`,
+Agents without repo-local skill support skip skill creation. Also ensure the MCP config has the required env vars set (SKYRAMP_FEATURE_LOCAL_DEV=1).`,
         conditionalGuidance: `Create the skill file for the calling agent ONLY if it doesn't already exist — never overwrite.
 
 **Skill path for the calling agent only:**
@@ -65,7 +65,7 @@ ${LOCAL_DEV_SKILL_CONTENT}
 - For VS Code: add to the Skyramp MCP server's VS Code MCP config env block:
   \`"SKYRAMP_FEATURE_LOCAL_DEV": "1"\`
 
-Setting SKYRAMP_FEATURE_LOCAL_DEV=1 automatically enables consumer contract tests (no separate flag needed). After updating the config, the user must restart the IDE or reload MCP servers for the change to take effect.
+After updating the config, the user must restart the IDE or reload MCP servers for the change to take effect.
 
 After verifying or creating files, inform the user what was installed.`,
     },
@@ -85,7 +85,7 @@ After verifying or creating files, inform the user what was installed.`,
     {
         stepIndex: 2,
         title: "Invoke the skyramp_local_dev prompt",
-        description: "Call the `skyramp_local_dev` MCP prompt to run the full local-dev testing workflow.\n\nPass these parameters:\n- `baseCommit`: the one-click `baseBranch` value (default `main`)\n- `repositoryPath`: absolute path to the repo\n- `servicesToMock`: comma-separated list only when the user explicitly named services to mock\n- `realServices`: comma-separated list only when the user explicitly named services that should receive real traffic\n- `mockProtocols`: comma-separated list only when the user explicitly constrained mocked protocols (for example, `rest`)\n\nThe one-click tool exposes `baseBranch` because that matches other workflow inputs; the `skyramp_local_dev` prompt argument is named `baseCommit`. Always map `baseBranch` → `baseCommit` when invoking the prompt.\n\nThe workflow generates the highest-value tests regardless of type. For integration scenarios with selected downstream mocks: skyramp_mock_generation → skyramp_integration_test_generation → skyramp_enrich_test_with_mocks. For contract scenarios: skyramp_contract_test_generation only; do not enrich contract tests. Integration enrich is MANDATORY when the selected scenario has downstream mocks — it embeds MOCK_SERVICES into the test file.\n\nFollow the returned prompt instructions EXACTLY — do not skip steps or freelance.",
+        description: "Call the `skyramp_local_dev` MCP prompt to run the full local-dev testing workflow.\n\nPass these parameters:\n- `baseCommit`: the one-click `baseBranch` value (default `main`)\n- `repositoryPath`: absolute path to the repo\n- `servicesToMock`: comma-separated list only when the user explicitly named services to mock\n- `realServices`: comma-separated list only when the user explicitly named services that should receive real traffic\n- `mockProtocols`: comma-separated list only when the user explicitly constrained mocked protocols (for example, `rest`)\n\nThe one-click tool exposes `baseBranch` because that matches other workflow inputs; the `skyramp_local_dev` prompt argument is named `baseCommit`. Always map `baseBranch` → `baseCommit` when invoking the prompt.\n\nThe workflow generates the highest-value tests regardless of type. For integration scenarios with selected downstream mocks: skyramp_mock_generation → skyramp_integration_test_generation → skyramp_enrich_test_with_mocks. For provider contract scenarios: skyramp_contract_test_generation only; no mocks needed. Integration enrich is MANDATORY when the selected scenario has downstream mocks — it embeds MOCK_SERVICES into the test file.\n\nFollow the returned prompt instructions EXACTLY — do not skip steps or freelance.",
         conditionalGuidance: renderFallbackGuidance(),
     },
 ];
@@ -135,7 +135,7 @@ Read <REPOSITORY_PATH>/.skyramp/workspace.yml before classifying dependencies. U
 ## Key Principles
 - ALL output paths absolute inside repo. NEVER /tmp.
 - For **integration tests**: call \`skyramp_enrich_test_with_mocks\` after generating each test that uses selected downstream mocks. Each integration test with mocked dependencies MUST have MOCK_SERVICES embedded for third-party mocks or user-requested mocks.
-- For **contract tests**: mocks are wired inline by the generation tool — do NOT call \`skyramp_enrich_test_with_mocks\` for contract tests. Consumer contract tests already include \`client.apply_mock(mock)\` in the generated test function.
+- For **provider contract tests**: no mocks needed — test hits the real endpoint directly. Do NOT call \`skyramp_enrich_test_with_mocks\` for contract tests.
 - Prioritize tests that catch real bugs and edge cases; test type is secondary to coverage value.
 - Present results directly to the user (no skyramp_submit_report).
 - **Prefer batch operations**: Use \`skyramp_batch_mock_generation\` over individual mock calls.

package/build/index.js

@@ -37,6 +37,7 @@ import { registerOneClickTool } from "./tools/one-click/oneClickTool.js";
 import { registerEnrichTestWithMocksTool } from "./tools/enrichTestWithMocksTool.js";
 import { registerPreflightMockCheckTool } from "./tools/preflightMockCheckTool.js";
 import { registerGenerateEnrichedIntegrationTestTool } from "./tools/generateEnrichedIntegrationTestTool.js";
+import { registerLocalDevWorkerComposeTool } from "./tools/localDevWorkerComposeTool.js";
 import { registerAnalysisResources } from "./resources/analysisResources.js";
 import { registerProgressResource } from "./resources/progressResource.js";
 import { AnalyticsService } from "./services/AnalyticsService.js";
@@ -116,7 +117,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.
@@ -198,7 +199,7 @@ const infrastructureTools = [
     registerTraceStopTool,
 ];
 if (isLocalDevEnabled()) {
-    infrastructureTools.push(registerEnrichTestWithMocksTool, registerPreflightMockCheckTool, registerGenerateEnrichedIntegrationTestTool);
+    infrastructureTools.push(registerEnrichTestWithMocksTool, registerPreflightMockCheckTool, registerGenerateEnrichedIntegrationTestTool, registerLocalDevWorkerComposeTool);
     logger.info("Local-dev tools enabled via SKYRAMP_FEATURE_LOCAL_DEV");
 }
 if (isTestbotEnabled()) {

package/build/playwright/registerPlaywrightTools.js

@@ -57,6 +57,8 @@ export async function registerPlaywrightTools(server, options) {
         'browser_assert_table_cell',
         'browser_mouse_action',
         'browser_visual_snapshot',
+        'browser_gojs_add_node',
+        'browser_gojs_link',
         'skyramp_export_zip',
         'skyramp_load_trace',
         // DOM Analyzer: blueprint capture (capture-act-capture pattern)

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/local-dev/local-dev-plan.js

@@ -99,7 +99,6 @@ For each endpoint under test:
 
 5. **For API and downstream contracts**, include scenarios only when they catch a realistic bug:
    - Provider contract: response field added/renamed/removed, type/nullable mismatch, status-code semantic drift.
-   - Consumer contract: our code sends the wrong downstream request body/header/path, or parses a response field that may be missing/renamed.
 
 6. **For full API flows**, treat API E2E coverage as integration coverage:
    - **API full-flow coverage is integration coverage** in this workflow. Do NOT label API-only workflows as E2E.
@@ -122,9 +121,8 @@ For each endpoint under test:
 | 1 | Order creation applies downstream pricing rules | integration | happy-path-with-pricing | All required downstream success | 201 + calculated totals | high |
 | 2 | Payment rejection rolls back order creation | integration | payment-rejects | Payment service → 422 | expected error + no persisted order | high |
 | 3 | Public order response shape does not regress | provider-contract | order-response-shape | N/A | required fields typed | medium |
-| 4 | Payment request shape remains compatible | consumer-contract | payment-request-shape | N/A | validates request body + parses response | medium |
-| 5 | Complete API order workflow remains coherent | integration | order-creation-full-flow | All downstreams for the cross-service workflow | final response + side effects observed | high |
-| 6 | Frontend checkout flow still works after UI changes | ui | checkout-ui-flow | Browser trace + applicable API mocks | visible success/error state | high when frontend changed |
+| 4 | Complete API order workflow remains coherent | integration | order-creation-full-flow | All downstreams for the cross-service workflow | final response + side effects observed | high |
+| 5 | Frontend checkout flow still works after UI changes | ui | checkout-ui-flow | Browser trace + applicable API mocks | visible success/error state | high when frontend changed |
 | ...| ... | ... | ... | ... | ... | ... |
 
 **IMPORTANT:** Only proceed to the next phase once you have the complete scenario list. The total number should reflect distinct bug-catching outcomes and API boundaries — skip redundant tests even if they are a different type.`)
@@ -146,7 +144,7 @@ For each endpoint under test:
 
 Work through the scenario list from Phase 2 in **bug-catching priority order**. The budget is ${ctx.maxGenerate} total tests across all types.
 
-**Selection rule:** Generate the tests most likely to catch real regressions and edge-case bugs. Choose integration, provider contract, consumer contract, or UI based on which one best proves the behavior. There is no required quota by test type. If the highest-value ${ctx.maxGenerate} scenarios are all integration tests, generate integrations; if focused contracts catch the riskiest issues more directly, generate contracts. For API-only full-flow coverage, choose integration and model the whole scenario in one scenario trace; reserve UI tests for frontend changes or browser-observable flows.
+**Selection rule:** Generate the tests most likely to catch real regressions and edge-case bugs. Choose integration, provider contract, or UI based on which one best proves the behavior. There is no required quota by test type. If the highest-value ${ctx.maxGenerate} scenarios are all integration tests, generate integrations; if focused provider contracts catch the riskiest issues more directly, generate contracts. For API-only full-flow coverage, choose integration and model the whole scenario in one scenario trace; reserve UI tests for frontend changes or browser-observable flows.
 
 **Coverage floor:** If Phase 2 identifies multiple high-priority scenarios, generate and execute each high-priority scenario up to ${ctx.maxGenerate}. Do not stop after the first passing test while other high-priority scenarios remain ungenerated or unexecuted.
 
@@ -229,23 +227,6 @@ Provider contracts assert: status codes, required fields present, field types co
 
 ---
 
-**For \`consumer-contract\` scenarios:**
-
-Call \`skyramp_contract_test_generation\` with:
-- \`endpointURL\`: the downstream service URL using the original Docker service hostname (e.g., "http://identity-service:4000/api/internal/v1/users/validate")
-- \`method\`: what OUR code sends
-- \`requestData\`: the request body OUR code constructs (from reading the implementation)
-- \`responseData\`: what OUR code expects back (the shape it parses)
-- \`outputDir\`: "${ctx.repositoryPath}/tests/skyramp/"
-
-Consumer contract tests have mocks wired **inline by default** — the generated test file includes \`MockV2\` creation and \`client.apply_mock(mock)\` directly in the test function. **No separate \`skyramp_enrich_test_with_mocks\` call is needed for contract tests.** The mock defines the expected downstream response shape and the test validates the contract against it.
-
-Consumer contract tests are incomplete until they invoke real consumer/SUT code that triggers the outbound request. A generated stub that calls \`client.send_request\` directly against the mock only proves the mock responds; it does not prove the application sends the right body/header/path. If you cannot wire real consumer code, do not execute or report the contract as PASS — mark the scenario **Blocked — consumer wiring unavailable**.
-
-Consumer contracts catch: wrong outbound request body/header/path, field renamed downstream, new required header added, response shape changed, status code semantics changed.
-
----
-
 **For \`ui\` scenarios:**
 
 Generate UI tests only when the diff includes frontend changes, a changed UI route, or a browser-observable user flow:
@@ -280,7 +261,7 @@ Keep advancing in bug-catching priority order until the highest-value scenarios
 
 This injects import statements from the generated mock files — no data duplication. The test imports directly from the mock files.
 
-**Skip contract tests** — consumer contract tests already have mocks wired inline by the generation tool (\`client.apply_mock(mock)\` embedded in the test function). Provider contract tests don't use mocks at all.`)
+**Skip contract tests** — provider contract tests don't use mocks at all.`)
     .done()
     // ─── Phase 4: Verify ───────────────────────────────────────────────────────
     .addPhase("verify", "Verify Tests", { headerLevel: "##", stepFormat: "hash" })
@@ -288,13 +269,12 @@ This injects import statements from the generated mock files — no data duplica
 
 1. Every scenario from Phase 2 has a corresponding test file in \`${ctx.repositoryPath}/tests/skyramp/\`
 2. For integration tests with selected downstream mocks: mock files exist in \`mocks/\` for each selected service/protocol and test files import them via a non-empty \`MOCK_SERVICES\` plus the language-specific apply helper (\`apply_all_mocks(client)\` for Python or \`applyAllMocks(client)\` for TypeScript/JavaScript/Java); if \`MOCK_SERVICES = {}\` or any expected mock import is missing for a mocked dependency, return to \`GENERATE_MOCKS_AND_TESTS\` or \`ENRICH_TESTS\` before any edits or execution
-3. For consumer contract tests: mocks are wired inline (\`client.apply_mock(mock)\` present in the test function) — no separate mock files needed
-4. For provider contract tests: no mocks — test hits the real endpoint directly
-5. Test files use idempotent data (UUID-suffixed emails, random values — not hardcoded strings)
-6. Auth headers are present in all test requests
-7. **Integration tests have scenario-driven assertions** — each test asserts the specific response fields that prove the "What this verifies" column from the scenario table, not only the status code. If a test only asserts \`response.status_code == 201\` (or equivalent) without any field-level assertion on the behavior being tested, it is incomplete. Add \`skyramp.get_response_value()\` assertions for the key fields before executing.
-8. **Outbound side effects are verified** — for every selected REST/gRPC/Kafka mock whose request body/header/path/event payload is the behavior under test, the mock spec or test includes a request/event assertion. If the toolchain cannot express that assertion, mark the scenario blocked instead of treating a response-only test as coverage.
-9. **No unresolved stubs** — no generated test file contains \`TODO\`, a standalone \`pass\` statement in a test body, \`NotImplemented\`, "replace with real consumer code", or an executable consumer-contract test that only calls the mock directly. A skipped or strict xfail direct-mock reference is allowed only when the file also contains a separate executable real consumer/SUT test. These are blocking defects, not passing tests.
+3. For provider contract tests: no mocks — test hits the real endpoint directly
+4. Test files use idempotent data (UUID-suffixed emails, random values — not hardcoded strings)
+5. Auth headers are present in all test requests
+6. **Integration tests have scenario-driven assertions** — each test asserts the specific response fields that prove the "What this verifies" column from the scenario table, not only the status code. If a test only asserts \`response.status_code == 201\` (or equivalent) without any field-level assertion on the behavior being tested, it is incomplete. Add \`skyramp.get_response_value()\` assertions for the key fields before executing.
+7. **Outbound side effects are verified** — for every selected REST/gRPC/Kafka mock whose request body/header/path/event payload is the behavior under test, the mock spec or test includes a request/event assertion. If the toolchain cannot express that assertion, mark the scenario blocked instead of treating a response-only test as coverage.
+8. **No unresolved stubs** — no generated test file contains \`TODO\`, a standalone \`pass\` statement in a test body, \`NotImplemented\`, or "replace with real consumer code". These are blocking defects, not passing tests.
 
 **If any mock file is missing for integration tests:** re-run \`skyramp_mock_generation\` for that service/endpoint.`)
     .step("ENHANCE_ASSERTIONS", "Enhance assertions for each test file", (ctx) => `For each test file in \`${ctx.repositoryPath}/tests/skyramp/\`, call \`skyramp_enhance_assertions\` with:
@@ -318,23 +298,24 @@ The tool returns instructions — it does NOT edit the file automatically. Apply
     .done()
     // ─── Phase 5: Deploy ────────────────────────────────────────────────────────
     .addPhase("deploy", "Deploy", { headerLevel: "##", stepFormat: "hash" })
-    .step("START_ENVIRONMENT", "Bring up the service under test", (ctx) => `If a \`docker-compose\` file is present in the repository, the service under test and its real infrastructure (DB, cache, real broker, real first-party services) must be running — **but mocked downstream services must NOT be running.**
+    .step("START_ENVIRONMENT", "Bring up the service under test and the Skyramp worker", (ctx) => `Bring up the service under test and its real infrastructure (DB, cache, real broker, real first-party services) together with the Skyramp mock worker — **but mocked downstream services must NOT be running.**
 
-**Why this matters:** The Skyramp worker intercepts traffic via Docker DNS alias hijacking — it registers itself as the DNS alias for each mocked service's hostname on the Docker network. If the real service container is also up on the same hostname and port, the two will conflict: traffic may reach the real service instead of the mock, or port binding will fail entirely. This is the most common cause of mocks not being applied correctly.
+**Why this matters:** The Skyramp worker runs as a Docker Compose service on the SUT's network and intercepts traffic via Docker DNS alias hijacking at mock-apply time — it takes over the DNS alias for each mocked service's hostname. If the real service container is also up on the same hostname and port, the two conflict: traffic may reach the real service instead of the mock, or port binding fails. This is the most common cause of mocks not being applied correctly. Running the worker as a compose service (rather than spawning it ad hoc) guarantees it joins the SUT's network and is torn down with the stack.
 
 Steps:
-1. Run \`docker compose ps\` in \`${ctx.repositoryPath}\` to check current container state.
-2. Identify which docker-compose service names correspond to services selected for mocking (e.g., if \`ams\` is selected for mocking, do not start the \`ams\` container).
-3. Stop any mocked service containers that are already running:
-   \`docker compose stop <mocked-service-1> <mocked-service-2> ...\`
-4. Rebuild and bring up only the SUT and its real dependencies — start selectively:
-   \`docker compose up -d --build <sut-service> <db> <cache> <broker> <real-first-party-services>\`
-   Do **not** run plain \`docker compose up -d\` when it would start mocked downstream services or reuse a stale SUT image. If the compose file cannot start selectively, start the minimum required profile/services and then re-check that mocked service containers are stopped before executing tests. If the SUT service has no compose \`build\` context, record that local code cannot be rebuilt by compose before execution.
-5. Wait for health checks to pass and verify the service under test responds (e.g., curl the health endpoint or send a minimal request).
-
-The \`skyramp_execute_test\` tool runs the enriched test in the language runner. The enriched test applies selected mocks at runtime through its language-specific helper before exercising the service.
-
-**Do NOT proceed to Execute until: (a) the service under test responds, and (b) all mocked service containers are confirmed stopped.**`)
+1. Call \`skyramp_setup_local_dev_worker\` with \`repositoryPath\` = \`${ctx.repositoryPath}\` (pass \`composeFile\` if the base docker-compose file is not at the repo root). It writes a worker compose override and returns \`composeFilePrefix\` (the \`-f <base> -f <override>\` flags), the resolved \`dockerNetwork\`, and the worker port. **Use the returned \`composeFilePrefix\` for every \`docker compose\` command below, and pass the returned \`dockerNetwork\` to test/mock generation (see the Generate phase).**
+2. Run \`docker compose <composeFilePrefix> ps\` to check current container state.
+3. Identify which docker-compose service names correspond to services selected for mocking (e.g., if \`ams\` is selected for mocking, do not start the \`ams\` container).
+4. Stop any mocked service containers that are already running:
+   \`docker compose <composeFilePrefix> stop <mocked-service-1> <mocked-service-2> ...\`
+5. Rebuild and bring up only the SUT, its real dependencies, and the worker — start selectively:
+   \`docker compose <composeFilePrefix> up -d --build <sut-service> <db> <cache> <broker> <real-first-party-services> skyramp\`
+   Always include the \`skyramp\` service. Do **not** run plain \`docker compose up -d\` when it would start mocked downstream services or reuse a stale SUT image. If the compose file cannot start selectively, start the minimum required profile/services plus \`skyramp\`, then re-check that mocked service containers are stopped before executing tests. If the SUT service has no compose \`build\` context, record that local code cannot be rebuilt by compose before execution.
+6. Wait for health checks to pass and verify (a) the service under test responds (e.g., curl the health endpoint) and (b) the \`skyramp\` worker container is running.
+
+The \`skyramp_execute_test\` tool runs the enriched test in the language runner. Its generated Skyramp client connects to the worker — emitted with \`runtime="docker"\`, \`docker_network\`, and \`docker_skyramp_port\` (from the \`dockerNetwork\` and \`dockerWorkerPort\` passed to generation) — and applies the selected mocks before exercising the service.
+
+**Do NOT proceed to Execute until: (a) the service under test responds, (b) the \`skyramp\` worker is running, and (c) all mocked service containers are confirmed stopped.**`)
     .subStep("DEPLOY_GRPC", "Handle gRPC dependencies", (_ctx) => `If the dependency map from Phase 1 includes gRPC services selected for mocking:
 
 To regenerate a single missing gRPC mock, call \`skyramp_mock_generation\` with \`protocol: "grpc"\`.
@@ -414,6 +395,7 @@ That's it. Pass \`token: ""\` so the executor injects \`SKYRAMP_TEST_TOKEN\` fro
   - **Generated test issue** — failure from wrong auth, missing field, or incorrect assertion in the generated test itself.
   - **Timeout** — execution did not complete; pass/fail is unknown.
 - **Issues found**: unmockable deps, generation failures, connection errors, gaps
+- **Teardown**: remind the user that, when finished, tearing the stack down with \`docker compose <composeFilePrefix> down -v --remove-orphans\` (the same \`-f\` prefix returned by \`skyramp_setup_local_dev_worker\`) removes the SUT, real dependencies, **and the Skyramp worker** together — so no worker container or network is left behind. A plain \`docker compose down\` *without* the override prefix leaves the worker running (it is defined only in the override, so a base-only \`down\` treats it as an orphan) and the network fails to delete with "resource still in use"; always include the prefix. If the prefix is ever unavailable at teardown, \`docker compose down --remove-orphans\` against the base file still sweeps the worker as an orphan.
 
 Do NOT write results to a file — report inline to the user.`)
     .done();

package/build/prompts/local-dev/local-dev-prompts.js

@@ -58,11 +58,12 @@ ${sandboxWorkerBlock ? sandboxWorkerBlock + "\n" : ""}${serviceContext ? service
 - **Mock files are code in the same language as tests** — \`skyramp_mock_generation\` produces mock files (language from workspace config) in \`tests/skyramp/mocks/\` with language-native mock factory functions (\`get_all_mocks()\` for Python, \`getAllMocks()\` for TypeScript/JavaScript/Java) that return MockV2 objects. The enrichment tool imports these, builds a collective \`MOCK_SERVICES\` collection, reuses the integration test client, clears stale mocks, and applies the full mock set in one atomic call. Do NOT create YAML mock files.
 - **NO Skyramp CLI** — do NOT use \`skyramp mocker apply\`, \`skyramp mocker generate\`, or any other Skyramp CLI command. Use ONLY MCP tools for Skyramp operations.
 - **NO duplicate mock data** — the generated mock files are the single source of truth. Do NOT duplicate response bodies or status codes in the test file. The test references mock files, not copies of them.
-- **Mock generation → enrich flow (integration tests only)** — use \`skyramp_mock_generation\` to generate mock files, then call \`skyramp_enrich_test_with_mocks\` to wire mock references into the test. The enrichment uses the same data from generation — never invent different values. Consumer contract tests do NOT need enrichment — mocks are wired inline by the generation tool.
+- **Mock generation → enrich flow (integration tests only)** — use \`skyramp_mock_generation\` to generate mock files, then call \`skyramp_enrich_test_with_mocks\` to wire mock references into the test. The enrichment uses the same data from generation — never invent different values.
 - **MANDATORY enrichment gate** — after every \`skyramp_integration_test_generation\` call for a scenario with any generated mock files, immediately call \`skyramp_enrich_test_with_mocks\` before reading, editing, enhancing, or executing that test. Do not batch all enrichment for later.
 - **Enrichment validation** — an integration test that has downstream mocks but lacks \`MOCK_SERVICES\` and the language-specific apply helper (\`apply_all_mocks(client)\` for Python or \`applyAllMocks(client)\` for TypeScript/JavaScript/Java) is incomplete. Stop and enrich it; never call \`skyramp_execute_test\` on an incomplete integration test.
 - **Do not delete mocks to pass** — if mock deployment fails, do NOT remove mock imports, empty \`MOCK_SERVICES\`, switch mocked downstreams to live Compose stubs, or report the resulting test as passed. Fix the mock wiring once; if still blocked, report the scenario as failed/blocked with the mock deployment error.
 - **Mocked services must not be running** — before execution, stop every Docker container for a service selected for mocking (\`docker compose stop <mocked-service>\`). The Skyramp worker takes over that service's DNS alias on the Docker network; a real container running on the same hostname and port will conflict, causing traffic to reach the real service instead of the mock or causing port binding failure. Bring up only the SUT and its real infrastructure (DB, cache, real broker, real first-party services); do NOT run \`docker compose up -d\` without immediately stopping mocked service containers.
+- **Worker runs as a compose service** — the Deploy phase calls \`skyramp_setup_local_dev_worker\`, which adds the Skyramp worker to the SUT's Docker network via a compose override and returns the resolved \`dockerNetwork\` plus the \`-f\` \`composeFilePrefix\`. Pass that \`dockerNetwork\` (and \`dockerWorkerPort\`, default 35142) to \`skyramp_generate_enriched_integration_test\` so the generated client connects to that worker — generation emits the client with \`runtime="docker"\`, \`docker_network\`, and \`docker_skyramp_port\`. Use the \`composeFilePrefix\` for every \`docker compose\` command, and tear the stack down with the same prefix (\`docker compose <composeFilePrefix> down -v --remove-orphans\`) so the worker is removed with the stack — a base-only \`docker compose down\` leaves the worker (it lives only in the override) holding the network open. Never spawn the worker manually.
 - **Mock URL format** — the \`endpointURL\` in \`skyramp_mock_generation\` MUST use the original Docker service hostname (e.g., \`http://identity-service:4000\`, \`http://profile-service:50052\`). The Skyramp executor uses DNS alias hijacking — it takes over the service's DNS name on the Docker network so the service under test's requests are intercepted transparently. NEVER use \`localhost\`, \`127.0.0.1\`, \`0.0.0.0\`, \`host.docker.internal\`, or the worker address as the mock URL. For REST mocks, \`skyramp_preflight_mock_check\` returns blocking \`REST_LOOPBACK_URL\` when a deployable mock uses these hosts.
 - **REST mock routing** — Generated REST mock files may contain a fallback \`URL\` value such as \`http://localhost:8080\`; do not manually edit those files. The enrichment tool uses the mock generation \`# Command\` target to set each REST mock's \`mock.url\` back to the original Docker service origin before \`apply_mock()\`. If the command target is loopback, regenerate the mock with the original service hostname.
 - **gRPC mock routing** — gRPC mocks may target the real downstream service port (e.g., \`partner-accounts:50051\`). Apply gRPC mocks before the SUT starts or restart the SUT after applying them, and verify the Skyramp worker has the original endpoint host alias from \`endpointURL\` (\`partner-accounts\`, not the protobuf service name like \`PartnerAccountsService\`).

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/dockerComposePrompt.js

@@ -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
 

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

@@ -80,9 +80,7 @@ export function buildWorkspaceInitSection() {
 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.
 
-This produces a baseline \`.skyramp/workspace.yml\` listing the services Testbot will test. Later steps in this SUT bootstrap run write \`.skyramp/sut/*\` files alongside it. You might have to update the per-service \`runtimeDetails.serverStartCommand\` to match the new SUT files created, so Testbot brings up the services correctly.
-
-Also verify each service's \`api.baseUrl\` includes the API path prefix (e.g. \`/api\`, \`/api/v1\`, \`/v1\`) — 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.`;
+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.

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

@@ -1,6 +1,6 @@
 /**
  * Prompt language for skyramp_actions output — the LLM_INSTRUCTIONS block
- * emitted to the agent that applies UPDATE and REGENERATE edits.
+ * emitted to the agent that applies UPDATE, REGENERATE, and DELETE actions.
  *
  * Kept separate from actionsTool.ts so prompt text is co-located with other
  * maintenance prompts and can be reviewed/edited without touching tool logic.
@@ -18,6 +18,8 @@ export declare function buildFileRenameStrategy(): string;
 export declare function buildUpdateStrategy(): string;
 /** Strategy string for REGENERATE — call generation tool to overwrite the file. */
 export declare function buildRegenerateStrategy(): string;
+/** Strategy string for DELETE — remove obsolete test files whose covered endpoints/UI no longer exist. */
+export declare function buildDeleteStrategy(): string;
 /** Per-file instruction block for a single UPDATE recommendation. */
 export declare function buildUpdateFileInstruction(params: {
     testFile: string;

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

@@ -1,6 +1,6 @@
 /**
  * Prompt language for skyramp_actions output — the LLM_INSTRUCTIONS block
- * emitted to the agent that applies UPDATE and REGENERATE edits.
+ * emitted to the agent that applies UPDATE, REGENERATE, and DELETE actions.
  *
  * Kept separate from actionsTool.ts so prompt text is co-located with other
  * maintenance prompts and can be reviewed/edited without touching tool logic.
@@ -15,12 +15,20 @@ 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() {
     return `For each file in regenerate_context, call the appropriate generation tool (skyramp_integration_test_generation or skyramp_contract_test_generation) with outputDir set to the file's directory and output set to the filename. Use existing_content to determine the test type, endpoint, auth pattern, and language. The generation tool will overwrite the file. Do NOT use skyramp_ui_test_generation here — UI test regeneration requires a recorded trace (playwrightInput) and must be handled separately.`;
 }
+/** Strategy string for DELETE — remove obsolete test files whose covered endpoints/UI no longer exist. */
+export function buildDeleteStrategy() {
+    return `For each file in files_to_delete, remove it from the repository with 'git rm <file>' (fall back to 'rm <file>' if the file is untracked). These tests cover endpoints or UI that no longer exist and have no migration path. Do NOT edit, regenerate, or call skyramp_enhance_assertions on these files — the only action is deletion.`;
+}
 /** Per-file instruction block for a single UPDATE recommendation. */
 export function buildUpdateFileInstruction(params) {
     const { testFile, renames, suggestedNewFile, updateInstructions, rationale } = params;

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.d.ts

@@ -1,6 +1,4 @@
 export declare function buildActionDecisionTree(): string;
-/** @deprecated use the individual check functions; this function is no longer part of the prompt */
-export declare function buildBreakingChangePatterns(): string;
 export declare function buildCheckEndpointExistence(): string;
 export declare function buildCheckResponseShape(): string;
 export declare function buildCheckAuthAndAuthorization(): string;