@skyramp/mcp 0.3.2 → 0.3.4

package/build/index.js

@@ -45,6 +45,8 @@ import { registerProgressResource } from "./resources/progressResource.js";
 import { AnalyticsService } from "./services/AnalyticsService.js";
 import { registerInitTriggerOnMCPInitialized } from "./utils/initAgent.js";
 import { isTestbotEnabled, isLocalDevEnabled } from "./utils/featureFlags.js";
+import { findRoot, readTestIdAttribute } from "./utils/pom-scope/index.js";
+import { discoverTestIdAttribute } from "./utils/pom-scope/testIdDiscovery.js";
 import { registerPlaywrightTools, registerTraceRecordingPrompt, getPlaywrightTraceService, } from "./playwright/index.js";
 // One-click routing instructions — injected into MCP server instructions so agents
 // know to delegate to the one-click tool rather than self-orchestrating.
@@ -212,8 +214,51 @@ if (isTestbotEnabled()) {
     logger.info("Testbot tools enabled via SKYRAMP_FEATURE_TESTBOT");
 }
 infrastructureTools.forEach((registerTool) => registerTool(server));
-// Register Playwright browser tools (trace recording via browser automation)
-registerPlaywrightTools(server).catch((err) => {
+// Register Playwright browser tools (trace recording via browser automation).
+//
+// Tell the capture which attribute this repository uses for test ids. Without
+// it the capture assumes Playwright's `data-testid`, and a repo using anything
+// else gets no test-id anchor and a positional xpath for every element — which
+// resolves at capture time and breaks later, so the miss never announces itself
+// (SKYR-4136). This server is the only component that knows which repository it
+// is running against.
+//
+// A declared `use.testIdAttribute` is authoritative. Failing that, the
+// repository's own tests name the attribute whenever they select on it, so read
+// it out of their selectors rather than guessing from a list of popular names.
+// Never fatal: no answer leaves the capture on Playwright's default.
+(async () => {
+    let testIdAttribute;
+    try {
+        const root = await findRoot(process.cwd());
+        testIdAttribute = await readTestIdAttribute(root);
+        if (testIdAttribute) {
+            logger.info(`testIdAttribute declared by the Playwright config: ${testIdAttribute}`);
+        }
+        else {
+            const discovered = await discoverTestIdAttribute(root);
+            testIdAttribute = discovered.attribute;
+            if (testIdAttribute) {
+                // Log the runner-up counts: on a part-migrated repo the most-used
+                // attribute wins, and a wrong pick should be visible here rather than
+                // showing up later as brittle selectors.
+                logger.info(`testIdAttribute discovered from test selectors: ${testIdAttribute}`, { counts: discovered.counts, filesScanned: discovered.filesScanned });
+            }
+            else {
+                // No name rule can reach an arbitrary convention like `xyz-id`, so name
+                // what the selectors did contain and the variable that overrides it.
+                // Editing the repo's own Playwright config is the wrong instruction: a
+                // suite may have several, and none of them at the root.
+                logger.info("No testIdAttribute declared or discovered — capture stays on Playwright's data-testid. " +
+                    "Set PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE to override.", { attributesSeenInSelectors: discovered.observed, filesScanned: discovered.filesScanned });
+            }
+        }
+    }
+    catch (err) {
+        logger.warning("Could not determine this repository's testIdAttribute", { error: err });
+    }
+    await registerPlaywrightTools(server, { testIdAttribute });
+})().catch((err) => {
     logger.error("Failed to register Playwright tools", { error: err });
 });
 // Global error handlers for crash telemetry

package/build/playwright/PlaywrightTraceService.d.ts

@@ -17,6 +17,14 @@ export interface PlaywrightTraceOptions {
     headless?: boolean;
     /** Directory for output files (zip, HAR). Defaults to cwd. */
     outputDir?: string;
+    /**
+     * The attribute this repository uses for test ids, when its Playwright config
+     * declares one. Forwarded to the blueprint capture, which otherwise only
+     * recognises the common conventions and falls back to positional xpaths —
+     * brittle, and silently so. Only this server knows which repository it runs
+     * against, so only this server can supply it.
+     */
+    testIdAttribute?: string;
 }
 export declare class PlaywrightTraceService {
     private _backend;

package/build/playwright/PlaywrightTraceService.js

@@ -26,6 +26,7 @@ export class PlaywrightTraceService {
             this._backend = new TraceRecordingBackend({
                 headless: this._options.headless,
                 outputDir: this._options.outputDir || process.cwd(),
+                testIdAttribute: this._options.testIdAttribute,
             });
             // Initialize with a synthetic client info
             await this._backend.initialize({

package/build/playwright/registerPlaywrightTools.js

@@ -4,11 +4,37 @@
  */
 import { z } from "zod";
 import { logger } from "../utils/logger.js";
+import { dualChannelResult } from "../utils/utils.js";
 import { PlaywrightTraceService, } from "./PlaywrightTraceService.js";
 let _service = null;
 export function getPlaywrightTraceService() {
     return _service;
 }
+/**
+ * The one browser tool whose result is re-shaped on the way out — see
+ * toStructuredBlueprintResult.
+ */
+const BLUEPRINT_TOOL = "browser_blueprint";
+/**
+ * Re-shape a browser_blueprint result onto both MCP result channels.
+ *
+ * SKYR-4194. The browser tools are registered here as passthroughs, and the fork
+ * returns the captured DOM as one `content[]` text block with no
+ * `structuredContent` — the shape whose spill the agent's file reader refuses.
+ * See `dualChannelResult` for why both channels carry the payload.
+ *
+ * An error result is returned untouched: the SDK's outputSchema check returns
+ * early on `isError`, so it needs no structuredContent.
+ */
+function toStructuredBlueprintResult(result) {
+    if (result?.isError)
+        return result;
+    const blueprint = (result?.content ?? [])
+        .filter((block) => block?.type === "text")
+        .map((block) => block.text)
+        .join("\n");
+    return dualChannelResult({ blueprint });
+}
 export async function registerPlaywrightTools(server, options) {
     _service = new PlaywrightTraceService(options);
     try {
@@ -68,9 +94,23 @@ export async function registerPlaywrightTools(server, options) {
     logger.info(`Filtering to ${filteredTools.length} essential tools (from ${tools.length} total)`);
     for (const tool of filteredTools) {
         const zodSchema = jsonSchemaToZod(tool.inputSchema);
+        const isBlueprint = tool.name === BLUEPRINT_TOOL;
         server.registerTool(tool.name, {
             description: tool.description || `Playwright tool: ${tool.name}`,
             inputSchema: zodSchema,
+            // SKYR-4194: only browser_blueprint returns its payload via
+            // structuredContent, which requires a declared outputSchema. The other
+            // browser tools return small results, and some return images, which this
+            // text-only re-shaping would drop.
+            ...(isBlueprint
+                ? {
+                    outputSchema: {
+                        blueprint: z
+                            .string()
+                            .describe("The captured PageBlueprint — sections, elements, and their logical names. Read and follow this field."),
+                    },
+                }
+                : {}),
         }, async (params) => {
             if (!_service?.isInitialized()) {
                 return {
@@ -83,7 +123,8 @@ export async function registerPlaywrightTools(server, options) {
                     isError: true,
                 };
             }
-            return _service.callTool(tool.name, params);
+            const result = await _service.callTool(tool.name, params);
+            return isBlueprint ? toStructuredBlueprintResult(result) : result;
         });
     }
     logger.info(`Registered ${filteredTools.length} Playwright tools: ${filteredTools.map((t) => t.name).join(", ")}`);

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

@@ -154,6 +154,25 @@ expect(getResponseValue(productsPostResponse, "created_at")).toMatch(/^\\d{4}-\\
             },
         ],
     },
+    {
+        title: "Assert a nullable field is present, not merely null",
+        description: "Reading a field's value cannot tell a null field from a missing one — `get_response_value` / `getValue` return the same result for both, so `is None` does not prove the field exists. Use a schema check with an example body instead.",
+        subPoints: [
+            "An example carrying `null` for the field asserts presence and nullness together, and fails when the field is absent.",
+            "An example carrying a concrete value only asserts that value's type, so a nullable field checked against a string example fails once the real value is null.",
+            "`check_schema` / `checkSchema` takes the RESPONSE OBJECT, not a parsed body. The `@skyramp/skyramp` type declaration says otherwise and is wrong — passing a plain object makes every check silently return false (SKYR-4189).",
+        ],
+        examples: [
+            {
+                language: "python",
+                code: `assert skyramp.check_schema(order_response, '{"cancelled_at": null}')`,
+            },
+            {
+                language: "javascript",
+                code: `expect(checkSchema(orderResponse, '{"cancelled_at": null}')).toBe(true);`,
+            },
+        ],
+    },
 ];
 export function renderRule(index, rule) {
     const subPoints = rule.subPoints && rule.subPoints.length > 0

package/build/prompts/pom-aware-code-reuse.js

@@ -1,5 +1,9 @@
 import { generateSkyrampHeader, SKYRAMP_UTILS_HEADER } from "../utils/utils.js";
+import { resolvePomCatalogPath } from "../utils/pom-catalog.js";
 export function getPomAwareCodeReusePrompt(testFile, language = "typescript", scopedPoms) {
+    // Resolved here, not left to the agent: the catalog only survives to the next
+    // run if it lands where delivery stages it (SKYR-4141).
+    const catalogPath = resolvePomCatalogPath(testFile);
     const isJs = language.toLowerCase() === "javascript";
     const ext = isJs ? "js" : "ts";
     const utilsFile = isJs ? "skyrampUtils.js" : "skyrampUtils.ts";
@@ -27,8 +31,6 @@ ${scopedPoms.tier2.map(renderPom).join("\n") || "(none)"}
 
 Do NOT glob or scan for other POM files. Proceed to STEP 2 and catalog exactly these files (plus any file they import or extend that you find essential while reading them).
 
-**Catalog-completeness guard for STEP 2a:** when checking for an existing \`skyramp-pom-catalog.md\`, it is only valid for THIS run if it already contains an entry for EVERY file listed above. If any listed file is missing from the catalog, do NOT reuse it wholesale — keep its existing entries and generate + append entries for the missing listed files (then use the updated catalog).
-
 **Decision:** continue to STEP 2.`
         : `## STEP 1: DETECT POM CLASSES IN THE PROJECT
 
@@ -89,10 +91,13 @@ ${step1Section}
 
 **Step 2a: Check for existing catalog (MANDATORY FIRST STEP)**
 
-Look for \`skyramp-pom-catalog.md\` walking UP from the test file's directory to the repository root; use the FIRST one found (catalogs from earlier runs may live at legacy locations — a found catalog is valid wherever it lives):
-- **If it exists:** Read it and verify it starts with \`<!-- skyramp-pom-catalog: auto-generated -->\`
-  - Valid → Output: *"Using existing POM catalog from /path/to/skyramp-pom-catalog.md"* and **skip to STEP 2b**
-  - Invalid → Continue to full catalog generation below
+Read the catalog at EXACTLY this path — the one canonical location. Do not search for it anywhere else:
+
+   \`${catalogPath}\`
+
+- **If it exists:** verify it starts with \`<!-- skyramp-pom-catalog: auto-generated -->\` AND already contains an entry for EVERY POM file STEP 1 identified — the files listed in STEP 1 above, or the files your own glob found, whichever applies.
+  - Valid and complete → Output: *"Using existing POM catalog from ${catalogPath}"* and **skip to STEP 2b**
+  - Invalid, or missing an entry for any STEP 1 file → do NOT reuse it wholesale — keep its existing entries and continue to full catalog generation below, generating and appending entries only for the missing files
 - **If it doesn't exist:** Continue to full catalog generation below
 
 ---
@@ -121,10 +126,14 @@ Before writing a single line of refactored code, do the following:
      - Whether the method wraps a multi-step sequence using sub-properties or components (e.g. \`searchAssetsByCondition\` internally calls \`searchConditionArea.expandWhenClosed()\`, \`clearBtn.click()\`, \`selectItemName()\`, \`valueKeyword.fill()\`, \`searchBtn.click()\`) — flag these as **wrapping methods**
    - Flag methods as **timing-aware**, **network-aware**, or **wrapping** as appropriate — all three are high-value substitution targets
 
-4. **Write the POM catalog — MANDATORY** — Write the complete catalog to \`skyramp-pom-catalog.md\` at the CANONICAL location: the top of the configured test directory (when this run's instructions declare one containing the test file), otherwise the nearest ancestor directory of the test file that contains a \`package.json\`, otherwise the repository root. Never invent a new location per run — determinism is what lets later runs reuse this file. This gives you a clean structured reference for STEP 2b and leaves a record for debugging.
+4. **Write the POM catalog — MANDATORY** — Write the complete catalog to EXACTLY this path, already resolved for this run, creating the parent directory first if it does not already exist:
+
+   \`${catalogPath}\`
+
+   Use it verbatim — do not re-derive it, shorten it, or pick a directory that looks more natural. Delivery commits this location; a catalog written anywhere else is discarded without warning, and the next run pays full POM rediscovery. This gives you a clean structured reference for STEP 2b and leaves a record for debugging.
 
 **BLOCKING: Do not proceed to STEP 2b until you have written this file and confirmed the path in a single output line:**
-*"POM catalog written to /path/to/skyramp-pom-catalog.md"*
+*"POM catalog written to ${catalogPath}"*
 
 **Verification gate:** Before continuing to STEP 2b, confirm you either (a) found and used an existing catalog in Step 2a, OR (b) just wrote a new catalog in step 4 above. If neither is true, STOP and complete step 4 now.
 

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

@@ -15,7 +15,7 @@ export function buildFileRenameStrategy() {
 }
 /** Strategy string for in-place UPDATE edits. */
 export function buildUpdateStrategy() {
-    return `Apply each file in update_context yourself with the Edit tool, using its current_content and the changes described in context. Preserve all existing test logic — only add or adjust what context describes.
+    return `Apply each file in update_context yourself with the Edit tool. Read the file first, then make the changes described in context. Preserve all existing test logic — only add or adjust what context describes.
 
 When a file provides edit_sites, apply each site directly using its anchor as the Edit target — do not re-grep or re-page the file to relocate the sites; they were already found for you.
 
@@ -25,7 +25,7 @@ After editing, re-read each file to confirm the change landed, then call skyramp
 }
 /** Strategy string for REGENERATE — call generation tool to overwrite the file. */
 export function buildRegenerateStrategy() {
-    return `For each file in regenerate_context, call the appropriate generation tool (skyramp_integration_test_generation or skyramp_contract_test_generation) with outputDir set to the file's directory and output set to the filename. Use existing_content to determine the test type, endpoint, auth pattern, and language. The generation tool will overwrite the file. Do NOT use skyramp_ui_test_generation here — UI test regeneration requires a recorded trace (playwrightInput) and must be handled separately.`;
+    return `For each file in regenerate_context, call the appropriate generation tool (skyramp_integration_test_generation or skyramp_contract_test_generation) with outputDir set to the file's directory and output set to the filename. The generation tool will overwrite the file. Do NOT use skyramp_ui_test_generation here — UI test regeneration requires a recorded trace (playwrightInput) and must be handled separately.`;
 }
 /** Strategy string for DELETE — remove obsolete test files whose covered endpoints/UI no longer exist. */
 export function buildDeleteStrategy() {

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

@@ -347,10 +347,7 @@ Static endpoint scan results are **best-effort hints only**. Do not assume the s
 ${staticHintCount > 0 ? `Static hints available: ${staticHintCount}. Verify every hinted method/path against source before using it.` : "Static hints available: 0. Build the endpoint list from source, router context, spec, and diff."}
 
 ${p.candidateRouteFiles && p.candidateRouteFiles.length > 0
-            ? `Candidate files to inspect:\n${p.candidateRouteFiles
-                .slice(0, 15)
-                .map((f) => `- \`${f}\``)
-                .join("\n")}${p.candidateRouteFiles.length > 15 ? `\n_(${p.candidateRouteFiles.length - 15} more files not shown)_` : ""}`
+            ? ""
             : staticHintCount > 0
                 ? "Candidate files to inspect: none identified by static scanning. Verify the static hints against their source files, changed files, router context, and specs above."
                 : "Candidate files to inspect: use the changed files and routing entry-point files above."}

package/build/prompts/test-recommendation/recommendationSections.d.ts

@@ -32,4 +32,4 @@ export declare function buildTestQualityCriteria(): string;
 export declare function buildGenerationRules(isUIOnlyPR: boolean): string;
 export declare function buildVerificationChecklist(topN: number, maxGen: number, codeReviewStepLabel?: string): string;
 export declare function buildFewShotExamples(): string;
-export declare function buildToolWorkflows(authHeaderValue: string, authTypeValue?: string, explicitScheme?: string): string;
+export declare function buildToolWorkflows(authHeaderValue: string, authTypeValue?: string, explicitScheme?: string, enrichStepLabel?: string): string;

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

@@ -1,6 +1,6 @@
 import { isContractConsumerModeEnabled } from "../../utils/featureFlags.js";
 import { resolveServiceDetailsRef } from "../../utils/utils.js";
-import { WorkspaceAuthType, getAuthScheme, isAuthorizationHeaderName, AUTH_MIDDLEWARE_PATTERNS_STR } from "../../utils/workspaceAuth.js";
+import { WorkspaceAuthType, getAuthScheme, isAuthorizationHeaderName } from "../../utils/workspaceAuth.js";
 // Cached at module-load — flags are process-wide and cannot change per call.
 const CONSUMER_MODE_ENABLED = isContractConsumerModeEnabled();
 const SERVICE_REFS = resolveServiceDetailsRef();
@@ -243,7 +243,7 @@ Reasoning: Catches a missing 404 guard on DELETE — verifies the handler return
 </example>
 </examples>`;
 }
-export function buildToolWorkflows(authHeaderValue, authTypeValue = "", explicitScheme) {
+export function buildToolWorkflows(authHeaderValue, authTypeValue = "", explicitScheme, enrichStepLabel = "2") {
     const isAuthorizationHeader = isAuthorizationHeaderName(authHeaderValue);
     const noAuth = !authHeaderValue;
     let authGuidance;
@@ -251,7 +251,7 @@ export function buildToolWorkflows(authHeaderValue, authTypeValue = "", explicit
     if (noAuth) {
         authGuidance = `**Auth Verification Required:** The workspace config indicates no authentication, but you MUST verify this independently before omitting auth:
 1. **OpenAPI spec** \u2192 check \`securitySchemes\` / \`securityDefinitions\` for \`type: http\`, \`type: apiKey\`, or \`type: oauth2\`
-2. **Source code** \u2192 look for known auth signals (${AUTH_MIDDLEWARE_PATTERNS_STR}).
+2. **Source code** \u2192 look for the auth middleware signals listed in Step ${enrichStepLabel} of the Execution Plan.
 3. **Route definitions** \u2192 check if routes have auth decorators or middleware applied
 4. **Still unknown** \u2192 proceed with \`authHeader: ""\` and note "auth pattern unrecognized" in your recommendation description.
 If you find auth requirements, pass the appropriate \`authHeader\` and \`authScheme\` to EVERY tool call. Only pass \`authHeader: ""\` if you confirm the API is truly unauthenticated.
@@ -270,7 +270,7 @@ If you find auth requirements, pass the appropriate \`authHeader\` and \`authSch
             authGuidance = `**Auth Scheme:** The workspace \`api.authType\` is \`"${authTypeValue}"\`.
 **Where to find the scheme** (check in order):
 1. **OpenAPI spec** \u2192 look at \`securitySchemes\` / \`securityDefinitions\` for \`type: http, scheme: bearer\` or \`type: apiKey\`
-2. **Source code** \u2192 auth middleware signals: ${AUTH_MIDDLEWARE_PATTERNS_STR}
+2. **Source code** \u2192 the auth middleware signals listed in Step ${enrichStepLabel} of the Execution Plan
 3. **Workspace config** \u2192 use \`api.authType\` value as the scheme if source is inconclusive
 Pass the prefix as \`authScheme\` (e.g., \`"Bearer"\`, \`"Token"\`, \`"Basic"\`). If the API uses raw tokens with no prefix, pass \`authScheme: ""\`.
 **Do NOT guess the scheme.**
@@ -280,7 +280,7 @@ To skip auth entirely, pass \`authHeader: ""\`.`;
             authGuidance = `**Auth Scheme:** No \`api.authType\` in workspace config.
 **Where to find the scheme** (check in order):
 1. **OpenAPI spec** \u2192 look at \`securitySchemes\` / \`securityDefinitions\` for \`type: http, scheme: bearer\` or \`type: apiKey\`
-2. **Source code** \u2192 auth middleware signals: ${AUTH_MIDDLEWARE_PATTERNS_STR}
+2. **Source code** \u2192 the auth middleware signals listed in Step ${enrichStepLabel} of the Execution Plan
 3. **Fallback** \u2192 use \`"Bearer"\` only if the project clearly uses JWT or OAuth; otherwise pass \`authScheme: ""\`
 Pass the prefix as \`authScheme\` (e.g., \`"Bearer"\`, \`"Token"\`, \`"Basic"\`). If the API uses raw tokens with no prefix, pass \`authScheme: ""\`.
 **Do NOT guess the scheme.**

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

@@ -5,7 +5,7 @@ import { logger } from "../../utils/logger.js";
 import { buildArchitectPreamble, buildContextFetchingGuidance, buildReasoningProtocol, buildToolWorkflows, buildFewShotExamples, buildVerificationChecklist, getAuthSnippets, MAX_TESTS_TO_GENERATE, MAX_RECOMMENDATIONS, } from "./recommendationSections.js";
 import { CATEGORY_PRIORITY, Novelty, PriorityTier } from "../../types/TestRecommendation.js";
 import { buildScopeAssessmentSection, isFrontendFile } from "./scopeAssessment.js";
-import { buildExecutionPlan, EXEC_STEP_CODE_REVIEW } from "./diffExecutionPlan.js";
+import { buildExecutionPlan, EXEC_STEP_CODE_REVIEW, EXEC_STEP_ENRICH } from "./diffExecutionPlan.js";
 import { buildFullRepoRecommendations } from "./fullRepoCatalog.js";
 import { ANALYSIS_STEP_EXTRACT } from "./analysisOutputPrompt.js";
 import { TASK_GENERATE, buildExternalCoverageSet, externalDedupKey, isAttackSurfaceSecurityBoundary, taskRef, } from "./recommendationShared.js";
@@ -345,8 +345,15 @@ Treat the endpoint lists above as static hints. If source/diff inspection finds
                     diffEndpointKeys.add(`${m.method} ${ep.path}`);
             }
         }
-        const summaryLines = allEndpoints
-            .flatMap((ep) => (ep.methods ?? []).flatMap((m) => (m.interactions ?? []).map((i) => `  ${m.method} ${ep.path} → ${i.response.statusCode} (${i.type}): ${i.description}`)))
+        // SKYR-4188: `description` held exactly "<METHOD> <path>" in 11,273 of 11,273
+        // interaction lines on eval run 32227152533 — a copy of the start of its own
+        // line. Emit it only when it says something the line does not already say.
+        const interactionLabel = (i, method, path) => i.description && i.description !== `${method} ${path}` ? `: ${i.description}` : "";
+        // detailBlocks repeats every summary line and adds the bodies. The two cover
+        // the same endpoints unless the scope is a diff, so outside a diff the summary
+        // is pure repetition.
+        const summaryLines = !isDiffScope ? "" : allEndpoints
+            .flatMap((ep) => (ep.methods ?? []).flatMap((m) => (m.interactions ?? []).map((i) => `  ${m.method} ${ep.path} → ${i.response.statusCode} (${i.type})${interactionLabel(i, m.method, ep.path)}`)))
             .join("\n");
         const detailEndpoints = isDiffScope
             ? allEndpoints.filter((ep) => (ep.methods ?? []).some((m) => diffEndpointKeys.has(`${m.method} ${ep.path}`)))
@@ -357,13 +364,12 @@ Treat the endpoint lists above as static hints. If source/diff inspection finds
             const qParams = i.request.queryParams ? `\n    queryParams: ${JSON.stringify(i.request.queryParams)}` : "";
             const resBody = i.response.body ? `\n    responseBody: ${JSON.stringify(i.response.body)}` : "";
             const headers = i.request.headers ? `\n    headers: ${JSON.stringify(i.request.headers)}` : "";
-            return `  ${m.method} ${ep.path} → ${i.response.statusCode} (${i.type}): ${i.description}${reqBody}${qParams}${resBody}${headers}`;
+            return `  ${m.method} ${ep.path} → ${i.response.statusCode} (${i.type})${interactionLabel(i, m.method, ep.path)}${reqBody}${qParams}${resBody}${headers}`;
         })))
             .join("\n");
         interactionSection = `
 ## Endpoint Interactions
-${summaryLines}
-
+${summaryLines ? `${summaryLines}\n` : ""}
 ### Detailed (request/response bodies)
 ${isDiffScope ? "Changed endpoints only. " : ""}Use source code schemas (Zod/Pydantic/DTOs) for actual request bodies and query parameters.
 ${detailBlocks}
@@ -557,7 +563,7 @@ ${isDiffScope
 5. \`skyramp_ui_test_generation({ playwrightInput: "<absolute_path_to_zip>" })\`
 
 **For E2E tests:** Same browser recording flow, then call \`skyramp_e2e_test_generation\` with the zip.`
-            : buildToolWorkflows(authHeaderValue, authTypeValue, workspaceAuthScheme))
+            : buildToolWorkflows(authHeaderValue, authTypeValue, workspaceAuthScheme, EXEC_STEP_ENRICH))
         : ""}
 
 ${mainSection}

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

@@ -1,21 +1,11 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { type Service } from "../../workspace/workspace.js";
-/** One related repository to analyze as shared context in multi-repo mode. */
-export interface RelatedRepository {
-    repositoryPath: string;
-    baseBranch?: string;
-    /** `owner/repo` slug, resolved by the action from the checkout's git remote.
-     *  Used verbatim as the `repository` argument/attribution for this repo so the
-     *  agent never has to infer it. */
-    repo: string;
-}
+import type { RelatedRepository, TestbotPromptOptions } from "../../types/TestbotPromptOptions.js";
 /**
  * Parse the JSON-encoded `relatedRepositories` argument passed via the testbot
  * prompt/resource. Returns undefined for missing/blank input or malformed JSON so the
  * caller cleanly falls back to single-repo behavior.
  */
 export declare function parseRelatedRepositories(raw: string | undefined): RelatedRepository[] | undefined;
-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, relatedRepositories?: RelatedRepository[], primaryRepo?: string, planOnly?: boolean, language?: string): string;
+export declare function getTestbotPrompt(opts: TestbotPromptOptions): string;
 export declare function buildWorkspaceRecoveryPrefix(repositoryPath: string): string;
 export declare function registerTestbotPrompt(server: McpServer): void;

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

@@ -54,9 +54,10 @@ export function parseRelatedRepositories(raw) {
         return undefined;
     }
 }
-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, uiCredentials, testsRepoDir, relatedRepositories, primaryRepo, planOnly = false, language) {
-    maxGenerate = Math.min(Math.max(maxGenerate, 0), maxRecommendations);
+export function getTestbotPrompt(opts) {
+    const { prTitle, prDescription, repositoryPath, baseBranch, maxRecommendations = MAX_RECOMMENDATIONS, prNumber, userPrompt, services, uiCredentials, testsRepoDir, relatedRepositories, primaryRepo, planOnly = false, language, } = opts;
+    // maxCritical is intentionally unused (reserved) — see TestbotPromptOptions.
+    const maxGenerate = Math.min(Math.max(opts.maxGenerate ?? MAX_TESTS_TO_GENERATE, 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.
@@ -552,7 +553,7 @@ ${CONTRACT_MODE_GUIDANCE}
 
     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. 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.
+       - **Navigated to a new URL** (e.g. router transition, link click, programmatic \`browser_navigate\`): \`{ isFullCapture: true, pageHash, blueprint, possibleAssertions }\` — a fresh full capture of the new page. \`possibleAssertions\` is present here too, but short — there is no previous capture to compare against, so nothing in it tells you what the action changed. 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:
 
@@ -642,7 +643,7 @@ In these cases:
 
 ${task3CountRule}
 
-${reportLanguageBlock}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.
+${reportLanguageBlock}Call \`skyramp_submit_report\` with \`stateFile\` (from \`skyramp_analyze_changes\` output) — the stateFile is required for execution outcome tracking, and the report is written beside it. Field names, types, and formats are defined in the tool's parameter schema — follow them exactly.
 
 ${hasRelatedRepos ? `
 - **MULTI-REPO attribution**: Set the \`repository\` field (\`owner/repo\`) on EVERY \`newTestsCreated\`, \`testResults\`, \`issuesFound\`, and \`additionalRecommendations\` item — including items about the PRIMARY repo — so each finding is unambiguously attributed. The primary repo's \`repository\` is \`${primaryRepo || "<the primary repo's owner/repo>"}\`; items derived from a related repo's diff (from the \`<related_repositories>\` analysis) carry that repo's \`repository\` value. In \`businessCaseAnalysis\`, include a short per-repo subsection and call out any cross-repo correlations you found.
@@ -651,13 +652,10 @@ ${hasRelatedRepos ? `
   - 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.
 
 ${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.
+    // Neither path reaches the agent any more: SKYR-4147 made the report derive from the
+    // state file's directory, and that directory comes from the environment via
+    // runArtifactDir(). Keep it that way — a path the model retypes out of this prose is a
+    // path the model can corrupt, which is the defect SKYR-4147 fixed.
 }
 export function buildWorkspaceRecoveryPrefix(repositoryPath) {
     return `IMPORTANT: The existing .skyramp/workspace.yml failed to parse or validate. Before proceeding with any tasks below, you MUST call skyramp_init_scan with workspacePath "${repositoryPath}" and force: true, then call skyramp_init_workspace with workspacePath "${repositoryPath}", the discovered services, scanToken, and force: true to regenerate the workspace file.\n\n`;
@@ -669,9 +667,6 @@ export function registerTestbotPrompt(server) {
         argsSchema: {
             prTitle: z.string().describe("Pull request title"),
             prDescription: z.string().describe("Pull request description/body"),
-            summaryOutputFile: z
-                .string()
-                .describe("File path where the agent should write the testbot summary report"),
             repositoryPath: z
                 .string()
                 .default(".")
@@ -733,7 +728,24 @@ 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.uiCredentials, args.testsRepoDir, parseRelatedRepositories(args.relatedRepositories), args.primaryRepo, args.planOnly, args.language);
+        let prompt = getTestbotPrompt({
+            prTitle: args.prTitle,
+            prDescription: args.prDescription,
+            repositoryPath: args.repositoryPath,
+            baseBranch: args.baseBranch,
+            maxRecommendations: args.maxRecommendations,
+            maxGenerate: args.maxGenerate,
+            maxCritical: args.maxCritical,
+            prNumber: args.prNumber,
+            userPrompt: args.userPrompt,
+            services: services.length ? services : undefined,
+            uiCredentials: args.uiCredentials,
+            testsRepoDir: args.testsRepoDir,
+            relatedRepositories: parseRelatedRepositories(args.relatedRepositories),
+            primaryRepo: args.primaryRepo,
+            planOnly: args.planOnly,
+            language: args.language,
+        });
         if (args.workspaceValidationFailed) {
             prompt = buildWorkspaceRecoveryPrefix(args.repositoryPath) + prompt;
         }

package/build/recommendation/discriminators.d.ts

@@ -27,5 +27,11 @@ export interface DiscriminatorValidation {
  *  1. `changedCodeAnchor` must be a non-trivial string (>= 8 chars after trim)
  *     occurring verbatim in `diffText` — grounds the claim in the real change.
  *  2. The `kind`-specific structural predicate must hold over `steps[]`.
+ *
+ * `reposWithoutDiff` names repos in the run whose section carries no branch
+ * diff (e.g. a related repo that fell back to its default branch, SKYR-4203).
+ * An anchor those repos' changes could contain cannot be disproven, so an
+ * unmatched anchor then fails with a "could not be checked" reason instead of
+ * the "not grounded" one — still unverified (no boost), but distinguishable.
  */
-export declare function validateDiscriminator(scenario: DraftedScenario, declared: DiscriminatorClaim, diffText: string): DiscriminatorValidation;
+export declare function validateDiscriminator(scenario: DraftedScenario, declared: DiscriminatorClaim, diffText: string, reposWithoutDiff?: string[]): DiscriminatorValidation;

package/build/recommendation/discriminators.js

@@ -14,10 +14,16 @@ const MIN_NEAR_MISS_LENGTH = 3;
  *  1. `changedCodeAnchor` must be a non-trivial string (>= 8 chars after trim)
  *     occurring verbatim in `diffText` — grounds the claim in the real change.
  *  2. The `kind`-specific structural predicate must hold over `steps[]`.
+ *
+ * `reposWithoutDiff` names repos in the run whose section carries no branch
+ * diff (e.g. a related repo that fell back to its default branch, SKYR-4203).
+ * An anchor those repos' changes could contain cannot be disproven, so an
+ * unmatched anchor then fails with a "could not be checked" reason instead of
+ * the "not grounded" one — still unverified (no boost), but distinguishable.
  */
-export function validateDiscriminator(scenario, declared, diffText) {
+export function validateDiscriminator(scenario, declared, diffText, reposWithoutDiff = []) {
     try {
-        const anchorResult = verifyAnchor(declared?.changedCodeAnchor, diffText);
+        const anchorResult = verifyAnchor(declared?.changedCodeAnchor, diffText, reposWithoutDiff);
         if (!anchorResult.verified)
             return anchorResult;
         const steps = Array.isArray(scenario?.steps) ? scenario.steps : [];
@@ -43,7 +49,7 @@ export function validateDiscriminator(scenario, declared, diffText) {
     }
 }
 // ── Anchor grounding ──
-function verifyAnchor(rawAnchor, diffText) {
+function verifyAnchor(rawAnchor, diffText, reposWithoutDiff = []) {
     const anchor = typeof rawAnchor === "string" ? rawAnchor.trim() : "";
     if (anchor.length < MIN_ANCHOR_LENGTH) {
         return {
@@ -57,6 +63,13 @@ function verifyAnchor(rawAnchor, diffText) {
     // text — compare whitespace-collapsed forms with diff markers stripped, or
     // legitimate multi-line anchors are systematically false-demoted.
     if (!diff.includes(anchor) && !normalizeForAnchorMatch(diff).includes(normalizeForAnchorMatch(anchor))) {
+        if (reposWithoutDiff.length > 0) {
+            return {
+                verified: false,
+                reason: `changedCodeAnchor "${anchor}" was not found in the available PR diffs, and no branch diff exists for ` +
+                    `${reposWithoutDiff.join(", ")} (likely checked out on the default branch), so the claim could not be checked against those changes.`,
+            };
+        }
         return {
             verified: false,
             reason: `changedCodeAnchor "${anchor}" does not occur verbatim in the PR diff, so the discriminator claim is not grounded in the actual change.`,

package/build/resources/testbotResource.js

@@ -26,10 +26,26 @@ export function registerTestbotResource(server) {
         const maxCrit = parseInt(uri.searchParams.get("maxCritical") || "", 10);
         const repositoryPath = param("repositoryPath", ".");
         const services = await readWorkspaceServices(repositoryPath);
-        const prompt = getTestbotPrompt(param("prTitle", ""), param("prDescription", ""), param("summaryOutputFile", ""), repositoryPath, uri.searchParams.get("baseBranch") || undefined, isNaN(maxRec) ? MAX_RECOMMENDATIONS : maxRec, isNaN(maxGen) ? MAX_TESTS_TO_GENERATE : maxGen, isNaN(maxCrit) ? MAX_CRITICAL_TESTS : maxCrit, isNaN(prNum) ? undefined : prNum, uri.searchParams.get("userPrompt") || undefined, services.length ? services : undefined, uri.searchParams.get("uiCredentials") || undefined, uri.searchParams.get("testsRepoDir") || undefined, parseRelatedRepositories(uri.searchParams.get("relatedRepositories") || undefined), uri.searchParams.get("primaryRepo") || undefined, 
-        // Plan-only eval lane (SKYR-3879): recommendation phase only, nothing
-        // generated or executed. Same accepted spellings as the prompt schema.
-        ["true", "1"].includes(uri.searchParams.get("planOnly") ?? ""), uri.searchParams.get("language") || undefined);
+        const prompt = getTestbotPrompt({
+            prTitle: param("prTitle", ""),
+            prDescription: param("prDescription", ""),
+            repositoryPath,
+            baseBranch: uri.searchParams.get("baseBranch") || undefined,
+            maxRecommendations: isNaN(maxRec) ? MAX_RECOMMENDATIONS : maxRec,
+            maxGenerate: isNaN(maxGen) ? MAX_TESTS_TO_GENERATE : maxGen,
+            maxCritical: isNaN(maxCrit) ? MAX_CRITICAL_TESTS : maxCrit,
+            prNumber: isNaN(prNum) ? undefined : prNum,
+            userPrompt: uri.searchParams.get("userPrompt") || undefined,
+            services: services.length ? services : undefined,
+            uiCredentials: uri.searchParams.get("uiCredentials") || undefined,
+            testsRepoDir: uri.searchParams.get("testsRepoDir") || undefined,
+            relatedRepositories: parseRelatedRepositories(uri.searchParams.get("relatedRepositories") || undefined),
+            primaryRepo: uri.searchParams.get("primaryRepo") || undefined,
+            // Plan-only eval lane (SKYR-3879): recommendation phase only, nothing
+            // generated or executed. Same accepted spellings as the prompt schema.
+            planOnly: ["true", "1"].includes(uri.searchParams.get("planOnly") ?? ""),
+            language: uri.searchParams.get("language") || undefined,
+        });
         AnalyticsService.pushMCPToolEvent("skyramp_testbot_prompt", undefined, {}).catch(() => { });
         // Return the original URI — clients may use it to re-fetch the resource,
         // and the caller already has these params. Credentials never appear in

package/build/services/ScenarioGenerationService.js

@@ -2,6 +2,7 @@ import { AUTH_PLACEHOLDER_TOKEN } from "../types/TestTypes.js";
 import { isAuthorizationHeaderName } from "../utils/workspaceAuth.js";
 import { inferExpectedStatus } from "../utils/httpDefaults.js";
 import { logger } from "../utils/logger.js";
+import { deriveBasePath } from "../utils/urlPath.js";
 // Keys that trigger built-in prototype setters when used as bracket-notation
 // property names on a plain object — guard against prototype pollution from
 // LLM-controlled or user-controlled JSON input.
@@ -22,7 +23,10 @@ export class ScenarioGenerationService {
         let destination = params.destination;
         let scheme = "https";
         let port = 443;
-        let basePath = "";
+        // Shared with generateBatchScenarioRestTool, which must predict this exact
+        // prefix to match workspace queryParamOverrides against the path this
+        // method will emit below (SKYR-4127). Keep it derived in one place.
+        const basePath = deriveBasePath(params.baseURL);
         if (params.baseURL) {
             try {
                 const parsed = new URL(params.baseURL);
@@ -33,7 +37,6 @@ export class ScenarioGenerationService {
                     : scheme === "https"
                         ? 443
                         : 80;
-                basePath = parsed.pathname.replace(/\/$/, "");
             }
             catch {
                 logger.warning("Could not parse baseURL, using destination param", {