@skyramp/mcp 0.2.5 → 0.2.7

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

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { MAX_TESTS_TO_GENERATE, MAX_RECOMMENDATIONS, MAX_CRITICAL_TESTS, PATH_PARAM_UUID_GUIDANCE, AUTH_CONFLICT_ERROR_MSG, } from "../test-recommendation/recommendationSections.js";
+import { buildDriftAnalysisPrompt } from "../test-maintenance/drift-analysis-prompt.js";
 import { getTraceRecordingPromptText } from "../../playwright/traceRecordingPrompt.js";
 import { isContractConsumerModeEnabled } from "../../utils/featureFlags.js";
 import { resolveServiceDetailsRef } from "../../utils/utils.js";
@@ -20,9 +21,6 @@ const CONTRACT_MODE_GUIDANCE = CONSUMER_MODE_ENABLED
 export function getTestbotPrompt(prTitle, prDescription, summaryOutputFile, repositoryPath, baseBranch, maxRecommendations = MAX_RECOMMENDATIONS, maxGenerate = MAX_TESTS_TO_GENERATE, _maxCritical = MAX_CRITICAL_TESTS, // Reserved — accepted for API compat but not yet wired into prompt
 prNumber, userPrompt, services, stateOutputFile, uiCredentials, testsRepoDir) {
     maxGenerate = Math.min(Math.max(maxGenerate, 0), maxRecommendations);
-    // TODO(SKYR-3636 follow-up): migrate Task 1 + Task 2 step bodies to PromptPlan
-    // (src/prompts/test-recommendation/promptPlan.ts) so step numbers don't have
-    // to be hand-maintained when steps are added or reordered.
     // For follow-up requests: emit the @skyramp-testbot header + guardrails + retrieve-recommendations step.
     // For first-run prompts: emit the full Task 1 analysis + maintenance section.
     const task1Section = userPrompt
@@ -53,27 +51,21 @@ Use those recommendations as your baseline. Only add or remove tests that the us
 
 ## Task 1: Analyze & Maintain
 
-1. **Pre-flight UI enumeration.** Call \`skyramp_ui_analyze_changes\` with \`repositoryPath\`: "${repositoryPath}"${uiCredentials ? `, \`uiCredentials\`: <use the value from <ui-credentials> in your context>` : ""}. The response returns \`uiContext\` (\`changedFrontendFiles\`, \`candidateUiPages\`) and capture instructions.
+1. Call \`skyramp_analyze_changes\` with \`repositoryPath\`: "${repositoryPath}", \`scope\`: "branch_diff", \`topN\`: ${maxRecommendations}, \`maxGenerate\`: ${maxGenerate}${baseBranch ? `, \`baseBranch\`: "${baseBranch}"` : ""}${prNumber ? `, \`prNumber\`: ${prNumber}` : ""}${stateOutputFile ? `, \`stateOutputFile\`: "${stateOutputFile}"` : ""}${testsRepoDir ? `, \`testsRepoDir\`: "${testsRepoDir}"` : ""}.
 
