@skyramp/mcp 0.2.6 → 0.2.150-rc.mntnc

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

@@ -1,10 +1,11 @@
-jest.mock("@skyramp/skyramp", () => ({
+import { jest } from "@jest/globals";
+import { TestType } from "../../types/TestTypes.js";
+jest.unstable_mockModule("@skyramp/skyramp", () => ({
     WorkspaceConfigManager: { create: jest.fn() },
 }));
-import { TestType } from "../../types/TestTypes.js";
-import { buildRecommendationPrompt, buildExternalCoverageSet, externalDedupKey } from "./test-recommendation-prompt.js";
-import { buildExecutionPlan } from "./diffExecutionPlan.js";
-import { PATH_PARAM_UUID_GUIDANCE, MAX_TESTS_TO_GENERATE, buildTestQualityCriteria, buildArchitectPreamble, buildContextFetchingGuidance, buildReasoningProtocol, buildFewShotExamples, buildVerificationChecklist, } from "./recommendationSections.js";
+const { buildRecommendationPrompt, buildExternalCoverageSet, externalDedupKey } = await import("./test-recommendation-prompt.js");
+const { buildExecutionPlan } = await import("./diffExecutionPlan.js");
+const { PATH_PARAM_UUID_GUIDANCE, MAX_TESTS_TO_GENERATE, buildTestQualityCriteria, buildArchitectPreamble, buildContextFetchingGuidance, buildReasoningProtocol, buildFewShotExamples, buildVerificationChecklist, } = await import("./recommendationSections.js");
 import { AnalysisScope } from "../../types/RepositoryAnalysis.js";
 // ---------------------------------------------------------------------------
 // Minimal fixtures
@@ -1669,100 +1670,6 @@ describe("externalDedupKey", () => {
         expect(externalDedupKey(scenario)).toBe("POST::orders::contract");
     });
 });
-describe("UI grounding guidance (Phase C D-1.a)", () => {
-    const editOrderScenario = minimalScenario({
-        scenarioName: 'edit-order',
-        description: 'edit order',
-        category: 'new_endpoint',
-        priority: 'medium',
-        steps: [
-            { order: 1, method: 'PATCH', path: '/api/v1/orders/{id}', description: 'edit', interactionType: 'success', expectedStatusCode: 200 },
-        ],
-        chainingKeys: [],
-    });
-    const uiGroundingBusinessContext = {
-        mainPurpose: "Test API", userFlows: [], dataFlows: [], integrationPatterns: [],
-        draftedScenarios: [editOrderScenario],
-    };
-    const uiOnlyAnalysis = () => minimalAnalysis({
-        branchDiffContext: {
-            currentBranch: "feature", baseBranch: "main",
-            changedFiles: ['frontend/src/components/EditOrder.tsx'],
-            newEndpoints: [],
-            modifiedEndpoints: [],
-            affectedServices: [],
-        },
-        businessContext: uiGroundingBusinessContext,
-    });
-    const mixedAnalysis = () => minimalAnalysis({
-        branchDiffContext: {
-            currentBranch: "feature", baseBranch: "main",
-            changedFiles: ['frontend/src/components/EditOrder.tsx', 'backend/orders.py'],
-            newEndpoints: [{
-                    path: '/api/v1/orders/{id}',
-                    methods: [{ method: 'PATCH', sourceFile: 'backend/orders.py', interactionCount: 1 }],
-                }],
-            modifiedEndpoints: [],
-            affectedServices: [],
-        },
-        businessContext: uiGroundingBusinessContext,
-    });
-    const backendOnlyAnalysis = () => minimalAnalysis({
-        branchDiffContext: {
-            currentBranch: "feature", baseBranch: "main",
-            changedFiles: ['backend/orders.py'],
-            newEndpoints: [{
-                    path: '/api/v1/orders',
-                    methods: [{ method: 'POST', sourceFile: 'backend/orders.py', interactionCount: 1 }],
-                }],
-            modifiedEndpoints: [],
-            affectedServices: [],
-        },
-        businessContext: uiGroundingBusinessContext,
-    });
-    it("emits UI grounding block on UI-only PRs", () => {
-        const out = buildRecommendationPrompt(uiOnlyAnalysis(), AnalysisScope.CurrentBranchDiff, 10);
-        expect(out).toContain("UI recommendation grounding");
-        expect(out).toContain("role=<role>");
-        expect(out).toContain("accessibleName=");
-    });
-    it("emits UI grounding block on mixed PRs", () => {
-        const out = buildRecommendationPrompt(mixedAnalysis(), AnalysisScope.CurrentBranchDiff, 10);
-        expect(out).toContain("UI recommendation grounding");
-        expect(out).toContain("contextText=");
-    });
-    it("does not emit UI grounding block on backend-only PRs", () => {
-        const out = buildRecommendationPrompt(backendOnlyAnalysis(), AnalysisScope.CurrentBranchDiff, 10);
-        expect(out).not.toContain("UI recommendation grounding");
-    });
-    it("carves out non-UI entries from the grounding format", () => {
-        const out = buildRecommendationPrompt(mixedAnalysis(), AnalysisScope.CurrentBranchDiff, 10);
-        expect(out).toMatch(/Contract, integration, e2e.*existing conventions/);
-    });
-    it("includes contextText example for repeating elements", () => {
-        const out = buildRecommendationPrompt(uiOnlyAnalysis(), AnalysisScope.CurrentBranchDiff, 10);
-        expect(out).toContain('contextText=["customer@example.com"');
-    });
-    // Phase C D-1.a/7b: directive instruction strengthening + Validates coverage
-    // + marked fallback. Asserts the post-7b language is present.
-    it("uses MUST directive for tuple presence in reasoning field", () => {
-        const out = buildRecommendationPrompt(uiOnlyAnalysis(), AnalysisScope.CurrentBranchDiff, 10);
-        expect(out).toContain("MUST contain at least three of");
-        expect(out).toContain("not valid output for UI test types");
-    });
-    it("instructs the agent to ground the Validates line for UI entries", () => {
-        const out = buildRecommendationPrompt(uiOnlyAnalysis(), AnalysisScope.CurrentBranchDiff, 10);
-        expect(out).toContain("Validates line — applies to");
-        expect(out).toContain("observable behavior the test verifies");
-        expect(out).toContain("structural facts");
-    });
-    it("requires a [no-blueprint-data] marker on source-grounded fallback entries", () => {
-        const out = buildRecommendationPrompt(uiOnlyAnalysis(), AnalysisScope.CurrentBranchDiff, 10);
-        expect(out).toContain("[no-blueprint-data]");
-        expect(out).toContain("issuesFound");
-        expect(out).toContain("Do NOT silently produce ungrounded reasoning");
-    });
-});
 // ---------------------------------------------------------------------------
 // Tests — UI recommendation authoring rules
 // ---------------------------------------------------------------------------

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

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

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

@@ -18,11 +18,8 @@ const CONTRACT_MODE_GUIDANCE = CONSUMER_MODE_ENABLED
   Both modes (\`providerMode: true, consumerMode: true\`): For diff that contains BOTH provider signals (such as new/modified endpoint handlers, route changes this service owns) AND consumer signals (outbound HTTP client calls to another service, no new endpoint handlers).`
     : `  Always add \`providerMode: true\` — the tool generates provider-side contract tests only.`;
 export function getTestbotPrompt(prTitle, prDescription, summaryOutputFile, repositoryPath, baseBranch, maxRecommendations = MAX_RECOMMENDATIONS, maxGenerate = MAX_TESTS_TO_GENERATE, _maxCritical = MAX_CRITICAL_TESTS, // Reserved — accepted for API compat but not yet wired into prompt
-prNumber, userPrompt, services, stateOutputFile, uiCredentials, testsRepoDir) {
+prNumber, userPrompt, services, uiCredentials, testsRepoDir) {
     maxGenerate = Math.min(Math.max(maxGenerate, 0), maxRecommendations);
-    // 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
@@ -44,7 +41,7 @@ Verify the prompt inside <USER_PROMPT> is related to adding or removing tests fr
 - If the prompt matches one or more tests in the Additional Recommendations → proceed to Task 1 (Skip Analysis).
 
 ### Task 1: Retrieve Previous Recommendations
-Call \`skyramp_analyze_changes\` with \`repositoryPath\`: "${repositoryPath}", \`scope\`: "branch_diff"${baseBranch ? `, \`baseBranch\`: "${baseBranch}"` : ""}${prNumber ? `, \`prNumber\`: ${prNumber}` : ""}${stateOutputFile ? `, \`stateOutputFile\`: "${stateOutputFile}"` : ""}${testsRepoDir ? `, \`testsRepoDir\`: "${testsRepoDir}"` : ""}.
+Call \`skyramp_analyze_changes\` with \`repositoryPath\`: "${repositoryPath}", \`scope\`: "branch_diff"${baseBranch ? `, \`baseBranch\`: "${baseBranch}"` : ""}${prNumber ? `, \`prNumber\`: ${prNumber}` : ""}${testsRepoDir ? `, \`testsRepoDir\`: "${testsRepoDir}"` : ""}.
 This will fetch the previous TestBot report from the PR comments and return deduplicated recommendations.
 Use those recommendations as your baseline. Only add or remove tests that the user requested AND that appear in the Additional Recommendations. Then proceed straight to Task 2: Generate New Tests.
 `
@@ -53,27 +50,27 @@ 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}` : ""}${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.
 
    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.
+   c. Call \`skyramp_execute_test\` with \`phase: "before"\` and \`stateFile\` for every test whose action is UPDATE or REGENERATE. Run them in parallel. This captures the pre-edit baseline — do not skip even if you expect the test to fail.
 
-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:
+   d. Call \`skyramp_actions\` with \`stateFile\` (from \`skyramp_analyze_changes\` output) and apply the edits it returns.
+
+3. **Code review:** From the \`skyramp_analyze_changes\` output and the existing test files you read for maintenance, note any logic bugs. Do NOT read additional source files just for code review — use what is already available from the analysis and test file reads. Common patterns to flag:
    - Computed fields not recalculated after mutation (e.g. \`total_amount\` unchanged after items are added/removed)
    - Incomplete CRUD: create without cleanup, update that adds new records without removing old ones
    - Missing input validation on new endpoints
@@ -81,15 +78,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 +282,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.
@@ -131,7 +291,7 @@ ${userPrompt ? "Generate only the tests that the user requested from the Additio
 - Example: If enrichment reveals that sending \`discount_value\` without \`discount_type\` silently orphans the value (a concrete bug), complete all planned GENERATE items first, then generate this discovered scenario as an extra test and report it in \`newTestsCreated\`.
 - Total generated: Follow the "Budget: N generate" line in the Execution Plan. Process every GENERATE-tagged item in order. Backfill from ADDITIONAL candidates (highest-ranked first) until \`newTestsCreated\` reaches ${maxGenerate} or all candidates are exhausted.
 - **UI test priority**: If the PR scope assessment shows any UI/E2E budget OR \`uiContext.changedFrontendFiles\` is non-empty (the deterministic server signal — populated for all supported frontend file types including \`.tsx\`/\`.jsx\`/\`.vue\`/\`.svelte\`/\`.dart\`), you MUST attempt to generate at least one UI test. Use \`browser_navigate\` to the app's base URL — if the app responds, record a trace and generate the test.
-  **Flutter web apps:** Skyramp's Playwright tools automatically enable Flutter's accessibility semantics tree on every \`browser_navigate\` call — you do NOT need to manually click \`flt-semantics-placeholder\` or add any activation step to the trace. Do NOT log an \`issuesFound\` entry about Flutter canvas rendering or accessibility activation — this is handled transparently. **Do NOT skip test generation or abstain from recording based on what you see in the Flutter source code** (e.g. \`SemanticsBinding.ensureSemantics()\` commented out, \`IS_TESTING\` flag absent, or similar) — Skyramp enables accessibility from the browser side regardless of the app's Dart code. Proceed with \`browser_navigate\` and test recording as normal.
+  **Flutter web apps:** Skyramp's Playwright tools automatically enable Flutter's accessibility semantics tree on every \`browser_navigate\` call — you do NOT need to manually click \`flt-semantics-placeholder\` or add any activation step to the trace. Do NOT log an \`issuesFound\` entry about Flutter canvas rendering or accessibility activation — this is handled transparently. **Do NOT skip test generation or abstain from recording based on what you see in the Flutter source code** (e.g. \`SemanticsBinding.ensureSemantics()\` commented out, \`IS_TESTING\` flag absent, or similar) — Skyramp enables accessibility from the browser side regardless of the app's Dart code. Proceed with \`browser_navigate\` and test recording as normal. **Start at the app's root URL** (e.g. \`{baseUrl}/\`) — do NOT \`browser_navigate\` straight to a deep sub-route (e.g. \`/authors\`, \`/orders/13\`). Flutter \`go_router\` SPAs route from the root: deep-linking on a cold page load often fails to render the expected screen (the route's widgets never mount, so the trace captures the wrong page). Load the root, let the app's own routing/auth-redirect render, then reach target screens by interaction. **After the initial login, navigate using in-app controls only** (tab buttons, links, back buttons) — do NOT call \`browser_navigate\` to a different URL after login. Flutter web apps are SPAs: a \`browser_navigate\` to a new URL after login triggers a full page reload which clears the auth session, causing redundant re-login cycles in the generated test. Use button clicks to reach target screens instead.
   **Skip only if one of these conditions is met:**
   - **(a) App is unreachable** — \`browser_navigate\` fails or connection is refused.
   - **(b) Unintegrated non-route component** — the changed file is a leaf component (not a framework route/entrypoint) that has no integration point in the running app. To confirm:
@@ -139,7 +299,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 +385,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 +398,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 +414,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 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.**
+    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.
+
+       **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,13 +467,11 @@ 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.
 
-**Execution timing:**
-- **beforeStatus** (maintained tests only): execute each maintained test file **once at the start** (before any edits) to capture \`beforeStatus\`. This is the only execution allowed before edits.
-- **Final execution**: Do NOT call \`skyramp_execute_test\` again until ALL maintenance edits AND ALL new test generation/enhancement are complete. Then execute every test file once — maintained files (for \`afterStatus\`) and new files together. Run independent files in parallel (same tool call batch).
+**Final execution (mandatory):** Do NOT call \`skyramp_execute_test\` until ALL maintenance edits AND ALL new test generation/enhancement are complete.
 - Only report test results for files you actually ran.
 **Auth**: If \`skyramp_analyze_changes\` reports an auth token or \`SKYRAMP_TEST_TOKEN\` is set, pass it in **every** \`skyramp_execute_test\` call from the first attempt — do NOT wait for a 401/403 to discover auth is needed.
 
@@ -331,15 +497,24 @@ In these cases:
 
 Otherwise: in \`newTestsCreated\`, you must have exactly ${maxGenerate} budget-counting new tests for the planned GENERATE items. Only new files (ADD) created for those planned GENERATE items count toward this ${maxGenerate} target — GENERATE items converted to UPDATE do not. You may also include at most one additional discovered-scenario file in \`newTestsCreated\` (the bug-catching test generated after all planned items); that extra test does **not** count against the ${maxGenerate} budget. If you have fewer than ${maxGenerate} budget-counting new tests, backfill from the remaining ADDITIONAL candidates before proceeding. Only proceed with fewer than ${maxGenerate} budget-counting new tests if all candidates failed after retry AND the fallback single-contract test also failed.
 
-Call \`skyramp_submit_report\` with \`summaryOutputFile\`: "${summaryOutputFile}". Field names, types, and formats are defined in the tool's parameter schema — follow them exactly.
+Call \`skyramp_submit_report\` with \`summaryOutputFile\`: "${summaryOutputFile}" and \`stateFile\` (from \`skyramp_analyze_changes\` output) — the stateFile is required for execution outcome tracking. Field names, types, and formats are defined in the tool's parameter schema — follow them exactly.
 
 - **additionalRecommendations**: AT MOST ${maxRecommendations - maxGenerate} items.
   - For \`testType: "contract"\` entries: **\`primaryEndpoint\` is required** (e.g. \`"GET /api/v1/users/{user_id}"\`). The tool will reject the submission without it — do not omit it or you will be forced to resubmit.
   - For \`testType: "integration"\` or \`"e2e"\` entries: omit \`primaryEndpoint\` — use \`description\` to list the endpoints involved instead.
+- **testMaintenance**: Use \`[]\` **only** if no existing Skyramp tests were found in the repository. If existing tests were found (any score), include one entry per test. Set \`action\` to the exact drift action you chose from the Action Decision Matrix (\`UPDATE\`, \`REGENERATE\`, \`DELETE\`, \`VERIFY\`, or \`IGNORE\`). For UPDATE/REGENERATE/DELETE tests that were modified and executed, populate \`beforeDetails\` and \`afterDetails\` from what you observed in \`skyramp_execute_test\` output — one line each, no newlines. For passing runs write the count and timing (e.g. \`"4 passed in 15.09s"\`). For failing runs write the test name and failure reason (e.g. \`"1 failed: test_foo - assert X == Y — shared-state pollution"\`). For VERIFY/IGNORE tests (not modified), omit \`beforeDetails\` and \`afterDetails\`. Do **not** add entries for tests that were not returned by the health analysis.
+- **testResults**: For UI/E2E test entries, include the \`videoPath\` field if \`skyramp_execute_test\` returned one.
 
 ---
 
 ${getTraceRecordingPromptText({ outputDir: `${repositoryPath}/.skyramp`, modularize: false })}`;
+    // TODO: merge stateFile and summaryOutputFile into a single file (follow-up PR).
+    // Currently the stateFile path is derived server-side from RUNNER_TEMP (GitHub Actions only);
+    // other CI systems (Jenkins, GitLab, Buildkite) require the caller to set RUNNER_TEMP.
+    // Once merged, the path flows through summaryOutputFile — already testbot-controlled and
+    // CI-agnostic — eliminating the RUNNER_TEMP dependency and the LLM confusion that motivated
+    // removing stateOutputFile from the prompt schema. Remove the RUNNER_TEMP branch in
+    // AnalysisStateManager.ts when this is done.
 }
 function escapeXml(value) {
     return value
@@ -414,10 +589,6 @@ export function registerTestbotPrompt(server) {
                 .string()
                 .optional()
                 .describe("Natural language prompt from the user (via @skyramp-testbot comment) to add or remove specific recommendations."),
-            stateOutputFile: z
-                .string()
-                .optional()
-                .describe("Absolute path where skyramp_analyze_changes should write its state file. When provided, the caller can locate the file without log parsing."),
             uiCredentials: z
                 .string()
                 .optional()
@@ -433,7 +604,7 @@ export function registerTestbotPrompt(server) {
         },
     }, async (args) => {
         const services = await readWorkspaceServices(args.repositoryPath);
-        let prompt = getTestbotPrompt(args.prTitle, args.prDescription, args.summaryOutputFile, args.repositoryPath, args.baseBranch, args.maxRecommendations, args.maxGenerate, args.maxCritical, args.prNumber, args.userPrompt, services.length ? services : undefined, args.stateOutputFile, args.uiCredentials, args.testsRepoDir);
+        let prompt = getTestbotPrompt(args.prTitle, args.prDescription, args.summaryOutputFile, args.repositoryPath, args.baseBranch, args.maxRecommendations, args.maxGenerate, args.maxCritical, args.prNumber, args.userPrompt, services.length ? services : undefined, args.uiCredentials, args.testsRepoDir);
         if (args.workspaceValidationFailed) {
             prompt = buildWorkspaceRecoveryPrefix(args.repositoryPath) + prompt;
         }

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

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