@skyramp/mcp 0.3.2-rc.pom-4 → 0.3.3

package/build/services/TestExecutionService.js

@@ -9,11 +9,11 @@ import { logger } from "../utils/logger.js";
 import { TestExecutionStatus, } from "../types/TestExecution.js";
 import { TestType } from "../types/TestTypes.js";
 import { buildContainerEnv } from "./containerEnv.js";
-import { SKYRAMP_IMAGE_VERSION } from "../utils/versions.js";
+import { EXECUTOR_DOCKER_IMAGE } from "../utils/versions.js";
 import { walkDir } from "../utils/fileWalk.js";
+export { EXECUTOR_DOCKER_IMAGE };
 const DEFAULT_TIMEOUT = 300000; // 5 minutes
 const MAX_CONCURRENT_EXECUTIONS = 5;
-export const EXECUTOR_DOCKER_IMAGE = `skyramp/executor:${SKYRAMP_IMAGE_VERSION}`;
 const DOCKER_PLATFORM = "linux/amd64";
 const EXECUTION_PROGRESS_INTERVAL = 10000; // 10 seconds between progress updates during execution
 // Temp file with valid empty JSON — used instead of /dev/null for .json config files
@@ -54,8 +54,11 @@ export const PLAYWRIGHT_CONFIG_FILES = [
     "playwright.config.js",
     "playwright.config.mjs",
 ];