-   **If the response says "No UI changes detected"** → skip ahead to \`skyramp_analyze_changes\`.
+   **Follow all instructions returned by \`skyramp_analyze_changes\`** — its response opens with a **UI Blueprint Capture** section that tells you which candidate URLs to capture (and how) before you write any UI recommendation \`reasoning\`.${uiCredentials ? " If the section lists candidate URLs, log in once via the credentials in your <ui-credentials> context before navigating to them." : ""}
 
-   **Otherwise:** for each candidate URL in the response${uiCredentials ? " (after logging in via the credentials provided)" : ""}, \`browser_navigate\` to the URL, then \`browser_blueprint\` to capture. The captures stay in your tool-result history — they're the element vocabulary you'll use when writing UI recommendation \`reasoning\` fields in \`skyramp_analyze_changes\`. You do NOT need to thread them back into a tool call.
 
-   If a candidate URL 404s or redirects, navigate from the workspace baseUrl and explore. If \`browser_blueprint\` fails on every candidate, proceed to \`skyramp_analyze_changes\` and log an \`issuesFound\` info entry — UI recommendations will fall back to source-grounded prose.
+   **Feature context check:** After capturing a blueprint per the UI Blueprint Capture instructions, cross-check whether it actually shows the changed feature. Look at the diff — what component, field, or UI element was changed? If that component only renders in a specific context (a particular collection type, a non-empty list, a specific user role, a form that only appears after a prior action), and the blueprint you captured doesn't contain it, navigate to the right context before using this blueprint for recommendations. A blueprint that doesn't show the changed feature produces recommendations that test the wrong thing — for example, recommending tests against a system collection when the PR changed behavior on custom collections. If you can't determine the right context from the diff and workspace config, note it in \`issuesFound\` and fall back to source-grounded recommendations for that URL.
 
-2. Call \`skyramp_analyze_changes\` with \`repositoryPath\`: "${repositoryPath}", \`scope\`: "branch_diff", \`topN\`: ${maxRecommendations}, \`maxGenerate\`: ${maxGenerate}${baseBranch ? `, \`baseBranch\`: "${baseBranch}"` : ""}${prNumber ? `, \`prNumber\`: ${prNumber}` : ""}${stateOutputFile ? `, \`stateOutputFile\`: "${stateOutputFile}"` : ""}${testsRepoDir ? `, \`testsRepoDir\`: "${testsRepoDir}"` : ""}. Use the blueprints already in your context (from \`skyramp_ui_analyze_changes\`) to ground UI recommendation reasoning.
    **If \`skyramp_analyze_changes\` returns an error:** retry once only if the error is transient (timeout, network blip, temporary unavailability) — do NOT retry for permanent errors (invalid repository path, missing required parameter, authentication failure). If it fails again, call \`skyramp_submit_report\` with a minimal valid payload: leave all test arrays empty and add the error to \`issuesFound\`. Refer to the \`skyramp_submit_report\` schema for required fields. Do NOT attempt Task 2 without a valid stateFile.
-   **If all changed files are non-application** (CI/CD, docs, lock files, config, or cosmetic frontend changes such as \`.css\`/\`.scss\` reformats with no observable rendering or interaction change) → skip to Task 3 (Submit Report) and follow the zero-test abstention path there.
+   **If all changed files are non-application** (CI/CD, docs, lock files, config) → skip to Task 3 (Submit Report) with empty arrays and a single \`issuesFound\` entry explaining why (same format as the zero-test path below).
 
-3. **Maintain existing tests:**
+2. **Maintain existing tests:**
 
-   a. Call \`skyramp_analyze_test_health\` with \`stateFile\` (from \`skyramp_analyze_changes\` output). **Do NOT read application source files** (routes, models, controllers) — all change information you need is in the \`skyramp_analyze_changes\` output and the diff.
+${buildDriftAnalysisPrompt()}
 
-   b. Write \`updateInstructions\` for each UPDATE or REGENERATE test before calling \`skyramp_actions\` — articulating the change first prevents file content from overriding diff-based reasoning.
-
-   c. Call \`skyramp_actions\` with \`stateFile\` (from \`skyramp_analyze_changes\` output) and apply the edits it returns.
-
-4. **Code review:** From the \`skyramp_analyze_changes\` output and the existing test files you read for maintenance, note any logic bugs. Do NOT read additional source files just for code review — use what is already available from the analysis and test file reads. Common patterns to flag:
+3. **Code review:** From the \`skyramp_analyze_changes\` output and the existing test files you read for maintenance, note any logic bugs. Do NOT read additional source files just for code review — use what is already available from the analysis and test file reads. Common patterns to flag:
    - Computed fields not recalculated after mutation (e.g. \`total_amount\` unchanged after items are added/removed)
    - Incomplete CRUD: create without cleanup, update that adds new records without removing old ones
    - Missing input validation on new endpoints
@@ -81,15 +73,178 @@ Use those recommendations as your baseline. Only add or remove tests that the us
    - Incorrect arithmetic in business logic (discount calculations, price aggregation)
    Log each finding in \`issuesFound\` with a \`severity\` (critical/high/medium/low). These bugs should inform your test design in Task 2.
 
-5. **Blueprint Citation Invariant** (UI test recommendations only). When \`skyramp_analyze_changes\` returned recommendations grounded in the captured blueprints from \`skyramp_ui_analyze_changes\`, every named UI element your recommendation \`reasoning\` mentions — heading text, button label, link text, role descriptions — must correspond to an element actually present in one of those captured blueprints.
-
-   Write the \`reasoning\` field in **natural prose** that names the elements as a human would describe them ("the Notifications heading", "the disabled Mark all as read button"). Do NOT use internal-identifier syntax like \`role=button, logicalName=...\` — that jargon leaks builder internals into a user-facing report.
-
-   Self-check before submitting: for each UI recommendation's \`reasoning\`, every element you mention by name should appear in one of the captured blueprints. If an element name doesn't appear in any blueprint, either rewrite the reasoning around an element that IS captured, or drop the element reference and describe the test target in higher-level terms ("the empty state of the notifications page"). Do not invent element names from the PR description, source diff, or component name.
-
-   **Non-UI entries (contract / integration / e2e / batch-scenario) are unaffected.** Their \`reasoning\` fields use the pre-existing formats — endpoint paths, request/response schemas, fixture chains. Do not reformat them.
-
-   **No upstream captures available?** If \`skyramp_ui_analyze_changes\` produced no candidate URLs or \`browser_blueprint\` failed on every candidate, all UI recommendations fall back to source-grounded prose drawn from the diff alone. Log the failure mode once in \`issuesFound\`. Non-UI work is unaffected.
+4. **Blueprint Citation Invariant** (UI test recommendations only). Every named UI element in your recommendation must correspond to an element actually captured in one of the blueprints you captured from the UI Blueprint Capture section of \`skyramp_analyze_changes\`. For **every** UI recommendation — both \`newTestsCreated[]\` entries (tests you generated) AND \`additionalRecommendations[]\` entries (deferred tests) with \`testType: "ui"\` — populate **four** fields: \`description\`, \`reasoning\`, \`targetElements\`, and \`pageContext\`. \`description\` and \`reasoning\` carry different roles — fill BOTH (see Field 4 below). The structured fields (\`targetElements\`, \`pageContext\`) are required on UI recs in BOTH arrays; non-UI recs (contract / integration / e2e / batch-scenario) MUST omit them.
+
+   **Field 1 — \`targetElements\`** (the elements the test targets — array, length 1+):
+   \`\`\`json
+   [
+     {
+       "role": "button",
+       "accessibleName": "Save changes",
+       "testId": "save-changes-btn",
+       "stableId": null,
+       "contextText": null,
+       "mutability": "mutable",
+       "widgetType": "native"
+     }
+   ]
+   \`\`\`
+   - **One element when the test has a single dominant target** (a click, a type, a single visibility check). Most tests fall here — use a length-1 array.
+   - **Multiple elements when the test verifies several elements together** — render-state tests (heading + input + button on a form), workflow tests (click button A, assert state appears in element B), or form-fill tests (multiple inputs + submit button). Each element is its own array entry.
+   - Each element's fields are lifted verbatim from a captured blueprint element. \`role\`, \`accessibleName\` are required. \`testId\`/\`stableId\`/\`contextText\` are \`null\` when not present in the capture.
+   - \`mutability\` — copy from \`blueprint.element.mutability\`. \`'mutable'\` = behavioral-test target; \`'immutable'\` = smoke target.
+   - \`widgetType\` — copy from \`blueprint.element.widgetType\`. \`'custom'\` = JavaScript-composite control (Radix, MUI, etc.) requiring click-to-open interaction; \`'native'\` = standard HTML element.
+   - \`contextText\` — only for elements inside repeating sections (table rows, list items). Lift from \`repeatingElement.items[].contextText\`. \`null\` otherwise.
+
+   **Field 2 — \`pageContext\`** (where the test runs):
+   \`\`\`json
+   { "url": "http://localhost:5173/orders/1", "pageHash": "10:434266447" }
+   \`\`\`
+   Lift \`url\` and \`pageHash\` from the BlueprintCapture object that fed \`targetElements\`. All entries in \`targetElements\` should be from the same page.
+
+   **Field 3 — \`reasoning\`** (one sentence — what is verified and why):
+
+   A **single sentence** (~25-50 words) that names the targeted element(s) and states what the test verifies and why it matters. There is no fixed template — write the sentence in whatever way reads naturally for the test. The constraints below are the only requirements.
+
+   - **Reference each element from \`targetElements\` by its \`accessibleName\`**. Bold each name. When the element has a \`testId\`, render it in inline code (e.g. \`save-changes-btn\`); fall back to \`stableId\` if no \`testId\`. Omit the parenthetical identifier when neither is captured. For elements inside repeating sections, include \`contextText\` parenthetically (e.g. \`(customer "Acme", total "$199.99")\`).
+   - **State what the test verifies or asserts** about those elements — the behavior, render state, business rule, or production risk.
+   - **Optionally add a "; this validates …" or "; covers …" clause** naming a formula, business rule, or source-line reference (e.g. "; this validates the \`subtotal * (1 - discountPercent/100)\` formula", "; covers the boundary clamp at EditOrderForm.tsx:42"). Skip the clause for smoke checks where there's no concrete code reference.
+   - **Voice matches which array the rec is in.** \`newTestsCreated\` uses descriptive voice ("verifies", "asserts", "documents"). \`additionalRecommendations\` uses recommendatory voice ("would verify", "should assert", "would cover"). Pick a sentence opening that matches; you do not need to start with a fixed phrase.
+   - **Multi-element recs** combine elements in one sentence using natural connectives ("and", "after clicking", "alongside") — not enumeration.
+   - Do NOT include \`logicalName\`, \`fingerprint\`, \`pageHash\`, \`xpath\`, or other internal identifiers — those leak builder internals into a user-facing report. (\`pageHash\` lives in \`pageContext\` for the verifier; never put it in prose.)
+
+   **Field 4 — \`description\`** (multi-sentence test walkthrough — REQUIRED for UI recs):
+
+   The \`description\` field complements \`reasoning\`. While \`reasoning\` is one sentence about what the test verifies and why, \`description\` is **2-4 sentences of free-form prose** describing the test as a walkthrough — the page navigated to, the actions taken, the assertions made, the data values used. Reads like documentation for whoever implements the test.
+
+   - For \`newTestsCreated\`: describe what the test does step by step. Example: "Navigates to /orders/1, opens the Edit Order form, enters discount=20%, submits, and asserts the real-time total updates to $799.99 before the PUT call."
+   - For \`additionalRecommendations\`: describe what the recommended test would do. Example: "Would navigate to a cancelled order's detail page and assert the Edit Order button is not rendered, enforcing the conditional guard added in OrderDetail.tsx."
+   - **\`description\` is NOT a duplicate of \`reasoning\`.** Keep them complementary: \`description\` = what the test does (walkthrough), \`reasoning\` = what's verified + why (one sentence).
+   - Same jargon-exclusion rules apply (no \`logicalName\` / \`pageHash\` / etc.).
+   - Same fallback rules apply: when no blueprint is available, prefix \`description\` and \`reasoning\` with \`[no-blueprint-data]\` and use page/feature-level prose.
+
+   **Examples (showing the full bundle — copy the structure, not the exact wording):**
+
+   *Single-element generated test (descriptive voice, with rationale clause):*
+   \`\`\`json
+   {
+     "testType": "ui",
+     "description": "Navigates to /orders/1, opens the Edit Order form, enters discount=150, submits, and asserts the validation error 'Discount must be ≤ 100' appears and the form does not close. Documents the boundary-clamp guard in EditOrderForm.tsx.",
+     "targetElements": [
+       {
+         "role": "button", "accessibleName": "Save changes",
+         "testId": "save-changes-btn", "stableId": null,
+         "contextText": null, "mutability": "mutable", "widgetType": "native"
+       }
+     ],
+     "pageContext": {
+       "url": "http://localhost:5173/orders/1",
+       "pageHash": "10:434266447"
+     },
+     "reasoning": "Verifies the **Save changes** button (\`save-changes-btn\`) shows a validation error and prevents form close when discount > 100; this validates the \`Math.min(100, Math.max(0, value))\` clamp at EditOrderForm.tsx:42."
+   }
+   \`\`\`
+
+   *Multi-element generated test (render-state, descriptive voice):*
+   \`\`\`json
+   {
+     "testType": "ui",
+     "description": "Navigates to /orders/1, clicks Edit Order, and asserts both the 'Edit Order' heading and the Discount (%) input render with discount pre-filled to 0. Smoke check before any user interaction.",
+     "targetElements": [
+       {
+         "role": "heading", "accessibleName": "Edit Order",
+         "testId": "edit-order-heading", "stableId": null,
+         "contextText": null, "mutability": "immutable", "widgetType": "native"
+       },
+       {
+         "role": "spinbutton", "accessibleName": "Discount (%)",
+         "testId": "edit-order-input-discount", "stableId": null,
+         "contextText": null, "mutability": "mutable", "widgetType": "native"
+       }
+     ],
+     "pageContext": {
+       "url": "http://localhost:5173/orders/1",
+       "pageHash": "13:-684516288"
+     },
+     "reasoning": "Asserts the **Edit Order** heading (\`edit-order-heading\`) and **Discount (%)** input (\`edit-order-input-discount\`) render with discount pre-filled to 0 on form mount; covers the form-mount default-value contract."
+   }
+   \`\`\`
+
+   *Negative test (asserts element is NOT rendered), recommendatory voice:*
+   \`\`\`json
+   {
+     "testType": "ui",
+     "description": "Would navigate to a cancelled order's detail page and assert the Edit Order button is not rendered. Enforces the conditional-render guard added in OrderDetail.tsx.",
+     "targetElements": [
+       {
+         "role": "button", "accessibleName": "Edit Order",
+         "testId": "edit-order-btn", "stableId": null,
+         "contextText": null, "mutability": "mutable", "widgetType": "native"
+       }
+     ],
+     "pageContext": {
+       "url": "http://localhost:5173/orders/cancelled-99",
+       "pageHash": "9:712044820"
+     },
+     "reasoning": "Would assert the **Edit Order** button (\`edit-order-btn\`) is not rendered on cancelled orders; enforces the conditional-render guard added in OrderDetail.tsx:118."
+   }
+   \`\`\`
+   (For negative tests, ground \`targetElements\` against a captured page where the element DOES render — so the verifier can confirm the citation is real.)
+
+   *Page-level / lifecycle test (no single dominant element), recommendatory voice:*
+   \`\`\`json
+   {
+     "testType": "ui",
+     "description": "Would walk through create → edit → cancel of an order, asserting the Order details heading reflects each state transition (Pending → Editing → Cancelled). Covers the OrderStatus state machine added in this PR.",
+     "targetElements": [
+       {
+         "role": "heading", "accessibleName": "Order details",
+         "testId": null, "stableId": null, "contextText": null,
+         "mutability": "immutable", "widgetType": "native"
+       }
+     ],
+     "pageContext": {
+       "url": "http://localhost:5173/orders/1",
+       "pageHash": "11:200115447"
+     },
+     "reasoning": "Would walk the create-edit-cancel order lifecycle and assert the **Order details** heading reflects each state transition; covers the OrderStatus state machine added in this PR."
+   }
+   \`\`\`
+   (When there's no single focus, anchor on the page heading or the most stable on-page element.)
+
+   *Single-element additional recommendation (recommendatory voice):*
+   \`\`\`json
+   {
+     "testType": "ui",
+     "description": "Would navigate to /admin/notifications when the inbox is empty and assert the Notifications heading renders alongside the empty-state message. Smoke check that the page handles the zero-rows case.",
+     "targetElements": [
+       {
+         "role": "heading", "accessibleName": "Notifications",
+         "testId": null, "stableId": null, "contextText": null,
+         "mutability": "immutable", "widgetType": "native"
+       }
+     ],
+     "pageContext": {
+       "url": "http://localhost:5173/admin/notifications",
+       "pageHash": "8:992103445"
+     },
+     "reasoning": "Would assert the **Notifications** heading renders alongside the empty-state message when the inbox has zero rows; covers the empty-state render path added in NotificationsPage.tsx:31."
+   }
+   \`\`\`
+
+   **Self-check before submitting (per UI rec, in both \`newTestsCreated\` and \`additionalRecommendations\`):**
+   - **Both \`description\` AND \`reasoning\` are populated.** \`description\` is a 2-4 sentence walkthrough; \`reasoning\` is one sentence about what's verified + why. They must not duplicate each other.
+   - Every entry in \`targetElements\` must appear verbatim in a captured blueprint element (matched on \`accessibleName\` + \`role\`).
+   - Every element name appearing in \`reasoning\` must match an entry's \`accessibleName\` exactly. Every backticked identifier in \`reasoning\` must come from a \`testId\` or \`stableId\` of an entry.
+   - **Voice matches the array:** \`newTestsCreated\` uses descriptive voice ("verifies", "asserts", "documents"). \`additionalRecommendations\` uses recommendatory voice ("would verify", "should assert", "would cover").
+   - \`pageContext.url\` must equal the URL of the BlueprintCapture you lifted \`targetElements\` from.
+   - Never mix two elements' fields in one \`targetElements\` entry — each entry is one captured element.
+   - No internal jargon in \`reasoning\` or \`description\`: no \`logicalName\`, \`fingerprint\`, \`pageHash\`, \`xpath\`.
+   - If any check fails, re-capture and verify, or drop that recommendation.
+
+   **Non-UI entries (contract / integration / e2e / batch-scenario) are unaffected.** Use their pre-existing reasoning formats. Do NOT add \`targetElements\` or \`pageContext\` to non-UI entries — the schema rejects them.
+
+   **No upstream captures available?** Set \`targetElements\` to \`null\`, omit \`pageContext\`, and prefix \`description\` and \`reasoning\` with \`[no-blueprint-data]\`. Use page/feature-level prose; don't cite specific element names without grounding. Apply the marker per entry, not per PR — affected recs only. Log capture failures in \`issuesFound\` (one info-severity entry per failure mode, naming counts). Don't pre-emptively fall back without attempting capture first. Non-UI work is unaffected.
 
 ---`;
     const serviceContext = services?.length ? buildServiceContext(services) : '';
@@ -122,7 +277,7 @@ ${userPrompt ? "Generate only the tests that the user requested from the Additio
 - **MANDATORY — use the pre-ranked GENERATE list as-is**: The Execution Plan's GENERATE section governs ADD actions. You MUST generate exactly those scenarios in the exact order listed. Do NOT substitute, rename, or replace a GENERATE item. If parameter grounding uncovers a distinct bug-catching scenario not already in the GENERATE or ADDITIONAL list, generate it after all planned GENERATE items are complete and report it in \`newTestsCreated\` — this is an additional test driven by source-code analysis and does not count against the GENERATE budget.
 - Scenario JSON files are always new files — always generate them for new methods. Every generated scenario JSON must have a corresponding new integration test generated from it via \`skyramp_integration_test_generation\`.
 - Covered-resource handling (aligns with Execution Plan Step 0): When a GENERATE item targets a resource that already has an existing test file covering the same endpoint:
-  - If the existing test source is \`[external]\`, skip the resource entirely — the external test already provides coverage. Do NOT generate a new parallel test file for it.
+  - If the existing test source is \`[external]\`, skip the resource entirely — the external test already provides coverage. Do NOT UPDATE, REGENERATE, or DELETE external tests.
   - If the existing test is tagged \`[skyramp]\`, apply type-specific rules:
     - Contract tests: UPDATE the existing Skyramp test file (add the new method's test cases). A new test case is a new test even if the file already exists — report in \`newTestsCreated\` and count toward the budget.
     - Integration/scenario tests: Always generate as a new file via the scenario pipeline (\`skyramp_batch_scenario_test_generation\` → \`skyramp_integration_test_generation\`), even if an existing integration test covers the same resource. A new multi-step scenario (e.g. create → PATCH → verify recalculation) is a distinct test file. Report in \`newTestsCreated\` and count toward the budget.
@@ -139,7 +294,6 @@ ${userPrompt ? "Generate only the tests that the user requested from the Additio
     2. If no production file imports, re-exports, or renders it, the component has no DOM node in the running app → unintegrated.
     3. **Exception**: if the same PR also adds a route/page file (e.g. under Next.js \`pages/\` or \`app/\`) that imports the component, the route IS the integration point — test through it.
   **Never** apply the unintegrated heuristic to framework route/entrypoint files themselves — those are always reachable by convention.
-  - **(c) Cosmetic-only frontend change** — the frontend files in the diff are purely cosmetic with no observable rendering or interaction change (e.g. a \`.css\`/\`.scss\` reformat: property reordering, comment/whitespace edits, \`0px\`→\`0\`). \`uiContext.changedFrontendFiles\` being non-empty does NOT override this — that signal only means a frontend file changed, not that behavior changed. Take the zero-test abstention path in Task 3; do NOT record a trace just to satisfy the mandate.
   **Never** generate tests for unrelated pages as a substitute for an unintegrated component.
   This rule takes priority over generating additional backend-only tests.
 - **Always generate a test for critical bugs, even if it will fail.** When a GENERATE-tagged item targets a page or endpoint with a known bug, do NOT skip it because you expect the test to fail — a failing test that documents a bug is more valuable than a text-only description. This applies within the existing GENERATE budget; do not add extra tests beyond the plan.
@@ -226,6 +380,7 @@ ${CONTRACT_MODE_GUIDANCE}
   - \`skyramp_export_zip\` outputPath: \`${repositoryPath}/.skyramp/<test_name>_trace.zip\`
   - \`skyramp_ui_test_generation\`: set \`modularizeCode: false\`
   - **\`browser_assert\` — MANDATORY**: at least one per page navigated. Call multiple assertions in the same tool call batch when checking independent elements. If you navigate to 2 pages, assert on both. Each assertion should verify a business outcome (state change, computed value, error condition) — not just that an element is visible.
+  - **Wait for stable state before the second capture**: After performing an action that affects computed fields (filling a discount, submitting a form, adding an item), check the current page state before calling the second \`browser_blueprint\` (the capture after the action). If a computed field — total, price, count, derived text — still shows its initial empty or zero value (e.g. \`$0.00\`, \`0\`, \`Loading...\`, empty string), that means async data hasn't finished loading yet. Use \`browser_wait_for\` to wait up to 10 seconds for the field to update to a real value (for example, wait for the total to show a non-zero amount like \`$799.99\` instead of \`$0.00\`). Once the field shows a real value, THEN call the second \`browser_blueprint\` to capture stable state. If after 10 seconds the field still hasn't updated, skip the assertion on that field — don't capture and assert a value that hasn't loaded.
   If \`browser_navigate\` fails (app not running / connection refused), move to \`additionalRecommendations\` with the failure reason.
   Record at most 2-3 UI traces per run to stay within tool call budget. Quality over quantity: 1 great test is better than 3 mediocre ones — do not pad to reach the count.
   **Strategic assertions** — key checkpoints only, 3 to 5 per test:
@@ -238,9 +393,9 @@ ${CONTRACT_MODE_GUIDANCE}
 
   **Capture-act-capture (applies only when recording a UI trace):**
 
-  **Skip this entire section if \`uiContext\` was absent or \`changedFrontendFiles\` was empty in the \`skyramp_ui_analyze_changes\` response** (backend-only PR). The capture-act-capture pattern is for UI trace recording only — there's no UI trace to record on a backend-only PR. Continue to the non-UI test-type instructions below.
+  **Skip this entire section if \`uiContext\` was absent or \`changedFrontendFiles\` was empty in the \`skyramp_analyze_changes\` response** (backend-only PR). The capture-act-capture pattern is for UI trace recording only — there's no UI trace to record on a backend-only PR. Continue to the non-UI test-type instructions below.
 
-  **Reminder — the UI test priority rule above still applies.** If the diff contains frontend/UI changes, you still MUST attempt to generate at least one UI test. Capture-act-capture is **how** you record that test, not **whether** you record one — do not substitute UI recommendations for actually recording a trace. UI recommendation reasoning was already grounded in the upstream blueprints from \`skyramp_ui_analyze_changes\`; Task 2's capture-act-capture is for the trace's own assertions, not for retroactively rewriting recommendation reasoning.
+  **Reminder — the UI test priority rule above still applies.** If the diff contains frontend/UI changes, you still MUST attempt to generate at least one UI test. Capture-act-capture is **how** you record that test, not **whether** you record one — do not substitute UI recommendations for actually recording a trace. UI recommendation reasoning was already grounded in the blueprints you captured from the UI Blueprint Capture section of \`skyramp_analyze_changes\`; Task 2's capture-act-capture is for the trace's own assertions, not for retroactively rewriting recommendation reasoning.
 
   This pattern produces delta-derived assertions from blueprint diffs. Diff-derived assertions catch state changes more reliably than author-inference — the diff tells you what actually changed on the page so the assertion is grounded in observable state, not in guessing what "success" looks like.
 
@@ -254,15 +409,23 @@ ${CONTRACT_MODE_GUIDANCE}
 
     1. **Before** the action: \`browser_blueprint\`. Identify the semantic target by \`role\`, \`accessibleName\`, and \`stableId\`/\`testId\`.
 
-    2. If the target's \`widgetType\` is \`"custom"\` or \`"unknown"\`: \`browser_widget_contract_lookup\` with the element's \`fingerprint\` and \`ref\`. On \`"found"\`, execute the contract steps. On \`"needs_inference"\`, fall through to snapshot-driven trial clicks (\`browser_wait_for\` between retries). Inference-and-cache is out of scope for this slice, so don't attempt to synthesize and cache contracts.
+    2. If the target's \`widgetType\` is \`"custom"\` or \`"unknown"\`, it is a JavaScript-composite control (e.g. a Radix/MUI combobox, a date picker, a custom multi-select) that does not behave like a native HTML element. Do NOT call \`browser_fill\` or \`browser_select_option\` directly on it. Instead: click the trigger element first, use \`browser_wait_for\` to wait for the overlay/dropdown to appear, then interact with its contents. Use \`browser_snapshot\` to inspect what appeared before choosing what to click next.
 
     3. Execute the action via \`browser_click\` / \`browser_type\` / \`browser_navigate\`. The \`ref\` comes from \`browser_snapshot\` as today.
 
     4. **After** the action: \`browser_blueprint\` again. The response shape depends on whether the action navigated:
-       - **Same URL (modal/tab/in-place mutation):** \`{ isFullCapture: false, pageHash, previousPageHash, delta, possibleAssertions }\`. The \`delta\` field contains \`elementsAdded\`, \`elementsRemoved\`, \`textChanges\`, \`repeatingCountChanges\`. The \`possibleAssertions\` field is a mechanical translation of those entries into Playwright \`expect(...)\` candidates — see step 5. You do **not** need to call \`browser_blueprint_diff\` here — that tool is only for cross-URL comparisons. An empty delta (all arrays empty) is itself a meaningful signal: the action did not change observable DOM (e.g. a silent failure the test should catch).
-       - **Navigated to a new URL** (e.g. router transition, link click, programmatic \`browser_navigate\`): \`{ isFullCapture: true, pageHash, blueprint }\` — a fresh full capture of the new page. No \`possibleAssertions\` here (no delta to translate). If you need a structured cross-URL diff, call \`browser_blueprint_diff(beforeBlueprint, afterBlueprint)\` explicitly; otherwise search the new blueprint for the elements your assertion will target.
+       - **Same URL (modal/tab/in-place mutation):** \`{ isFullCapture: false, pageHash, previousPageHash, delta, possibleAssertions }\`. The \`delta\` field contains \`elementsAdded\`, \`elementsRemoved\`, \`textChanges\`, \`repeatingCountChanges\`. The \`possibleAssertions\` field is a mechanical translation of those entries into Playwright \`expect(...)\` candidates — see step 5. An empty delta (all arrays empty) is itself a meaningful signal: the action did not change observable DOM (e.g. a silent failure the test should catch).
+       - **Navigated to a new URL** (e.g. router transition, link click, programmatic \`browser_navigate\`): \`{ isFullCapture: true, pageHash, blueprint }\` — a fresh full capture of the new page. No \`possibleAssertions\` here (no delta to translate). Search the new blueprint for the elements your assertion will target.
+
+    5. **The second \`browser_blueprint\` response (the capture after the action) includes a \`possibleAssertions[]\` array — mechanical translations of delta entries into ready-to-use Playwright \`expect(...)\` candidates.** Each entry has \`{ code, rationale, tier }\`. Use tier to drive your assertion choices:
+
+       - **HIGH** — always assert on these. HIGH candidates translate state-observable changes: text content that updated (\`toHaveText\`), URL transitions (\`toHaveURL\`), count changes (\`toHaveCount\`). If a HIGH-tier candidate exists after an action, it is the primary assertion for that action. (If you followed the stable-state rule above and waited for real data before capturing, HIGH candidates will already contain real values — not loading state.)
+       - **MEDIUM** — use as supplementary assertions. MEDIUM candidates translate structural changes: an element appeared (\`toBeVisible\`) or disappeared (\`not.toBeVisible\`) after the action. Useful alongside HIGH assertions but insufficient alone for state-changing actions.
+       - **LOW** — treat as context only. LOW candidates are incidental visibility checks on elements that happened to be on-page. Do not use LOW candidates as the sole assertion on a state-changing action.
+
+       **If no HIGH-tier candidate exists after a state-changing action** (form submit, button click that mutates data), write a targeted assertion yourself — look in the second blueprint capture for computed values, status fields, or derived text that changed. One well-targeted \`toHaveText\` or \`toHaveValue\` beats five \`toBeVisible\` checks.
 
-    5. **The AFTER response includes a \`possibleAssertions[]\` array — these are mechanical translations of delta entries into Playwright \`expect(...)\` candidates, available if any of them happen to match the assertion you'd write anyway.** Each entry has \`{ code, rationale, tier }\` where \`code\` is ready-to-use, \`rationale\` explains the source delta entry, and \`tier\` is HIGH/MEDIUM/LOW. **Read them, but do not feel obligated to use them.** They are heavily biased toward visibility checks (\`toBeVisible\` / \`not.toBeVisible\`), which are often shallow assertions — a passing visibility check does not mean the feature works. The right assertion target depends on what the test is *for*: if you're testing a state-changing action (form submit, button click that mutates data), prefer assertions on the post-action state (computed values, count changes, server-derived fields). Use a \`possibleAssertions\` candidate when its \`code\` already expresses what you would have written; ignore the array entirely when none of the candidates match the test's actual purpose. Adding visibility assertions just because they're available reduces test value; one well-targeted assertion beats five visibility checks of incidental DOM elements (modal scaffolding, navigation chrome). The pre-existing rule still applies: **at least one \`browser_assert\` per page navigated, verifying a business outcome — not just that an element is visible.**
+       **The pre-existing rule still applies:** at least one \`browser_assert\` per page navigated, verifying a business outcome — not just that an element is visible.
 
   **The Blueprint Citation Invariant applies during recording too.** Every assertion you emit cites element names — those names must come from blueprint captures, not invention. For N user-intent-level actions, the reference target is N+1 \`browser_blueprint\` calls (the first returns full, the rest return deltas). Traces that follow the pattern produce assertions grounded in observable state changes; traces that skip captures fall back to author-inferred assertions and risk citing names that don't exist in the rendered DOM.
 
@@ -299,7 +462,7 @@ Do NOT use \`page.waitForTimeout()\` with fixed delays. Do NOT retry more than o
 **After generation, you MUST do exactly these steps — nothing more, nothing less:**
 1. **[MANDATORY] After \`skyramp_integration_test_generation\`**: Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated integration test file, \`testType: "integration"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.
 2. **[MANDATORY] After \`skyramp_contract_test_generation\` with \`providerMode\`**: Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated provider contract test file, \`testType: "contract"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.
-3. **[MANDATORY] After \`skyramp_ui_test_generation\`**: Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated UI test file, \`testType: "ui"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.
+3. **[MANDATORY] After \`skyramp_ui_test_generation\`**: Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated UI test file, \`testType: "ui"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file. The HIGH-tier \`possibleAssertions\` from your second \`browser_blueprint\` captures (after each action) during trace recording are in your context — when the enhance instructions ask you to add assertions for state-changing actions, use those grounded candidates first (they contain exact computed values from the DOM delta, e.g. \`toHaveText('Total: $899.98')\`). Only fall back to deriving values from the test file or source code when no HIGH-tier candidate covers the action.
 4. **Wait**: Do NOT proceed to test execution until steps 1–3 are complete and the verification checklist in the \`skyramp_enhance_assertions\` tool result has been validated for EVERY generated test file.
 Do not make any changes other than the assertion enhancements described above. For example: do not modify auth headers, cookies, tokens, env vars, or imports that the generation tool already set correctly — those are correct by construction and changing them breaks auth or execution.
 
@@ -336,6 +499,7 @@ Call \`skyramp_submit_report\` with \`summaryOutputFile\`: "${summaryOutputFile}
 - **additionalRecommendations**: AT MOST ${maxRecommendations - maxGenerate} items.
   - For \`testType: "contract"\` entries: **\`primaryEndpoint\` is required** (e.g. \`"GET /api/v1/users/{user_id}"\`). The tool will reject the submission without it — do not omit it or you will be forced to resubmit.
   - For \`testType: "integration"\` or \`"e2e"\` entries: omit \`primaryEndpoint\` — use \`description\` to list the endpoints involved instead.
+- **testMaintenance**: Use \`[]\` **only** if no existing Skyramp tests were found in the repository. If existing tests were found (any score), include one entry per test. Set \`action\` to the exact drift action you chose from the Action Decision Matrix (\`UPDATE\`, \`REGENERATE\`, \`DELETE\`, \`VERIFY\`, or \`IGNORE\`). For UPDATE/REGENERATE/DELETE tests that were modified and executed, populate all fields from real before/after execution results. For VERIFY/IGNORE tests (not modified), derive \`beforeStatus\` from the \`skyramp_analyze_test_health\` health score (typically \`"Pass"\` if drift score is 0 and no health issues were flagged), set \`afterStatus\` to \`"Skipped"\`, and use \`afterDetails\` to explain why (e.g. "IGNORE: drift score 0 — endpoint not modified in this PR"). Do **not** add entries for tests that were not returned by the health analysis.
 
 ---
 

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

@@ -0,0 +1 @@
+export {};

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

@@ -1,13 +1,14 @@
-jest.mock("../../workspace/workspace.js", () => ({
+import { jest } from "@jest/globals";
+jest.unstable_mockModule("../../workspace/workspace.js", () => ({
     WorkspaceConfigManager: jest.fn(),
 }));
-jest.mock("../../services/AnalyticsService.js", () => ({
+jest.unstable_mockModule("../../services/AnalyticsService.js", () => ({
     AnalyticsService: { pushMCPToolEvent: jest.fn() },
 }));
-jest.mock("../../playwright/traceRecordingPrompt.js", () => ({
+jest.unstable_mockModule("../../playwright/traceRecordingPrompt.js", () => ({
     getTraceRecordingPromptText: () => "",
 }));
-import { getTestbotPrompt } from "./testbot-prompts.js";
+const { getTestbotPrompt, buildWorkspaceRecoveryPrefix } = await import("./testbot-prompts.js");
 // Minimal args to invoke getTestbotPrompt — only services matter for these tests
 const baseArgs = {
     prTitle: "Test PR",
@@ -216,13 +217,11 @@ describe("drift analysis — runtime tool call (step 3)", () => {
         const prompt = basePrompt();
         expect(prompt).toContain("skyramp_actions");
     });
-    it("step 3 appears inside Task 1, before Task 2", () => {
+    it("skyramp_analyze_test_health is referenced in the prompt", () => {
+        // After the unified maintenance refactor, analyze_test_health is referenced
+        // in the testMaintenance submission guidance rather than as an explicit step.
         const prompt = basePrompt();
-        const task1Pos = prompt.indexOf("## Task 1");
-        const healthPos = prompt.indexOf("skyramp_analyze_test_health");
-        const task2Pos = prompt.indexOf("## Task 2");
-        expect(healthPos).toBeGreaterThan(task1Pos);
-        expect(healthPos).toBeLessThan(task2Pos);
+        expect(prompt).toContain("skyramp_analyze_test_health");
     });
     it("does not contain the build-time embedded drift_analysis_rules content (Action Decision Tree)", () => {
         // The rules are now fetched at runtime via skyramp_analyze_test_health —
@@ -237,57 +236,7 @@ describe("drift analysis — runtime tool call (step 3)", () => {
         expect(prompt).not.toContain("You are acting as a Skyramp Integration Architect");
     });
 });
-describe("UI grounding via Task 2 capture-act-capture", () => {
-    it("surfaces uiContext as guidance, not a contract", () => {
-        const prompt = getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath);
-        // uiContext fields are explained inline so the agent knows what to do with
-        // them. Step 1 provides candidate URLs but gives fallback instructions
-        // ("navigate from the workspace baseUrl and explore") for 404s/redirects,
-        // treating candidates as guidance not a rigid contract.
-        expect(prompt).toContain("uiContext");
-        expect(prompt).toContain("candidateUiPages");
-        expect(prompt).toContain("changedFrontendFiles");
-        expect(prompt).toMatch(/navigate from the workspace baseUrl and explore/i);
-    });
-    it("step 5 enforces Blueprint Citation Invariant in natural prose", () => {
-        const prompt = getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath);
-        // Step 5 is the citation-invariant guardrail, not a "fill in tuples"
-        // post-processing step (slice 4 cleanup: recs are grounded upstream).
-        expect(prompt).toContain("Blueprint Citation Invariant");
-        // Reasoning must be natural prose, NOT internal-identifier syntax.
-        expect(prompt).toMatch(/natural prose/i);
-        expect(prompt).toMatch(/internal-identifier syntax/i);
-    });
-    it("Task 2 no longer instructs the agent to fill in tuples post-hoc", () => {
-        const prompt = getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath);
-        // After slice 4 cleanup: Task 2 captures are for trace recording's own
-        // assertions, not for retroactively rewriting recommendation reasoning.
-        // The phrase "fill in tuples" must NOT appear anywhere in the prompt.
-        expect(prompt).not.toMatch(/fill in tuples/i);
-        expect(prompt).not.toMatch(/return to step 5 and fill/i);
-    });
-    it("Task 2 step 5 mentions possibleAssertions as available, NOT as required (slice 5.5 softening)", () => {
-        const prompt = getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath);
-        // Slice 5: AFTER-action browser_blueprint response includes
-        // possibleAssertions[] — mechanically translated candidates.
-        expect(prompt).toContain("possibleAssertions");
-        // Slice 5.5: prompt explicitly tells the agent NOT to feel obligated.
-        // Two P09 runs with the prior "emit at least one" directive showed the
-        // agent over-using shallow visibility assertions at the expense of
-        // integration-test depth. The softened version says: read them, use
-        // when they happen to match what you'd write anyway, ignore otherwise.
-        expect(prompt).toMatch(/do not feel obligated/i);
-        expect(prompt).toMatch(/biased toward visibility/i);
-        // The candidate format is still documented.
-        expect(prompt).toMatch(/\bcode\b.*\brationale\b.*\btier\b/i);
-        // The pre-existing "at least one browser_assert per page navigated"
-        // rule should be preserved (it's about meaningful business-outcome
-        // assertions, not about possibleAssertions).
-        expect(prompt).toMatch(/at least one .browser_assert. per page navigated/i);
-    });
-});
 describe("buildWorkspaceRecoveryPrefix", () => {
-    const { buildWorkspaceRecoveryPrefix } = require("./testbot-prompts.js");
     it("includes repositoryPath in both init_scan and init_workspace instructions", () => {
         const prefix = buildWorkspaceRecoveryPrefix("/home/user/repo");
         expect(prefix).toContain('skyramp_init_scan with workspacePath "/home/user/repo"');
@@ -348,20 +297,13 @@ describe("testsRepoDir in getTestbotPrompt", () => {
     });
 });
 describe("testbot prompt blueprint-grounded recommendations (slice 4)", () => {
-    it("instructs the agent to call skyramp_ui_analyze_changes before skyramp_analyze_changes", () => {
-        const prompt = getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath);
-        const uiacIdx = prompt.indexOf("skyramp_ui_analyze_changes");
-        const acIdx = prompt.indexOf("skyramp_analyze_changes");
-        expect(uiacIdx).toBeGreaterThan(-1);
-        expect(acIdx).toBeGreaterThan(uiacIdx);
-    });
-    it("Task 1 step 1 instructs the agent to capture blueprints (without threading them through a param)", () => {
+    it("uses a single skyramp_analyze_changes call (no separate pre-flight tool, no blueprint threading)", () => {
         const prompt = getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.summaryOutputFile, baseArgs.repositoryPath);
-        // Captures stay in tool-result history; analyze_changes returns the
-        // authoring rules and the agent supplies the captured vocabulary.
-        expect(prompt).toMatch(/browser_blueprint`?\s*to capture/i);
-        expect(prompt).toMatch(/tool-result history/i);
-        // Make sure we removed the old capturedBlueprints threading directive.
+        // The standalone pre-flight tool is gone — its work folded into analyze_changes.
+        expect(prompt).not.toContain("skyramp_ui_analyze_changes");
+        expect(prompt).toContain("skyramp_analyze_changes");
+        // Captures stay in tool-result history — the old capturedBlueprints
+        // threading directive must be gone.
         expect(prompt).not.toMatch(/capturedBlueprints/);
     });
     // Flutter support — both the generalised UI trigger wording and the

