@skyramp/mcp 0.1.5 → 0.1.7

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

@@ -934,9 +934,9 @@ describe("buildRecommendationPrompt — multi-method endpoint partitioning", ()
         });
         const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10);
         // Both GET and POST for /api/products should be in "Changed in this PR"
-        expect(prompt).toContain("Changed in this PR");
-        expect(prompt).toMatch(/Changed in this PR:[\s\S]*GET \/api\/products/);
-        expect(prompt).toMatch(/Changed in this PR:[\s\S]*POST \/api\/products/);
+        expect(prompt).toContain("Likely changed in this PR");
+        expect(prompt).toMatch(/Likely changed in this PR[\s\S]*GET \/api\/products/);
+        expect(prompt).toMatch(/Likely changed in this PR[\s\S]*POST \/api\/products/);
         // /api/items should NOT be in changed section
         expect(prompt).toMatch(/Other endpoints[\s\S]*GET \/api\/items/);
     });
@@ -983,8 +983,8 @@ describe("buildRecommendationPrompt — multi-method endpoint partitioning", ()
         });
         const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10);
         // Both products and orders should be in changed section
-        expect(prompt).toMatch(/Changed in this PR:[\s\S]*GET \/api\/products/);
-        expect(prompt).toMatch(/Changed in this PR:[\s\S]*POST \/api\/orders/);
+        expect(prompt).toMatch(/Likely changed in this PR[\s\S]*GET \/api\/products/);
+        expect(prompt).toMatch(/Likely changed in this PR[\s\S]*POST \/api\/orders/);
     });
 });
 // ---------------------------------------------------------------------------
@@ -1021,7 +1021,7 @@ describe("buildRecommendationPrompt — removed endpoint listing", () => {
         });
         const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10);
         expect(prompt).toContain("DELETE /api/legacy [removed]");
-        expect(prompt).toContain("Changed in this PR");
+        expect(prompt).toContain("Likely changed in this PR");
     });
 });
 // ---------------------------------------------------------------------------

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