-// Directories to skip mounting entirely (cannot bind-mount /dev/null to a directory)
-export const EXCLUDED_MOUNT_ITEMS = [
+// Directories the recursive shadow scans must never descend into. node_modules
+// IS mounted (see mountRepoTree) — but walking it would shadow every package's
+// own package.json with empty JSON via MOUNT_NULL_ITEMS, breaking resolution
+// for the whole tree.
+export const MOUNT_SCAN_SKIP_DIRS = [
     "node_modules",
 ];
 // Reserved container subdir under /home/user where a cross-repo test repository
@@ -354,7 +357,7 @@ export function detectSessionFiles(testFilePath) {
  */
 export function findExcludedPaths(dir, excludedItems) {
     const results = [];
-    const shouldSkipDir = (entry) => excludedItems.includes(entry.name) || EXCLUDED_MOUNT_ITEMS.includes(entry.name);
+    const shouldSkipDir = (entry) => excludedItems.includes(entry.name) || MOUNT_SCAN_SKIP_DIRS.includes(entry.name);
     for (const [entry, fullPath] of walkDir(dir, { shouldSkipDir })) {
         // Only shadow files — mounting /dev/null to a directory target causes Docker errors
         if (excludedItems.includes(entry.name)) {
@@ -364,18 +367,23 @@ export function findExcludedPaths(dir, excludedItems) {
     return results;
 }
 /**
- * Find every nested `node_modules` directory under `dir` — i.e. all except the
- * top-level `<dir>/node_modules` (which the workspace mount already excludes).
- * Never descends into a `node_modules`. Used to shadow repo-local node_modules
- * that ride into the executor inside a parent directory's wholesale bind-mount;
- * a leaked `@playwright/test` becomes a second physical copy and trips
- * Playwright's "Requiring @playwright/test second time" guard.
+ * Find every `node_modules` directory under `dir`, including the top-level
+ * `<dir>/node_modules`. Never descends into a `node_modules`. Used to shadow
+ * SHADOWED_NESTED_PACKAGES inside each one: a repo-local `@playwright/test`
+ * becomes a second physical copy and trips Playwright's "Requiring
+ * @playwright/test second time" guard.
+ *
+ * The top-level one is deliberately NOT special-cased (SKYR-4140). When
+ * `workspacePath` is itself an npm package root — the standard `tests/<suite>/`
+ * layout — its node_modules IS the only one, so skipping it left the shadow
+ * machinery with nothing to act on and no customer dependency resolvable.
+ *
  * Skips `.git` (nothing importable lives there) and does not follow symlinks —
  * by design (a symlinked nested node_modules either dangles in-container,
  * falling through to NODE_PATH's global copy, or its real-path target is
  * walked directly).
  */
-export function findNestedNodeModules(dir) {
+export function findNodeModulesDirs(dir) {
     const results = [];
     const walk = (current) => {
         let entries;
@@ -392,8 +400,7 @@ export function findNestedNodeModules(dir) {
                 continue;
             const full = path.join(current, entry.name);
             if (entry.name === "node_modules") {
-                if (current !== dir)
-                    results.push(full); // skip the top-level node_modules
+                results.push(full);
                 continue; // never descend into a node_modules
             }
             walk(full);
@@ -565,10 +572,15 @@ export class TestExecutionService {
             testFilePath,
             options.testType,
         ];
+        const networkMode = options.dockerNetwork?.trim()
+            ? options.dockerNetwork.trim()
+            : options.useHostNetwork && process.platform === "linux"
+                ? "host"
+                : undefined;
         // Prepare host config with mounts
         const hostConfig = {
             ExtraHosts: ["host.docker.internal:host-gateway"],
-            ...(options.useHostNetwork && process.platform === "linux" ? { NetworkMode: "host" } : {}),
+            ...(networkMode ? { NetworkMode: networkMode } : {}),
             Mounts: [
                 {
                     Type: "bind",
@@ -588,17 +600,16 @@ export class TestExecutionService {
             hostConfig.Mounts.push(mount);
         };
         // Mount one repo tree (the workspace, or a cross-repo test repository) into
-        // the container, skipping EXCLUDED_MOUNT_ITEMS completely.
+        // the container.
         //
         // Each top-level entry is bind-mounted at the canonical container path and —
         // when mirrorToHost is set — at its host-absolute path too. The dual mount
         // lets the test resolve any absolute reference the codegen happens to embed
         // (storageState, fixture paths, snapshots) — including the host workspace
         // path that Playwright's TypeScript loader sometimes produces from
-        // `__dirname` — without needing source-code detection. EXCLUDED_MOUNT_ITEMS
-        // (node_modules) stays excluded at both targets; MOUNT_NULL_ITEMS shadows
-        // (package.json → empty JSON, etc.), nested-package shadows, and
-        // PLAYWRIGHT_CONFIG_FILES shadows (minimal config) are applied at both
+        // `__dirname` — without needing source-code detection. MOUNT_NULL_ITEMS
+        // shadows (package.json → empty JSON, etc.), node_modules package shadows,
+        // and PLAYWRIGHT_CONFIG_FILES shadows (minimal config) are applied at both
         // targets too so the protections survive regardless of which path the test
         // resolves to.
         //
@@ -606,7 +617,7 @@ export class TestExecutionService {
         // later mounts over earlier ones, so the top-level entry mounts must be
         // pushed BEFORE the shadow mounts that override paths inside them.
         //
-        // The three recursive scans (findExcludedPaths × 2 + findNestedNodeModules)
+        // The three recursive scans (findExcludedPaths × 2 + findNodeModulesDirs)
         // are deliberately kept as separate walks rather than fused into one pass:
         // each skips node_modules/.git so the cost is small, and separate walks keep
         // each shadow category's semantics independently testable.
@@ -618,11 +629,13 @@ export class TestExecutionService {
             // otherwise the entry mount would win the dedup race and the repo's own
             // config (which may import dotenv, or simply isn't the minimal/generated
             // one) would leak into the container.
+            //
+            // node_modules is NOT filtered out (SKYR-4140): it carries the customer's
+            // test-support deps, and the per-package shadows below neutralise the only
+            // copies that must not load from the repo.
             const entriesToMount = fs
                 .readdirSync(hostRoot)
-                .filter((file) => !EXCLUDED_MOUNT_ITEMS.includes(file) &&
-                !MOUNT_NULL_ITEMS.includes(file) &&
-                !PLAYWRIGHT_CONFIG_FILES.includes(file));
+                .filter((file) => !MOUNT_NULL_ITEMS.includes(file) && !PLAYWRIGHT_CONFIG_FILES.includes(file));
             for (const file of entriesToMount) {
                 const source = path.join(hostRoot, file);
                 pushMount({ Type: "bind", Target: path.join(containerRoot, file), Source: source });
@@ -639,10 +652,9 @@ export class TestExecutionService {
                     pushMount({ Type: "bind", Source: source, Target: absolutePath });
                 }
             }
-            // Shadow SHADOWED_NESTED_PACKAGES inside every nested node_modules leaked in
-            // via a parent-directory bind-mount (see findNestedNodeModules) — the
-            // top-level node_modules is already excluded above via EXCLUDED_MOUNT_ITEMS.
-            for (const nested of findNestedNodeModules(hostRoot)) {
+            // Shadow SHADOWED_NESTED_PACKAGES inside every mounted node_modules — the
+            // repo's own top-level one included (see findNodeModulesDirs).
+            for (const nested of findNodeModulesDirs(hostRoot)) {
                 for (const pkg of SHADOWED_NESTED_PACKAGES) {
                     const pkgPath = path.join(nested, pkg);
                     if (!fs.existsSync(pkgPath))
@@ -706,6 +718,22 @@ export class TestExecutionService {
         if (crossRepoTestRoot) {
             mountRepoTree(crossRepoTestRoot, path.join(containerMountPath, TEST_REPO_CONTAINER_SUBDIR), true);
         }
+        // runner.sh invokes `npx playwright test`, and npx resolves binaries from
+        // <cwd>/node_modules/.bin before PATH — cwd is always containerMountPath. Now
+        // that node_modules is mounted (SKYR-4140), a repo-local .bin/playwright would
+        // run instead of the image's global CLI. The per-package shadows above do not
+        // cover it under a pnpm layout, where .bin/playwright symlinks into .pnpm/
+        // rather than into node_modules/playwright. Shadow this one .bin — the only
+        // one npx can reach — so binary resolution falls through to PATH as before.
+        // Pushed after mountRepoTree so it layers over the node_modules entry mount.
+        if (fs.existsSync(path.join(workspacePath, "node_modules", ".bin"))) {
+            pushMount({
+                Type: "bind",
+                Source: EMPTY_DIR_PATH,
+                Target: path.join(containerMountPath, "node_modules", ".bin"),
+                ReadOnly: true,
+            });
+        }
         // Mount video output directory for browser tests (writable)
         if (browserTest && videoHostDir) {
             pushMount({

package/build/services/TestGenerationService.d.ts

@@ -1,6 +1,6 @@
 import { SkyrampClient } from "@skyramp/skyramp";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { TestType } from "../types/TestTypes.js";
+import { TestType, MOCK_TYPE } from "../types/TestTypes.js";
 export interface BaseTestParams {
     endpointURL?: string;
     method?: string;
@@ -50,7 +50,7 @@ export declare abstract class TestGenerationService {
     generateTest(params: BaseTestParams & Record<string, any>): Promise<CallToolResult>;
     protected validateInputs(params: BaseTestParams): CallToolResult;
     protected abstract buildGenerationOptions(params: BaseTestParams & Record<string, any>): any;
-    protected abstract getTestType(): TestType;
+    protected abstract getTestType(): TestType | typeof MOCK_TYPE;
     protected handleApiAnalysis(params: BaseTestParams): Promise<CallToolResult | null>;
     private static readonly STANDARD_HEADERS;
     private static simpleWildcardMatch;

package/build/services/TestGenerationService.js

@@ -2,10 +2,11 @@ import path from "path";
 import fs from "fs";
 import { SkyrampClient } from "@skyramp/skyramp";
 import { analyzeOpenAPIWithGivenEndpoint } from "../utils/analyze-openapi.js";
-import { isAuthorizationHeaderName, KNOWN_AUTH_HEADERS, getWorkspaceAuthConfig, getDefaultAuthHeader, getAuthScheme, WorkspaceAuthType, getWorkspaceSkipTLSVerify, } from "../utils/workspaceAuth.js";
+import { isAuthorizationHeaderName, KNOWN_AUTH_HEADERS, resolveAuthFromWorkspace, getWorkspaceSkipTLSVerify, getWorkspaceDefaultQueryParams, mergeQueryParamsString, } from "../utils/workspaceAuth.js";
 import { getPathParameterValidationError, OUTPUT_DIR_FIELD_NAME, PATH_PARAMS_FIELD_NAME, QUERY_PARAMS_FIELD_NAME, FORM_PARAMS_FIELD_NAME, validateParams, validatePath, validateRequestData, } from "../utils/utils.js";
 import { getEntryPoint } from "../utils/telemetry.js";
 import { getLanguageSteps } from "../utils/language-helper.js";
+import { TestType } from "../types/TestTypes.js";
 import { logger } from "../utils/logger.js";
 import { normalizeLanguageParams } from "../utils/normalizeParams.js";
 import { stageGeneratedPaths, resolveOutputDir } from "../utils/gitStaging.js";
@@ -24,6 +25,19 @@ export function deriveEffectiveFramework(language, framework) {
     const lang = (language ?? "").trim().toLowerCase();
     return lang === "typescript" || lang === "javascript" ? "playwright" : "";
 }
+/**
+ * Test types whose generation is driven by a recorded Playwright trace, not a
+ * live query-string request the same way contract/fuzz/smoke/load/integration
+ * are. Their schemas (uiTestSchema, e2eTestSchema) don't expose a queryParams
+ * field at all, so there's no way for a caller to override or even know this
+ * field exists — injecting an unrequested, uneditable workspace
+ * defaultQueryParams value into that path is not what the design intends
+ * (SKYR-4050).
+ */
+const SKIP_DEFAULT_QUERY_PARAMS_TEST_TYPES = new Set([
+    TestType.UI,
+    TestType.E2E,
+]);
 export class TestGenerationService {
     client;
     constructor() {
@@ -316,29 +330,15 @@ The generated test file remains unchanged and ready to use as-is.
     async executeGeneration(generateOptions) {
         try {
             // Auto-resolve auth from workspace config when authHeader was not explicitly provided.
-            // undefined = omit (auto-resolve); "" = explicit skip-auth for unauthenticated endpoints.
+            // undefined = auto-resolve; "" = caller explicitly said skip-auth.
             if (generateOptions.authHeader === undefined) {
                 try {
                     const repoPath = generateOptions.outputDir || process.cwd();
-                    const wsAuth = await getWorkspaceAuthConfig(repoPath);
-                    let resolvedHeader = wsAuth.authHeader ?? getDefaultAuthHeader(wsAuth.authType);
-                    if (!resolvedHeader && wsAuth.authScheme !== undefined) {
-                        resolvedHeader = "Authorization";
-                    }
-                    if (wsAuth.authType === WorkspaceAuthType.ApiKey && !resolvedHeader) {
-                        logger.warning("workspace.yml has authType: apiKey but no authHeader is set — " +
-                            "requests will be sent without an auth header and will likely receive 401/403. " +
-                            "Add authHeader: <X-Your-Key-Header> to .skyramp/workspace.yml.");
-                    }
-                    if (resolvedHeader && wsAuth.authType !== WorkspaceAuthType.None) {
-                        logger.info("authHeader not provided — resolved from workspace config", {
-                            authHeader: resolvedHeader,
-                            authType: wsAuth.authType,
-                        });
-                        generateOptions.authHeader = resolvedHeader;
-                        if (isAuthorizationHeaderName(resolvedHeader)) {
-                            generateOptions.authScheme =
-                                generateOptions.authScheme ?? wsAuth.authScheme ?? getAuthScheme(wsAuth.authType);
+                    const resolved = await resolveAuthFromWorkspace(repoPath, generateOptions.authHeader, generateOptions.authScheme);
+                    if (resolved) {
+                        generateOptions.authHeader = resolved.authHeader;
+                        if (resolved.authScheme !== undefined) {
+                            generateOptions.authScheme = resolved.authScheme;
                         }
                     }
                 }
@@ -364,6 +364,24 @@ The generated test file remains unchanged and ready to use as-is.
                     logger.warning("Could not resolve skipTLSVerify from workspace config");
                 }
             }
+            // Workspace-declared default query params (SKYR-4050): api.defaultQueryParams
+            // are attached to every generated request for the service. Existing
+            // queryParams entries (explicit caller values) always win on a key collision.
+            if (!SKIP_DEFAULT_QUERY_PARAMS_TEST_TYPES.has(this.getTestType())) {
+                try {
+                    const repoPath = generateOptions.outputDir || process.cwd();
+                    const defaults = await getWorkspaceDefaultQueryParams(repoPath);
+                    if (defaults) {
+                        generateOptions.queryParams = mergeQueryParamsString(generateOptions.queryParams, defaults);
+                        logger.info("Merged workspace defaultQueryParams into queryParams", {
+                            keys: Object.keys(defaults),
+                        });
+                    }
+                }
+                catch {
+                    logger.warning("Could not resolve default query params from workspace config");
+                }
+            }
             if (generateOptions.traceFilePath) {
                 const traceAuth = this.extractAuthFromTrace(generateOptions.traceFilePath, generateOptions.generateInclude, generateOptions.generateExclude);
                 if (traceAuth) {

package/build/services/containerEnv.js

@@ -14,7 +14,9 @@ export function rewriteLocalhostForDocker(url) {
  */
 export function buildContainerEnv(options, saveStoragePath, hostEnv = process.env) {
     const env = [
-        `SKYRAMP_TEST_TOKEN=${options.token || ""}`,
+        // Omit entirely when empty so os.getenv() returns None in the test —
+        // unauthenticated endpoints won't send an empty auth header (E7).
+        ...(options.token ? [`SKYRAMP_TEST_TOKEN=${options.token}`] : []),
         "SKYRAMP_IN_DOCKER=true",
     ];
     // Skyramp-generated tests are standalone HTTP tests that never need host repo
@@ -42,6 +44,30 @@ export function buildContainerEnv(options, saveStoragePath, hostEnv = process.en
             env.push(`${key}=${shouldRewrite ? rewriteLocalhostForDocker(val) : val}`);
         }
     }
+    // Credentials that generated UI tests read from the environment instead of
+    // carrying as literals (SKYR-3862). Without this the container never sees
+    // them and every generated login fails its guard.
+    //
+    // Forwarded on presence, not truthiness: the generated guard deliberately
+    // distinguishes an unset variable (a misconfiguration, fails fast) from one
+    // set to "" (valid on forms that accept a blank password). A truthy check —
+    // as used for the URL vars above — would drop the empty case and collapse it
+    // into the failure case.
+    //
+    // TODO(SKYR-4110): only ONE credential pair is forwarded, because testbot
+    // exports only the first credential from its `uiCredentials` input. That input
+    // was designed to carry several, so the agent can pick per test case by
+    // authorization role — so a multi-role suite can get a credential its test did
+    // not expect, surfacing as a false 403. The fix is a keyed form
+    // (SKYRAMP_UI_PASSWORD_<KEY>), which needs no new forwarding logic here: the
+    // loop above already forwards SKYRAMP_TEST_SERVICE_URL_* by prefix, so the
+    // same approach applies. Keep the presence-not-truthiness rule when it lands.
+    for (const key of ["SKYRAMP_UI_USERNAME", "SKYRAMP_UI_PASSWORD"]) {
+        const val = hostEnv[key];
+        if (val !== undefined) {
+            env.push(`${key}=${val}`);
+        }
+    }
     if (hostEnv.SKYRAMP_DEBUG) {
         env.push(`SKYRAMP_DEBUG=${hostEnv.SKYRAMP_DEBUG}`);
     }

package/build/tool-phases.js

@@ -11,7 +11,11 @@ export const TOOL_PHASE_MAP = {
     skyramp_ui_test_generation: "generating",
     skyramp_batch_scenario_test_generation: "generating",
     skyramp_mock_generation: "generating",
+    skyramp_batch_mock_generation: "generating",
+    skyramp_generate_enriched_integration_test: "generating",
+    skyramp_enrich_test_with_mocks: "generating",
     skyramp_execute_test: { before: "maintaining", after: "executing" },
+    skyramp_run_existing_tests: { before: "maintaining", after: "executing" },
     skyramp_analyze_test_health: "maintaining",
     skyramp_submit_report: "reporting",
 };
@@ -30,6 +34,7 @@ export const TOOLS_WITHOUT_PHASE = new Set([
     "skyramp_init_scan",
     "skyramp_init_workspace",
     "skyramp_one_click_tool",
+    "skyramp_setup_local_dev_worker",
     "skyramp_actions",
     "skyramp_start_trace_collection",
     "skyramp_stop_trace_collection",
@@ -37,4 +42,6 @@ export const TOOLS_WITHOUT_PHASE = new Set([
     "skyramp_modularization",
     "skyramp_reuse_code",
     "skyramp_enhance_assertions",
+    "skyramp_preflight_mock_check",
+    "skyramp_query_proxy_mocks",
 ]);

package/build/tools/code-refactor/codeReuseTool.js

@@ -4,9 +4,11 @@ import { getCodeReusePrompt, isPomAwareTarget } from "../../prompts/code-reuse.j
 import { selectScopedPoms } from "../../utils/pom-scope/index.js";
 import { verifyReuse } from "../../utils/pom-verify/index.js";
 import { infraGateFailure, zeroReuseGateFailure, composeVerifyText } from "./verify-gates.js";
+import { recordCandidates, recordNoPomLayer, recordVerifyOutcome } from "./reuse-state.js";
 import { codeRefactoringSchema, languageSchema, } from "../../types/TestTypes.js";
 import { SKYRAMP_UTILS_HEADER } from "../../utils/utils.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
+import { isPomReuseEnabled } from "../../utils/featureFlags.js";
 import { stageGeneratedPaths } from "../../utils/gitStaging.js";
 const codeReuseSchema = z.object({
     testFile: z
@@ -25,6 +27,12 @@ const codeReuseSchema = z.object({
         .describe("Verify a previously written refactored test's POM calls against source instead of returning the reuse prompt"),
 });
 const TOOL_NAME = "skyramp_reuse_code";
+// Only advertised when SKYRAMP_FEATURE_POM_REUSE=1 — with the flag off this tool
+// never takes the POM path, so describing it would promise behavior it won't do.
+const POM_AWARE_MODE_DESCRIPTION = `
+
+      **POM-AWARE MODE (TypeScript/JavaScript + Playwright):**
+      For projects with \`language: "typescript" or "javascript"\` and \`framework: "playwright"\`, this tool first checks whether the project has an existing Page Object Model (POM) library (\`pageobjects/\` directories or \`*.page.ts\` / \`*.page.js\` files). If POMs are found, the test is refactored to use those POM classes and methods — replacing raw inline locators with the existing abstractions. SkyrampUtils consolidation is skipped on this path. If no POMs are found, the tool falls back to the standard SkyrampUtils path. New POM creation is out of scope — existing POMs are reused only. After POM-aware code reuse, do NOT call skyramp_modularization — on this path that supersedes WORKFLOW SUMMARY step 6.`;
 export function registerCodeReuseTool(server) {
     server.registerTool(TOOL_NAME, {
         description: `Analyzes code for reuse opportunities and enforces code reuse principles.
@@ -57,10 +65,7 @@ export function registerCodeReuseTool(server) {
 
       **MANDATORY**: ONLY ALLOW CODE REUSE IF THE IS TRACE BASED FLAG IS SET TO TRUE ELSE DO NOT ALLOW CODE REUSE AND LEAVE THE TEST FILE AS IS.
       **CRITICAL**: NON TRACE BASED TESTS ARE ALREADY MODULARIZED AND DO NOT NEED CODE REUSE.
-      The tool will provide step-by-step instructions that MUST be followed exactly.
-
-      **POM-AWARE MODE (TypeScript/JavaScript + Playwright):**
-      For projects with \`language: "typescript" or "javascript"\` and \`framework: "playwright"\`, this tool first checks whether the project has an existing Page Object Model (POM) library (\`pageobjects/\` directories or \`*.page.ts\` / \`*.page.js\` files). If POMs are found, the test is refactored to use those POM classes and methods — replacing raw inline locators with the existing abstractions. SkyrampUtils consolidation is skipped on this path. If no POMs are found, the tool falls back to the standard SkyrampUtils path. New POM creation is out of scope — existing POMs are reused only. After POM-aware code reuse, do NOT call skyramp_modularization.`,
+      The tool will provide step-by-step instructions that MUST be followed exactly.${isPomReuseEnabled() ? POM_AWARE_MODE_DESCRIPTION : ""}`,
         inputSchema: codeReuseSchema.shape,
         _meta: {
             keywords: [
@@ -75,9 +80,26 @@ export function registerCodeReuseTool(server) {
         let errorResult;
         try {
             if (params.verify) {
+                // The verify pass is POM-only, and it is the sole writer of the report's
+                // reuse summary — so with the flag off a stale instruction to verify must
+                // not run it, or a POM-less run would still emit POM reuse numbers.
+                if (!isPomReuseEnabled()) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "VERIFICATION SKIPPED — POM-aware code reuse is disabled. Nothing to verify; continue.",
+                            },
+                        ],
+                    };
+                }
                 try {
                     const r = await verifyReuse(params.testFile, params.language);
                     const gate = (await infraGateFailure(params, r)) ?? (await zeroReuseGateFailure(params, r));
+                    // Record what this pass established before returning the text report:
+                    // every number in it is already in hand here, so the agent is never
+                    // asked to read one back out and retype it later.
+                    await recordVerifyOutcome(params.testFile, r, gate !== undefined, params.language);
                     return { content: [{ type: "text", text: composeVerifyText(gate, r) }] };
                 }
                 catch (err) {
@@ -110,11 +132,28 @@ export function registerCodeReuseTool(server) {
                     });
                     if (tier1.length + tier2.length > 0) {
                         scopedPoms = { tier1, tier2 };
+                        // Only report candidates found through the conventional POM globs.
+                        //
+                        // The selector-grep fallback also matches ordinary in-repo frontend
+                        // source — app components legitimately contain the spec's test-ids by
+                        // construction — so in a repo with no page-object layer at all it still
+                        // yields "candidates". Reporting those would render, on a POM-less repo,
+                        // "4 candidate POM files detected" next to zero reuse: each number true
+                        // in isolation, but together they assert reusable page objects existed
+                        // and were ignored. `zeroReuseGateFailure` already draws this exact line
+                        // for the same reason; the report has to draw it too.
+                        //
+                        // The agent is still handed the grep-discovered files to consider —
+                        // only the customer-facing count is withheld.
+                        if (diagnostics.discovery === "globs") {
+                            await recordCandidates(params.testFile, tier1.length);
+                        }
                     }
                     else if (diagnostics.selectors > 0 && diagnostics.discovery !== "skipped-too-large") {
                         // A clean scan ran (glob or selector-grep) and found zero overlap — distinct from
                         // "scoping wasn't attempted" (no selectors) or "scan was skipped" (repo too large).
                         scopedPoms = { tier1: [], tier2: [], scannedNoOverlap: true };
+                        await recordNoPomLayer(params.testFile);
                     }
                     logger.info("POM pre-scoping", {
                         ...diagnostics,

package/build/tools/code-refactor/enhanceAssertionsTool.js

@@ -5,6 +5,7 @@ import { getContractProviderAssertionsPrompt } from "../../prompts/enhance-asser
 import { getIntegrationAssertionsPrompt } from "../../prompts/enhance-assertions/integrationAssertionsPrompt.js";
 import { getUIAssertionsPrompt } from "../../prompts/enhance-assertions/uiAssertionsPrompt.js";
 import { isTestbotEnabled } from "../../utils/featureFlags.js";
+import { renderSharedAssertionRules } from "../../prompts/enhance-assertions/sharedAssertionRules.js";
 import { stageGeneratedPaths } from "../../utils/gitStaging.js";
 const TOOL_NAME = "skyramp_enhance_assertions";
 const TESTBOT_UI_CHECKS = `
@@ -12,6 +13,37 @@ const TESTBOT_UI_CHECKS = `
 - If no suitable selector exists in the generated file for an assertion you need to add, go back and call \`browser_assert\` on the live page to record it with a valid selector, then re-export and regenerate.
 - **After executing a UI test that documents a bug from \`issuesFound\`**: if it passed when you expected it to fail, the assertions are too weak — add a stronger \`expect()\` that directly targets the buggy behavior. This counts as the single allowed retry under the 2-attempt cap — do NOT re-run more than once.
 `;
+function buildAssertionInstructions(testFile, testType, enhanceType) {
+    if (testType === TestType.UI) {
+        let instructions = getUIAssertionsPrompt(testFile, enhanceType);
+        if (isTestbotEnabled()) {
+            instructions += TESTBOT_UI_CHECKS;
+        }
+        return instructions;
+    }
+    if (testType === TestType.CONTRACT) {
+        return getContractProviderAssertionsPrompt(testFile, enhanceType);
+    }
+    if (testType === TestType.INTEGRATION) {
+        return getIntegrationAssertionsPrompt(testFile, enhanceType);
+    }
+    throw new Error(`Unsupported testType for ${TOOL_NAME}: ${testType}`);
+}
+function buildAutoApplyInstructions(testFile, testType, enhanceType) {
+    const typeSpecificInstructions = buildAssertionInstructions(testFile, testType, enhanceType);
+    return [
+        `Enhance response body assertions in: \`${testFile}\``,
+        `Test type: ${testType} | Context: ${enhanceType}`,
+        ``,
+        `Read the file, apply the type-specific assertion guidance below, and write the file back directly.`,
+        `Add assertions after each send_request/sendRequest status-code assertion.`,
+        `Use SDK helper: Python \`skyramp.get_response_value(response, "json.path")\`, JS \`getValue(response, "json.path")\`.`,
+        `Do NOT restructure, reformat, add comments, or change imports. Only add assertion lines.`,
+        ``,
+        `Type-specific assertion guidance:`,
+        typeSpecificInstructions,
+    ].join("\n");
+}
 const enhanceAssertionsSchema = {
     testFile: z
         .string()
@@ -24,6 +56,12 @@ const enhanceAssertionsSchema = {
         .describe("The context of the enhancement. " +
         "Use 'generation' after generating a new test file (applies to every test function). " +
         "Use 'maintenance' during drift UPDATE (applies only to new or diff-affected functions)."),
+    autoApply: z
+        .boolean()
+        .default(false)
+        .describe("When true, returns a compact instruction set (10 lines) that tells the agent to " +
+        "read the test file, enhance assertions per standard rules, and write it back directly. " +
+        "When false (default), returns the full verbose instruction set."),
 };
 export function registerEnhanceAssertionsTool(server) {
     server.registerTool(TOOL_NAME, {
@@ -34,26 +72,33 @@ export function registerEnhanceAssertionsTool(server) {
 - After updating an existing supported test file during maintenance`,
         inputSchema: enhanceAssertionsSchema,
     }, async (params) => {
-        const { testFile, testType, enhanceType } = params;
+        const { testFile, testType, enhanceType, autoApply } = params;
         // Stage so testbot includes the generated files in its output commit.
         await stageGeneratedPaths(testFile);
-        const enhanceCtx = enhanceType;
-        let instructions;
-        if (testType === TestType.UI) {
-            instructions = getUIAssertionsPrompt(testFile, enhanceCtx);
-            if (isTestbotEnabled()) {
-                instructions += TESTBOT_UI_CHECKS;
-            }
-        }
-        else if (testType === TestType.CONTRACT) {
-            instructions = getContractProviderAssertionsPrompt(testFile, enhanceCtx);
-        }
-        else if (testType === TestType.INTEGRATION) {
-            instructions = getIntegrationAssertionsPrompt(testFile, enhanceCtx);
-        }
-        else {
-            throw new Error(`Unsupported testType for ${TOOL_NAME}: ${testType}`);
+        if (autoApply) {
+            const compactInstructions = [
+                `Enhance response body assertions in: \`${testFile}\``,
+                `Test type: ${testType} | Context: ${enhanceType}`,
+                ``,
+                `Read the file, add assertions after each send_request/sendRequest status-code assertion, write it back.`,
+                `Use SDK helper: Python \`skyramp.get_response_value(response, "json.path")\`, JS \`getValue(response, "json.path")\`.`,
+                ``,
+                `Shared assertion rules (apply all that fit):`,
+                renderSharedAssertionRules(),
+                ``,
+                `Do NOT restructure, reformat, add comments, or change imports. Only add assertion lines.`,
+            ].join("\n");
+            const result = {
+                content: [{ type: "text", text: compactInstructions }],
+                isError: false,
+            };
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, undefined, { testFile: params.testFile, testType: params.testType, enhanceType: params.enhanceType, autoApply: Boolean(params.autoApply) }).catch(() => { });
+            return result;
         }
+        const enhanceCtx = enhanceType;
+        const instructions = autoApply
+            ? buildAutoApplyInstructions(testFile, testType, enhanceCtx)
+            : buildAssertionInstructions(testFile, testType, enhanceCtx);
         const result = {
             content: [
                 {
@@ -63,7 +108,12 @@ export function registerEnhanceAssertionsTool(server) {
             ],
             isError: false,
         };
-        AnalyticsService.pushMCPToolEvent(TOOL_NAME, undefined, params).catch(() => { });
+        AnalyticsService.pushMCPToolEvent(TOOL_NAME, undefined, {
+            testFile: params.testFile,
+            testType: params.testType,
+            enhanceType: params.enhanceType,
+            autoApply: Boolean(params.autoApply),
+        }).catch(() => { });
         return result;
     });
 }