package/build/resources/analysisResources.d.ts

@@ -0,0 +1,17 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const ANALYSIS_URI_PREFIX = "skyramp://analysis";
+/**
+ * Register MCP Resources for analysis data access.
+ *
+ * Resources provide read-only, token-efficient access to analysis data
+ * via sessionId. The state file is an internal backing store.
+ *
+ * URI scheme:
+ *   skyramp://analysis/{sessionId}/summary
+ *   skyramp://analysis/{sessionId}/endpoints
+ *   skyramp://analysis/{sessionId}/endpoints/{+path}
+ *   skyramp://analysis/{sessionId}/endpoints/{+path}/{method}
+ *   skyramp://analysis/{sessionId}/scenarios
+ *   skyramp://analysis/{sessionId}/diff
+ */
+export declare function registerAnalysisResources(server: McpServer): void;

package/build/resources/progressResource.d.ts

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

package/build/resources/testbotResource.d.ts

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

package/build/services/AnalyticsService.d.ts

@@ -0,0 +1,13 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare class AnalyticsService {
+    static pushTestGenerationToolEvent(toolName: string, result: CallToolResult, params: Record<string, any>): Promise<void>;
+    static pushMCPToolEvent(toolName: string, result: CallToolResult | undefined, params: Record<string, string>): Promise<void>;
+    /**
+     * Track server crash events
+     */
+    static pushServerCrashEvent(crashType: string, errorMessage: string, errorStack?: string): Promise<void>;
+    /**
+     * Track tool timeout events
+     */
+    static pushToolTimeoutEvent(toolName: string, timeoutMs: number, params: Record<string, string>): Promise<void>;
+}

package/build/services/AnalyticsService.test.d.ts

@@ -0,0 +1 @@
+export {};