@@ -5,9 +5,11 @@ import { MAX_TESTS_TO_GENERATE, MAX_RECOMMENDATIONS, MAX_CRITICAL_TESTS, PATH_PA
 import { buildDriftAnalysisPrompt } from "../test-maintenance/drift-analysis-prompt.js";
 import { getTraceRecordingPromptText } from "../../playwright/traceRecordingPrompt.js";
 import { isContractConsumerModeEnabled } from "../../utils/featureFlags.js";
+import { resolveServiceDetailsRef } from "../../utils/utils.js";
 import { readWorkspaceConfigRaw } from "../../utils/workspaceAuth.js";
-// Cached at module-load — the flag is process-wide and cannot change per call.
+// Cached at module-load — flags are process-wide and cannot change per call.
 const CONSUMER_MODE_ENABLED = isContractConsumerModeEnabled();
+const SERVICE_REFS = resolveServiceDetailsRef();
 // Mode-aware bullet block that appears inside the "How to generate each type"
 // section. When consumer mode is disabled, only provider-mode guidance is
 // surfaced so the agent never recommends or invokes consumer contract tests.
@@ -121,8 +123,8 @@ ${userPrompt ? "Generate only the tests that the user requested from the Additio
 - Critical-category tests are already ranked first by the pre-computed scores — follow the plan order.
 
 **Auth — determine ONCE, apply to EVERY tool call:**
-1. Read auth params from the Execution Plan returned by \`skyramp_analyze_changes\` — they are resolved directly from workspace.yml. **Use these as-is; do not infer or override.**
-2. If workspace shows \`authType: none\` or \`authHeader: ""\` → proceed with no auth (\`authHeader: ""\`). If tests fail due to 401/403, add to \`issuesFound\`: "Auth may be required — update \`api.authType\` in workspace.yml."
+1. Read auth params from the Execution Plan returned by \`skyramp_analyze_changes\` — they are pre-resolved from ${SERVICE_REFS.authSourceRef}. **Use these as-is; do not infer or override.**
+2. If workspace shows \`authType: none\` or \`authHeader: ""\` → proceed with no auth (\`authHeader: ""\`). If tests fail due to 401/403, add to \`issuesFound\`: "Auth may be required — update \`api.authType\` in ${SERVICE_REFS.authSourceRef}."
 3. **Auth params by header type — quick reference:**
 
    | \`authHeader\` | \`authType\` examples | \`skyramp_batch_scenario_*\` / \`skyramp_contract_*\` | \`skyramp_integration_test_generation\` (scenarioFile) |
@@ -133,7 +135,7 @@ ${userPrompt ? "Generate only the tests that the user requested from the Additio
    | none / \`""\` | \`none\` | \`authHeader: ""\` only when endpoint confirmed unauthenticated | \`authHeader: ""\` |
 
    **Omit \`authToken\` entirely** — \`SKYRAMP_PLACEHOLDER_TOKEN\` is auto-inserted at execution time.
-   The \`authScheme\` for \`Authorization\` headers is pre-resolved in the Execution Plan — use it exactly (e.g. \`"Bearer"\`, \`"Token"\`, or a custom scheme from \`api.authScheme\` in workspace.yml).
+   The \`authScheme\` for \`Authorization\` headers is pre-resolved in the Execution Plan — use it exactly (e.g. \`"Bearer"\`, \`"Token"\`, or a custom scheme from ${SERVICE_REFS.authSourceRef}).
 
    Passing auth alongside workspace \`authType\` on \`skyramp_integration_test_generation\` causes "${AUTH_CONFLICT_ERROR_MSG}" — follow the table.
 4. Only pass \`authHeader: ""\` if you can confirm the endpoint is truly unauthenticated.
@@ -141,7 +143,7 @@ ${userPrompt ? "Generate only the tests that the user requested from the Additio
 **How to generate each type (for ADD):**
 - **Integration**: call \`skyramp_batch_scenario_test_generation\` with ALL steps in a single call (pass the \`steps\` array with method, path, requestBody, statusCode for each step). Then call \`skyramp_integration_test_generation\` with the returned scenario file.
   **Use the pre-built scenario JSON from the Execution Plan** — pass the steps array directly. Do NOT read source code models to construct request bodies if the plan already provides them.
-  Scenario JSON and test files go in the \`testDirectory\` from \`workspace.yml\` (visible in the service context block at the top of this prompt). Do NOT create a new \`tests/\` directory at the repo root — use the path the workspace config specifies. If no \`testDirectory\` is configured, default to the language-conventional location (e.g. \`src/test/java/...\` for Java, \`tests/\` for Python).
+  Scenario JSON and test files go in ${SERVICE_REFS.testDirRef}. Do NOT create a new \`tests/\` directory at the repo root — use that path. If no \`testDirectory\` is configured, default to the language-conventional location (e.g. \`src/test/java/...\` for Java, \`tests/\` for Python).
   **Pipeline for speed**: Call ALL \`skyramp_batch_scenario_test_generation\` calls in one batch. When they return, call ALL \`skyramp_integration_test_generation\` calls in the next batch. Do NOT serialize per-scenario (batch→integration→batch→integration) — batch ALL scenarios first, then generate ALL integration tests.
 - **Contract**: call \`skyramp_contract_test_generation\` with \`endpointURL\`, \`method\`, and \`requestData\` for POST/PUT/PATCH.
   Pass \`apiSchema\` if an OpenAPI spec exists.
@@ -289,7 +291,7 @@ function buildServiceContext(services) {
         if (svc.api?.baseUrl)
             parts.push(`  <base_url>${escapeXml(svc.api.baseUrl)}</base_url>`);
         if (svc.testDirectory)
-            parts.push(`  <output_dir>${escapeXml(svc.testDirectory)}</output_dir>`);
+            parts.push(`  <test_directory>${escapeXml(svc.testDirectory)}</test_directory>`);
         parts.push('</service>');
         return parts.join('\n');
     });
@@ -303,6 +305,9 @@ export async function readWorkspaceServices(repositoryPath) {
     const rawConfig = await readWorkspaceConfigRaw(repositoryPath);
     return (rawConfig?.services ?? []);
 }
+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`;
+}
 export function registerTestbotPrompt(server) {
     logger.info("Registering testbot prompt");
     server.registerPrompt("skyramp_testbot", {
@@ -349,10 +354,17 @@ export function registerTestbotPrompt(server) {
                 .string()
                 .optional()
                 .describe("Browser login credentials for UI test recording (format: 'username:password', one per line). Injected into the prompt as a <ui-credentials> block so the agent logs in before recording traces."),
+            workspaceValidationFailed: z
+                .boolean()
+                .default(false)
+                .describe("Set to true when the testbot detected that .skyramp/workspace.yml exists but failed schema validation. Instructs the agent to regenerate the workspace file before proceeding."),
         },
     }, async (args) => {
         const services = await readWorkspaceServices(args.repositoryPath);
-        const 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);
+        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);
+        if (args.workspaceValidationFailed) {
+            prompt = buildWorkspaceRecoveryPrefix(args.repositoryPath) + prompt;
+        }
         AnalyticsService.pushMCPToolEvent("skyramp_testbot_prompt", undefined, {}).catch(() => { });
         return {
             messages: [

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

@@ -59,7 +59,7 @@ describe("buildServiceContext (via getTestbotPrompt)", () => {
         expect(prompt).toContain("<language>python</language>");
         expect(prompt).toContain("<framework>pytest</framework>");
         expect(prompt).toContain("<base_url>http://localhost:8000</base_url>");
-        expect(prompt).toContain("<output_dir>tests/python</output_dir>");
+        expect(prompt).toContain("<test_directory>tests/python</test_directory>");
         expect(prompt).toContain("</service>");
         expect(prompt).toContain("<services>");
         expect(prompt).toContain("</services>");
@@ -70,7 +70,7 @@ describe("buildServiceContext (via getTestbotPrompt)", () => {
         expect(prompt).not.toContain("<language>");
         expect(prompt).not.toContain("<framework>");
         expect(prompt).not.toContain("<base_url>");
-        expect(prompt).not.toContain("<output_dir>");
+        expect(prompt).not.toContain("<test_directory>");
     });
     it("renders multiple services", () => {
         const prompt = callWithServices([
@@ -104,7 +104,7 @@ describe("buildServiceContext (via getTestbotPrompt)", () => {
                 api: { baseUrl: "http://host?a=1&b=2" },
             },
         ]);
-        expect(prompt).toContain("<output_dir>tests/a&amp;b</output_dir>");
+        expect(prompt).toContain("<test_directory>tests/a&amp;b</test_directory>");
         expect(prompt).toContain("<base_url>http://host?a=1&amp;b=2</base_url>");
     });
     it("places services block between REPOSITORY PATH and instruction line", () => {
@@ -211,12 +211,12 @@ describe("drift analysis inline embedding", () => {
         expect(prompt).toContain("<drift_analysis_rules>");
         expect(prompt).toContain("</drift_analysis_rules>");
     });
-    it("includes persona inside the XML block", () => {
+    it("does not include a persona statement inside the inline XML block", () => {
         const prompt = basePrompt();
         const start = prompt.indexOf("<drift_analysis_rules>");
         const end = prompt.indexOf("</drift_analysis_rules>");
         const block = prompt.slice(start, end);
-        expect(block).toContain("You are acting as a Skyramp Integration Architect");
+        expect(block).not.toContain("You are acting as a Skyramp Integration Architect");
     });
     it("drift_analysis_rules block appears inside Task 1, before Task 2", () => {
         const prompt = basePrompt();
@@ -231,3 +231,20 @@ describe("drift analysis inline embedding", () => {
         expect(prompt).toContain("rules in `<drift_analysis_rules>`");
     });
 });
+describe("buildWorkspaceRecoveryPrefix", () => {
+    const { buildWorkspaceRecoveryPrefix } = require("./testbot-prompts.js");
+    it("includes repositoryPath in both init_scan and init_workspace instructions", () => {
+        const prefix = buildWorkspaceRecoveryPrefix("/home/user/repo");
+        expect(prefix).toContain('skyramp_init_scan with workspacePath "/home/user/repo"');
+        expect(prefix).toContain('skyramp_init_workspace with workspacePath "/home/user/repo"');
+    });
+    it("includes force: true for both tool calls", () => {
+        const prefix = buildWorkspaceRecoveryPrefix("/repo");
+        expect(prefix).toContain("force: true, then call skyramp_init_workspace");
+        expect(prefix).toContain("force: true to regenerate");
+    });
+    it("starts with IMPORTANT", () => {
+        const prefix = buildWorkspaceRecoveryPrefix("/repo");
+        expect(prefix).toMatch(/^IMPORTANT:/);
+    });
+});

package/build/resources/analysisResources.js

@@ -29,6 +29,7 @@ export function registerAnalysisResources(server) {
                 return memData;
             }
         }
+        logger.warning(`Session not found in memory (sessionId=${sessionId}) — server may have restarted; falling back to state file`);
         // Fall back to state file for backward compatibility.
         // Try both "analysis" and "recommendation" prefixes since the default changed.
         const registeredPath = getSessionFilePath(sessionId);

package/build/services/ScenarioGenerationService.js

@@ -1,6 +1,8 @@
 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 { stageGeneratedPaths } from "../utils/gitStaging.js";
 import fs from "fs";
 import path from "path";
 export class ScenarioGenerationService {
@@ -40,6 +42,8 @@ export class ScenarioGenerationService {
                 }
                 existingRequests.push(traceRequest);
                 fs.writeFileSync(filePath, JSON.stringify(existingRequests, null, 2), "utf8");
+                // Stage so testbot includes the generated files in its output commit.
+                await stageGeneratedPaths(filePath);
                 logger.info("Trace request added to file", {
                     filePath,
                     totalRequests: existingRequests.length,
@@ -124,7 +128,7 @@ ${JSON.stringify(traceRequest, null, 2)}
         }
         const timestamp = new Date().toISOString();
         const method = params.method;
-        const statusCode = params.statusCode ?? (method === "POST" ? 201 : method === "DELETE" ? 204 : 200);
+        const statusCode = params.statusCode ?? inferExpectedStatus(method);
         const requestBody = params.requestBody ||
             (method === "GET" || method === "DELETE" ? "" : "{}");
         const responseHeaders = params.responseHeaders

package/build/services/TestGenerationService.js

@@ -8,6 +8,7 @@ import { getEntryPoint } from "../utils/telemetry.js";
 import { getLanguageSteps } from "../utils/language-helper.js";
 import { logger } from "../utils/logger.js";
 import { normalizeLanguageParams } from "../utils/normalizeParams.js";
+import { stageGeneratedPaths } from "../utils/gitStaging.js";
 export class TestGenerationService {
     client;
     constructor() {
@@ -324,6 +325,8 @@ The generated test file remains unchanged and ready to use as-is.
                     throw new Error(`Test generation failed: ${result}`);
                 }
             }
+            // Stage so testbot includes the generated files in its output commit.
+            await stageGeneratedPaths(generateOptions.outputDir);
             return `
 **Generated Test Details:**
 - Test Type: ${this.getTestType()}

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

@@ -4,6 +4,7 @@ import { getCodeReusePrompt } from "../../prompts/code-reuse.js";
 import { codeRefactoringSchema, languageSchema, } from "../../types/TestTypes.js";
 import { SKYRAMP_UTILS_HEADER } from "../../utils/utils.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
+import { stageGeneratedPaths } from "../../utils/gitStaging.js";
 const codeReuseSchema = z.object({
     testFile: z
         .string()
@@ -70,6 +71,8 @@ export function registerCodeReuseTool(server) {
                 language: params.language,
                 framework: params.framework,
             });
+            // Stage so testbot includes the generated files in its output commit.
+            await stageGeneratedPaths(params.testFile);
             const codeReusePrompt = getCodeReusePrompt(params.testFile, params.language, params.framework);
             return {
                 content: [

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

@@ -4,6 +4,8 @@ import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { getContractProviderAssertionsPrompt } from "../../prompts/enhance-assertions/contractProviderAssertionsPrompt.js";
 import { getIntegrationAssertionsPrompt } from "../../prompts/enhance-assertions/integrationAssertionsPrompt.js";
 import { getUIAssertionsPrompt } from "../../prompts/enhance-assertions/uiAssertionsPrompt.js";
+import { isTestbotEnabled } from "../../utils/featureFlags.js";
+import { stageGeneratedPaths } from "../../utils/gitStaging.js";
 const TOOL_NAME = "skyramp_enhance_assertions";
 const TESTBOT_UI_CHECKS = `
 ### Additional Testbot-Specific Checks
@@ -33,11 +35,13 @@ export function registerEnhanceAssertionsTool(server) {
         inputSchema: enhanceAssertionsSchema,
     }, async (params) => {
         const { testFile, testType, enhanceType } = 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 (process.env.SKYRAMP_FEATURE_TESTBOT === "1") {
+            if (isTestbotEnabled()) {
                 instructions += TESTBOT_UI_CHECKS;
             }
         }

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

@@ -6,6 +6,7 @@ import { ModularizationService, } from "../../services/ModularizationService.js"
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { normalizeLanguageParams, resolveParamAliases, } from "../../utils/normalizeParams.js";
 import { normalizeSkyrampImportsInFile } from "../../utils/normalizeSkyrampImports.js";
+import { stageGeneratedPaths } from "../../utils/gitStaging.js";
 const modularizationSchema = {
     testFile: z
         .string()
@@ -79,6 +80,8 @@ After modularization, if errors remain, call skyramp_fix_errors.
             if (!params.isTraceBased && [TestType.UI, TestType.E2E, TestType.INTEGRATION].includes(params.testType))
                 params.isTraceBased = true;
             normalizeSkyrampImportsInFile(params.testFile);
+            // Stage so testbot includes the generated files in its output commit.
+            await stageGeneratedPaths(params.testFile);
             // Default prompt to test file content
             if (!params.prompt && params.testFile) {
                 try {

package/build/tools/generate-tests/generateBatchScenarioRestTool.js

@@ -5,6 +5,7 @@ import fs from "fs";
 import { baseSchema, AUTH_PLACEHOLDER_TOKEN, HttpMethod } from "../../types/TestTypes.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { getWorkspaceAuthConfig, WorkspaceAuthType, getDefaultAuthHeader, isAuthorizationHeaderName, getAuthScheme } from "../../utils/workspaceAuth.js";
+import yaml from "js-yaml";
 import { logger } from "../../utils/logger.js";
 function isJsonValue(v) {
     if (v === undefined || v === null)
@@ -184,6 +185,126 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
                 logger.warning("Could not resolve auth from workspace config");
             }
         }
+        // Separate try/catch so auth errors don't silently swallow schema population.
+        // Walk up from outputDir with a sync existsSync check — one stat per level,
+        // one read+parse only when found — instead of an async readWorkspaceConfigRaw
+        // call (WorkspaceConfigManager instantiation + 2 async I/O ops) per level.
+        if (!params.apiSchema) {
+            try {
+                const WS_SUBPATH = path.join(".skyramp", "workspace.yml");
+                // Assumption: outputDir lives somewhere inside the repo tree so the walk-up
+                // eventually reaches .skyramp/workspace.yml. If outputDir is outside the repo
+                // (e.g. /tmp/skyramp-test), the loop exits at the filesystem root without finding
+                // the config — the surrounding try/catch handles this gracefully (non-critical).
+                let searchDir = path.resolve(params.outputDir);
+                let wsConfigPath = null;
+                while (searchDir !== path.dirname(searchDir)) {
+                    const candidate = path.join(searchDir, WS_SUBPATH);
+                    if (fs.existsSync(candidate)) {
+                        wsConfigPath = candidate;
+                        break;
+                    }
+                    searchDir = path.dirname(searchDir);
+                }
+                if (wsConfigPath) {
+                    const wsRaw = yaml.load(fs.readFileSync(wsConfigPath, "utf-8"));
+                    // Best-effort: picks the first service. Multi-service workspaces may have
+                    // the wrong schema if outputDir belongs to a later service — acceptable
+                    // limitation for now; the user can always pass apiSchema explicitly.
+                    const rawSchemaPath = wsRaw?.services?.[0]?.api?.schemaPath;
+                    if (rawSchemaPath && typeof rawSchemaPath === "string") {
+                        const isUrl = rawSchemaPath.startsWith("http://") || rawSchemaPath.startsWith("https://");
+                        // searchDir is the directory where workspace.yml was found — use it as
+                        // the resolution base so relative paths like "../openapi.yml" resolve
+                        // correctly regardless of outputDir depth.
+                        const schemaPath = isUrl
+                            ? rawSchemaPath
+                            : path.resolve(searchDir, rawSchemaPath);
+                        params = { ...params, apiSchema: schemaPath };
+                        logger.info("Auto-populated apiSchema from workspace config", { schemaPath });
+                    }
+                }
+            }
+            catch {
+                // non-critical
+            }
+        }
+        // ── Change 10b: Reject GraphQL endpoint steps ──
+        // Skyramp supports REST testing only; /graphql* requires introspection not implemented.
+        {
+            const graphqlSteps = params.steps.filter((s) => {
+                if (typeof s.path !== "string")
+                    return false;
+                const normalized = s.path.replace(/\/+$/, "").toLowerCase();
+                return normalized.split("/").some((seg) => seg === "graphql");
+            });
+            if (graphqlSteps.length > 0) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `GraphQL endpoints are not supported by Skyramp's test generation.\n` +
+                                `Affected steps: ${graphqlSteps.map((s) => `${s.method} ${s.path}`).join(", ")}\n\n` +
+                                `Skyramp supports REST API testing only. Remove GraphQL steps and use ` +
+                                `the REST endpoints for the same resource instead.`,
+                        }],
+                };
+            }
+        }
+        // ── Change 3: Soft spec path validation ──
+        // Warn when step paths are missing from the spec — proceed with generation regardless.
+        // Hard rejection was removed: specs frequently lag code (new endpoints, undocumented
+        // internal routes, stale auto-gen) so a missing path != a phantom path.
+        let specValidationWarning = "";
+        if (params.apiSchema) {
+            try {
+                const isUrl = params.apiSchema.startsWith("http://") || params.apiSchema.startsWith("https://");
+                let specText;
+                if (isUrl) {
+                    const specRes = await fetch(params.apiSchema, { signal: AbortSignal.timeout(10_000) });
+                    if (!specRes.ok) {
+                        throw new Error(`HTTP ${specRes.status} ${specRes.statusText} fetching spec at ${params.apiSchema}`);
+                    }
+                    specText = await specRes.text();
+                }
+                else {
+                    // Note: relative apiSchema paths resolve against outputDir, not the workspace root.
+                    // In practice apiSchema is always absolute (Gap Fix 2 / schema guidance), so this is safe.
+                    specText = fs.readFileSync(path.resolve(params.outputDir, params.apiSchema), "utf-8");
+                }
+                // js-yaml handles both JSON and YAML specs
+                const specLoaded = yaml.load(specText);
+                const specPaths = new Set(Object.keys((specLoaded && typeof specLoaded === "object" ? specLoaded.paths : null) ?? {}));
+                if (specPaths.size === 0) {
+                    logger.warning("Spec loaded but contains no paths — skipping path check", {
+                        apiSchema: params.apiSchema,
+                    });
+                }
+                else {
+                    const unverifiedSteps = params.steps.filter((s) => {
+                        if (typeof s.path !== "string")
+                            return false;
+                        const norm = s.path.replace(/:[a-zA-Z_][a-zA-Z0-9_]*/g, (m) => `{${m.slice(1)}}`);
+                        return !specPaths.has(s.path) && !specPaths.has(norm);
+                    });
+                    if (unverifiedSteps.length > 0) {
+                        specValidationWarning =
+                            `\n\n⚠️ **Spec warning** — the following paths were not found in \`${params.apiSchema}\` ` +
+                                `(spec may be stale or incomplete — verify paths against source before running tests):\n` +
+                                unverifiedSteps.map((s) => `  ${s.method} ${s.path}`).join("\n") +
+                                `\n\nKnown spec paths (first 20): ${[...specPaths].slice(0, 20).join(", ")}`;
+                        logger.warning("Step paths not found in spec — proceeding (spec may lag code)", {
+                            unverifiedPaths: unverifiedSteps.map((s) => s.path),
+                            apiSchema: params.apiSchema,
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                logger.warning("Spec check skipped — could not load apiSchema", {
+                    apiSchema: params.apiSchema,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
         const service = new ScenarioGenerationService();
         const steps = params.steps;
         const scenarioSlug = params.scenarioName.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "scenario";
@@ -261,7 +382,8 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
                         + `**Scenario:** ${params.scenarioName}\n`
                         + `**Steps:**\n${steps.map((s, i) => `  ${i + 1}. ${s.method} ${s.path} → ${s.statusCode ?? "default"}`).join("\n")}\n\n`
                         + `**File:** ${filePath}\n\n`
-                        + `**Next:** Call \`skyramp_integration_test_generation\` with \`scenarioFile: "${filePath}"\``,
+                        + `**Next:** Call \`skyramp_integration_test_generation\` with \`scenarioFile: "${filePath}"\``
+                        + specValidationWarning,
                 },
             ],
             isError: false,