@skyramp/mcp 0.0.62 → 0.0.63-rc.1

package/build/index.js

@@ -24,12 +24,7 @@ import { registerRecommendTestsPrompt } from "./prompts/test-recommendation/regi
 import { registerModularizationTool } from "./tools/code-refactor/modularizationTool.js";
 import { registerCodeReuseTool } from "./tools/code-refactor/codeReuseTool.js";
 import { registerScenarioTestTool } from "./tools/generate-tests/generateScenarioRestTool.js";
-import { registerDiscoverTestsTool } from "./tools/test-maintenance/discoverTestsTool.js";
-import { registerAnalyzeTestDriftTool } from "./tools/test-maintenance/analyzeTestDriftTool.js";
-import { registerExecuteBatchTestsTool } from "./tools/test-maintenance/executeBatchTestsTool.js";
-import { registerCalculateHealthScoresTool } from "./tools/test-maintenance/calculateHealthScoresTool.js";
-import { registerActionsTool } from "./tools/test-maintenance/actionsTool.js";
-import { registerStateCleanupTool } from "./tools/test-maintenance/stateCleanupTool.js";
+import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerExecuteTestsTool, registerActionsTool, registerStateCleanupTool, } from "./tools/test-management/index.js";
 import { registerTestbotPrompt, registerTestbotResource, } from "./prompts/testbot/testbot-prompts.js";
 import { registerInitTestbotTool } from "./tools/initTestbotTool.js";
 import { registerSubmitReportTool } from "./tools/submitReportTool.js";
@@ -66,6 +61,12 @@ const server = new McpServer({
 2. Call \`skyramp_recommend_tests\` with \`sessionId\` → the LLM reasons over the
    enriched data to recommend tests, referencing specific interactions and scenarios.
 
+## Test Health Analysis Flow (4-step)
+1. Call \`skyramp_analyze_changes\` with \`repositoryPath\` and \`scope\` → discovers existing tests, scans endpoints, computes branch diff → returns a \`stateFile\`.
+2. Call \`skyramp_analyze_test_health\` with \`stateFile\` → runs drift analysis + health scoring + LLM semantic assessment → returns enriched \`stateFile\`.
+3. (Optional) Call \`skyramp_execute_tests\` with \`stateFile\` → runs tests live to verify status.
+4. Call \`skyramp_actions\` with \`stateFile\` → executes UPDATE/REGENERATE/ADD recommendations.
+
 After analysis, you can also inspect data via MCP Resources:
 - \`skyramp://analysis/{sessionId}/summary\` — high-level overview
 - \`skyramp://analysis/{sessionId}/endpoints\` — compact endpoint listing
@@ -188,11 +189,10 @@ registerAnalyzeRepositoryTool(server);
 registerRecommendTestsTool(server);
 // Register analysis resources (MCP Resources for enriched data access)
 registerAnalysisResources(server);
-// Register test maintenance tools
-registerDiscoverTestsTool(server);
-registerAnalyzeTestDriftTool(server);
-registerExecuteBatchTestsTool(server);
-registerCalculateHealthScoresTool(server);
+// Register unified test-management tools (replaces separate test-maintenance tools)
+registerAnalyzeChangesTool(server);
+registerAnalyzeTestHealthTool(server);
+registerExecuteTestsTool(server);
 registerActionsTool(server);
 registerStateCleanupTool(server);
 // Register workspace management tools

package/build/prompts/test-maintenance/drift-analysis-prompt.js

@@ -0,0 +1,59 @@
+import { buildDriftScoringGuide, buildActionDecisionMatrix, buildBreakingChangePatterns, buildTestAssessmentGuidelines, buildAddRecommendationGuidelines, buildDriftOutputChecklist, } from "./driftAnalysisSections.js";
+export function buildDriftAnalysisPrompt(params) {
+    const { existingTests, parsedDiff, scannedEndpoints, repositoryPath, stateFile } = params;
+    // Detect new endpoints count from parsedDiff
+    let newEndpointCount = 0;
+    let diffSection = "";
+    if (parsedDiff) {
+        const lines = parsedDiff.split("\n");
+        const epMatches = parsedDiff.match(/(?:^|\n)\*\*(GET|POST|PUT|PATCH|DELETE)\s+[^\*]+\*\*/gm);
+        if (epMatches)
+            newEndpointCount = epMatches.length;
+        diffSection = `## Branch Diff
+\`\`\`
+${lines.slice(0, 200).join("\n")}
+\`\`\`
+`;
+    }
+    const testListSection = existingTests.length > 0
+        ? `## Existing Test Files (${existingTests.length})
+${existingTests
+            .map((t) => {
+            const score = t.drift?.driftScore !== undefined ? ` [drift: ${t.drift.driftScore}]` : "";
+            return `- ${t.testFile} (${t.testType})${score}`;
+        })
+            .join("\n")}
+`
+        : `## Existing Test Files
+No existing Skyramp tests found in repository.
+`;
+    const scannedSection = scannedEndpoints.length > 0
+        ? `## Scanned Endpoints (${scannedEndpoints.length})
+${scannedEndpoints.map((ep) => `- ${Array.isArray(ep.methods) ? ep.methods.join("|") : ep.method} ${ep.path}`).join("\n")}
+`
+        : "";
+    return `# Test Health Analysis
+
+**Repository**: \`${repositoryPath}\`
+**Existing tests**: ${existingTests.length}
+**New endpoints in diff**: ${newEndpointCount}
+
+${diffSection}
+${testListSection}
+${scannedSection}
+${buildDriftScoringGuide()}
+
+${buildActionDecisionMatrix()}
+
+${buildBreakingChangePatterns()}
+
+${buildTestAssessmentGuidelines()}
+
+${buildAddRecommendationGuidelines()}
+
+${buildDriftOutputChecklist(existingTests.length, newEndpointCount)}
+
+After completing the assessment above, call \`skyramp_actions\` with \`stateFile: "${stateFile}"\`
+
+**CRITICAL**: Do NOT create any .json or .md files. Only call skyramp_actions when done.`;
+}

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

@@ -0,0 +1,153 @@
+/**
+ * Modular section builders for the Drift Analysis prompt,
+ * mirroring the recommendationSections.ts pattern.
+ */
+export function buildDriftScoringGuide() {
+    return `## Drift Score Guide (0–100)
+
+| Score | Label | Meaning |
+|-------|-------|---------|
+| 0–20  | IGNORE | No meaningful drift — test is still valid as-is |
+| 21–40 | VERIFY | Minor changes detected — review but likely fine |
+| 41–70 | UPDATE | Breaking changes detected — test needs edits |
+| 71–100 | REGENERATE | Major structural changes — regenerate from scratch |
+
+Assign each existing test a score based on how much the codebase has changed relative to what the test expects.`;
+}
+export function buildActionDecisionMatrix() {
+    return `## Action Decision Matrix
+
+For each test, choose one of:
+
+| Action | When to use |
+|--------|------------|
+| **IGNORE** | Drift score 0–20; no breaking changes AND no additive field gaps detected |
+| **VERIFY** | Drift score 21–40; minor changes, manual review recommended |
+| **UPDATE** | Drift score 25–70; breaking changes OR additive fields added to a covered endpoint (new response field the test doesn't assert) |
+| **REGENERATE** | Drift score 71–100; endpoint removed, major restructuring, or test is fundamentally broken |
+| **ADD** | New endpoint detected in diff that has no corresponding test yet |
+
+Rules:
+- Prefer UPDATE over REGENERATE when changes are localized (e.g., only the URL path changed).
+- Prefer IGNORE over VERIFY when all changed files are unrelated to the test's endpoint.
+- Always use ADD for new endpoints when the action is scoped to new test creation.
+- **Additive changes (new response fields) on a covered endpoint always trigger UPDATE** — even if existing assertions still pass. The test needs a new assertion for the added field.`;
+}
+export function buildBreakingChangePatterns() {
+    return `## Breaking Change Patterns to Detect
+
+Scan the diff lines for these high-signal patterns:
+
+### Endpoint-level breaking changes
+- \`-  @app.route("/old-path")\` / \`+  @app.route("/new-path")\` — renamed endpoint
+- \`-  router.get("/old")\` / \`+  router.get("/new")\` — renamed route
+- \`-  @GetMapping("/old")\` / \`+  @GetMapping("/new")\` — Spring rename
+- Lines removing a route decorator entirely (endpoint removed)
+
+### Request/response shape changes
+- Field type changes: \`- field: int\` → \`+ field: string\`
+- Required field added: \`+ required: [..., "newField"]\`
+- Response field removed: \`- "responseField":\`
+- Enum value changes: \`- status: "active"\` → \`+ status: "enabled"\`
+
+### Auth changes
+- \`+ @require_auth\`, \`+ @login_required\`, \`+ middleware(authMiddleware)\`
+- \`- @require_auth\` (auth removed)
+- Token type changed: Bearer → Cookie
+
+### Status code changes
+- \`- return 200\` → \`+ return 201\`
+- \`- status_code=200\` → \`+ status_code=204\`
+- \`- res.status(201)\` → \`+ res.status(200)\`
+
+### Additive response field changes (non-breaking but coverage gap)
+These do NOT break existing assertions but leave the new field untested. Always flag as UPDATE for covered endpoints.
+- \`+ "newField": queryset.filter(...).count()\` added inside a \`Response({...})\` or \`res.json({...})\`
+- \`+ newField = serializers.XXXField()\` added to a serializer used by a tested endpoint
+- \`+ "newField":\` added to a response body dict returned by the endpoint
+- New key added inside an existing dict/object returned by the endpoint`;
+}
+export function buildTestAssessmentGuidelines() {
+    return `## Per-Test Assessment (4 Steps)
+
+For each existing test file, follow these steps:
+
+### Step 1: Check endpoint existence
+Does the endpoint the test targets still exist in the codebase?
+- If the endpoint path/method is no longer present → score 80+, action: REGENERATE
+- If the endpoint was renamed → score 50–70, action: UPDATE (path substitution)
+
+### Step 2: Check request/response shape (breaking changes)
+Has the request body or response structure changed in a way that breaks the test?
+- Compare test's expected fields against current schema/model definitions
+- Type changes (string→int, int→string) → score 60+, action: UPDATE or REGENERATE
+- New required fields the test doesn't send → score 50+, action: UPDATE
+- Response fields the test asserts on have been removed → score 50+, action: UPDATE
+
+### Step 2b: Check additive response field changes (coverage gaps)
+**Even if existing assertions still pass**, does the diff add a new field to the response of an endpoint this test already covers?
+- Look at the diff for lines like \`+ "newField":\` or \`+ newField =\` inside a view/serializer this test hits
+- If YES → score 30, action: UPDATE — add an assertion for the new field (e.g. \`assert "newField" in response_body\` or \`assert response_body["newField"] >= 0\`)
+- This applies even when the test only checks status codes — the test should be extended to cover the new field
+- **Do NOT score IGNORE if a new response field was added to a covered endpoint**
+
+### Step 3: Check auth changes
+Has the authentication mechanism for this endpoint changed?
+- Auth added where none existed → score 40+, action: UPDATE
+- Auth method changed (bearer→cookie) → score 50+, action: UPDATE
+- Auth removed → score 30+, action: VERIFY or UPDATE
+
+### Step 4: Assign score and action
+Based on the above, assign a final drift score 0–100 and choose the action (IGNORE / VERIFY / UPDATE / REGENERATE).
+Provide a 1-2 sentence rationale.
+- If Step 2b flagged an additive field → score must be ≥ 30 and action must be UPDATE, even if Steps 2/3 found no breaking changes.`;
+}
+export function buildAddRecommendationGuidelines() {
+    return `## ADD Recommendations for New Endpoints
+
+For each new endpoint detected in the diff (not yet covered by any existing test):
+
+### Test type priority by HTTP method
+| Method | Recommended test types |
+|--------|----------------------|
+| POST / PUT / PATCH | integration, contract |
+| GET | contract, smoke |
+| DELETE | integration, smoke |
+
+### ADD recommendation format
+For each new endpoint, include:
+1. The endpoint path and method
+2. The recommended test types (from the table above)
+3. The Skyramp tool to call (e.g., \`skyramp_contract_test_generation\`, \`skyramp_integration_test_generation\`)
+4. The \`endpointURL\` to use (combine base URL + path)
+5. The language/framework to use (from workspace config or project metadata)`;
+}
+export function buildDriftOutputChecklist(existingTestCount, newEndpointCount) {
+    return `## Output Checklist
+
+Complete ALL of the following before calling skyramp_actions:
+
+### Existing tests (${existingTestCount} total)
+For EACH existing test, output:
+\`\`\`
+Test: <testFile>
+Drift Score: <0-100>
+Action: <IGNORE | VERIFY | UPDATE | REGENERATE>
+Rationale: <1-2 sentence explanation>
+\`\`\`
+
+${newEndpointCount > 0
+        ? `### New endpoints (${newEndpointCount} detected)
+For EACH new endpoint, output:
+\`\`\`
+Endpoint: <METHOD> <path>
+Action: ADD
+Test types: <contract | integration | smoke | ...>
+Rationale: <1 sentence>
+\`\`\``
+        : `### New endpoints
+No new endpoints detected in this diff.`}
+
+### Final step
+After completing all assessments above, call \`skyramp_actions\` with the stateFile to execute the recommended changes.`;
+}

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

@@ -1,6 +1,12 @@
 function buildEnrichmentInstructions(p) {
     const isDiffScope = p.analysisScope === "current_branch_diff";
+    const useHealthFlow = p.nextTool === "skyramp_analyze_test_health";
     if (!isDiffScope) {
+        const nextStep = useHealthFlow
+            ? `### Step 3: Identify tests at risk of drift
+Call \`skyramp_analyze_test_health\` with \`stateFile: "${p.sessionId}"\``
+            : `### Step 3: Call recommend tests
+Call \`skyramp_recommend_tests\` with \`sessionId: "${p.sessionId}"\``;
         return `## Your Task — Enrich & Recommend (full repo)
 
 ### Step 1: Read key files
@@ -12,8 +18,7 @@ to understand the tech stack, endpoint shapes, auth mechanisms, and request/resp
 Map how endpoints relate to each other — which POST creates resources consumed by other endpoints?
 **Resolve nested/sub-router paths** from the Router Mounting section above.
 
-### Step 3: Call recommend tests
-Call \`skyramp_recommend_tests\` with \`sessionId: "${p.sessionId}"\``;
+${nextStep}`;
     }
     const changedFiles = p.parsedDiff?.changedFiles.join(", ") ?? "";
     const hasApiEndpoints = p.parsedDiff && (p.parsedDiff.newEndpoints.length > 0 || p.parsedDiff.modifiedEndpoints.length > 0);
@@ -29,14 +34,13 @@ Mounting context.`
 UI-only PR — read changed components to find API calls (fetch, axios, hooks).`
             : `### Step 2: Identify affected endpoints
 No API route changes detected — read changed files to identify affected endpoints.`;
-    return `## Your Task — Enrich & Recommend (PR-scoped)
-
-### Step 1: Read the changed files
-${changedFiles}
-
-${step2}
+    const step3Content = useHealthFlow
+        ? `### Step 3: Identify tests at risk of drift
+Assess which existing tests may be broken by the changes in this diff.
 
-### Step 3: Draft integration scenarios
+### Step 4: Call analyze test health
+Call \`skyramp_analyze_test_health\` with \`stateFile: "${p.sessionId}"\``
+        : `### Step 3: Draft integration scenarios
 Draft multi-step scenarios simulating realistic user workflows:
 - **Cross-resource data flow**: Foreign key relationships, parent→child creation, verification
 - **Search/filter verification**: Create data, search, verify results
@@ -47,6 +51,14 @@ Draft multi-step scenarios simulating realistic user workflows:
 
 ### Step 4: Call recommend tests
 Call \`skyramp_recommend_tests\` with \`sessionId: "${p.sessionId}"\``;
+    return `## Your Task — Enrich & Recommend (PR-scoped)
+
+### Step 1: Read the changed files
+${changedFiles}
+
+${step2}
+
+${step3Content}`;
 }
 export function buildAnalysisOutputText(p) {
     const isDiffScope = p.analysisScope === "current_branch_diff";

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

@@ -10,11 +10,18 @@ export function buildRecommendationPrompt(analysis, analysisScope = "full_repo",
     const isDiffScope = analysisScope === "current_branch_diff";
     const diffContext = analysis.branchDiffContext;
     const openApiSpec = analysis.artifacts?.openApiSpecs?.[0];
+    // ── Filter out bot-generated test files from changedFiles ──
+    // Prevents bot-committed test files from being treated as application changes
+    // on subsequent testbot runs on the same PR.
+    const SKYRAMP_TEST_FILE_PATTERN = /(?:_test|_smoke|_contract|_fuzz|_integration|_load|_e2e|_ui)\.[^/]+$|scenario_[^/]+\.json$/;
+    const filteredChangedFiles = diffContext
+        ? diffContext.changedFiles.filter(f => !SKYRAMP_TEST_FILE_PATTERN.test(f))
+        : [];
     // ── Frontend / UI change detection ──
     const FRONTEND_FILE_PATTERN = /\.(tsx?|jsx?|vue|svelte|css|scss|less|html)$/;
     const API_DIR_PATTERN = /\/(api|routes?|controllers?|routers?|handlers?|endpoints?|server)\//;
     const hasFrontendChanges = isDiffScope && diffContext
-        ? diffContext.changedFiles.some(f => FRONTEND_FILE_PATTERN.test(f) &&
+        ? filteredChangedFiles.some(f => FRONTEND_FILE_PATTERN.test(f) &&
             !API_DIR_PATTERN.test(f) &&
             /\/(components?|pages?|views?|layouts?|app|src\/app|frontend|client|public|styles?)\//i.test(f))
         : false;
@@ -62,7 +69,7 @@ ${endpointLines}
         diffSection = `
 ## Branch Diff Context
 Branch: \`${diffContext.currentBranch}\` → base: \`${diffContext.baseBranch}\`
-Changed files: ${diffContext.changedFiles.join(", ")}
+Changed files: ${filteredChangedFiles.join(", ")}
 New endpoints:
 ${fmtEps(diffContext.newEndpoints, (m) => `${m.sourceFile}, ${m.interactionCount} interactions`)}
 Modified endpoints:

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

@@ -3,115 +3,116 @@ import { z } from "zod";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { MAX_TESTS_TO_GENERATE, MAX_RECOMMENDATIONS } from "../test-recommendation/recommendationSections.js";
-function getTestbotPrompt(prTitle, prDescription, diffFile, testDirectory, summaryOutputFile, repositoryPath, baseBranch, maxRecommendations = MAX_RECOMMENDATIONS, maxGenerate = MAX_TESTS_TO_GENERATE) {
+function getTestbotPrompt(prTitle, prDescription, diffFile, testDirectory, summaryOutputFile, repositoryPath, baseBranch, maxRecommendations = MAX_RECOMMENDATIONS, maxGenerate = MAX_TESTS_TO_GENERATE, prNumber) {
     return `<TITLE>${prTitle}</TITLE>
 <DESCRIPTION>${prDescription}</DESCRIPTION>
 <CODE CHANGES>${diffFile}</CODE CHANGES>
 <TEST DIRECTORY>${testDirectory}</TEST DIRECTORY>
 <REPOSITORY PATH>${repositoryPath}</REPOSITORY PATH>
 
-Use the Skyramp MCP server tools for all tasks below.
-
-## Task 1: Recommend & Generate New Tests
-
-Read the diff at \`${diffFile}\`. Skip Task 1 if all changed files are non-application
-(CI/CD, docs, lock files, config). Otherwise proceed:
-
-### Steps
-
-1. Call \`skyramp_analyze_repository\` with \`repositoryPath\`: "${repositoryPath}", \`analysisScope\`: "current_branch_diff"${baseBranch ? `\n   , \`baseBranch\`: "${baseBranch}"` : ''}
-2. Call \`skyramp_recommend_tests\` with the returned \`sessionId\`.
-   It returns ${maxRecommendations} ranked recommendations. Walk through them in rank order and generate
-   up to ${maxGenerate} tests. Any recommendation you skip or cannot generate goes to
-   \`additionalRecommendations\`.
-
-3. **Generate** up to ${maxGenerate} tests by walking the ranked list top-to-bottom:
-   - If a recommendation can be generated, generate it and count it.
-   - If it cannot (e.g. E2E/UI without traces), move it to \`additionalRecommendations\`
-     and continue to the next recommendation.
-   - Stop once you have ${maxGenerate} generated tests OR exhaust all ${maxRecommendations} recommendations.
-   - All remaining (ungenerated) recommendations go to \`additionalRecommendations\`.
-   Keep a list of every file the CLI creates (test files AND scenario JSON files).
-
-   **Frontend-only PRs** (no backend/API changes): only generate tests if relevant
-   Playwright traces exist. If no traces are available, skip generation entirely and
-   move all ${maxRecommendations} recommendations to \`additionalRecommendations\` with scenario steps and
-   trace recording instructions. Do not generate integration tests for unchanged backend
-   APIs just to fill the quota — those tests don't validate the PR's changes.
-
-   **How to generate each type:**
-   - **Integration**: call \`skyramp_scenario_test_generation\` per step, then
-     \`skyramp_integration_test_generation\` with the scenario file.
-     The scenario JSON is written to the same \`outputDir\` as the test files
-     (e.g. \`tests/scenario_<name>.json\`), not \`.skyramp/\`.
-   - **Contract**: call \`skyramp_contract_test_generation\` with \`endpointURL\`, \`method\`,
-     and \`requestData\` for POST/PUT endpoints.
-     Pass \`apiSchema\` if an OpenAPI spec exists — it validates response structure.
-   - **Fuzz**: call \`skyramp_fuzz_test_generation\` with \`endpointURL\`, \`method\`, \`requestData\`.
-     Pass \`apiSchema\` if available — it generates smarter boundary values.
-   - **E2E/UI**: only generate when relevant Playwright traces exist (see step 5).
-     Without traces, move the test to \`additionalRecommendations\` with scenario steps
-     and trace recording instructions instead.
-   - Skip smoke tests entirely.
-
-   **Scenario quality:** Before generating, verify each step's preconditions are met by
-   prior steps. For example, you can't update a membership that was never created — check
-   the controller code for existence checks and ensure the scenario creates records first.
-
-   **Filenames:** Pass a descriptive \`--output\` name per test to avoid CLI overwrites.
-
-4. **Execute** the generated tests and record results.
-
-5. **Trace search** for E2E/UI: look in \`\${testDirectory}\`, repo root, and \`.skyramp/\` for
-   trace files (\`*trace*.json\`, \`*playwright*.zip\`). Only use a trace if it covers code
-   changed in this PR and targets localhost — skip traces for external hosts or unrelated code.
-
-   With relevant traces: backend + Playwright → \`skyramp_e2e_test_generation\`,
-   Playwright only → \`skyramp_ui_test_generation\`.
-
-**After generation, fix chaining only.** The CLI may use literal/hardcoded IDs instead
-of dynamic values from prior responses. Fix these two cases:
-1. **Path params:** variables like \`product_id = 'product_id'\` → use the response accessor
-   (e.g. \`getResponseValue(response, "response.id")\` in TS, \`skyramp.get_response_value(response, "id")\` in Python).
-2. **Request body refs:** hardcoded IDs in request bodies (e.g. \`"product_id": 1\`) → replace
-   with the dynamic ID extracted from the prior POST response (e.g. \`product_id\` variable or
-   \`dataOverride\`/\`data_override\` for the field).
-
-Change ONLY chaining-related values (path param assignments and body ID references).
-Preserve everything else exactly as the CLI generated it — headers, auth code, assertions,
-imports, and all other request body fields.
-
-## Task 2: Existing Test Maintenance
-
-Run this task regardless of Task 1 outcome — even if Task 1 was skipped or generated zero tests.
-
-1. Call \`skyramp_discover_tests\` with \`repositoryPath\`: "${repositoryPath}".
-2. If zero Skyramp tests found, report \`testMaintenance\` as an empty array.
-   This is expected for new repos — pass \`issuesFound\` as an empty array \`[]\`. Do not add a "no tests found" entry.
-3. If tests exist:
-   a. Baseline them (from CI status or by executing).
-   b. Run \`skyramp_analyze_test_drift\` → \`skyramp_calculate_health_scores\` → \`skyramp_actions\`.
-   c. Apply actions (path renames, schema updates) in-place. Do not regenerate.
-   d. Execute modified tests. Report before/after in \`testMaintenance\`.
-
-## Task 3: Submit Report
-
-Verify Tasks 1 and 2 are complete, then call \`skyramp_submit_report\` with
-\`summaryOutputFile\`: "${summaryOutputFile}".
+Use the Skyramp MCP server tools. Follow the steps below in order.
+
+---
+
+## Step 1: Analyze
+
+Read the diff at \`${diffFile}\`.
+If all changed files are non-application (CI/CD, docs, lock files, config only) → skip to Step 4 (Submit Report) with empty arrays.
+
+Otherwise:
+1. Call \`skyramp_analyze_changes\` with \`repositoryPath\`: "${repositoryPath}", \`scope\`: "branch_diff", \`topN\`: ${maxRecommendations}${prNumber ? `, \`prNumber\`: ${prNumber}` : ""} — discovers existing Skyramp tests, scans endpoints changed in the diff, loads workspace config, and returns ${maxRecommendations} ranked ADD recommendations.${prNumber ? " Uses PR comment history to avoid re-recommending already-generated tests." : ""}
+2. Call \`skyramp_analyze_test_health\` with the \`stateFile\` from step 1 (skip if zero existing tests found) — scores each existing test for drift against the diff and assigns UPDATE / REGENERATE / VERIFY / ADD actions.
+
+---
+
+## Step 2: Decide — one action per affected test / endpoint
+
+Using the diff, the recommendations, and the health assessment, assign exactly one action to each item:
+
+### For each **existing Skyramp test**:
+- **UPDATE** — the diff touches the endpoint this test covers AND adds/changes fields the test should assert (e.g. new response field, changed status code, renamed path). The test still runs but has a coverage gap or will break.
+- **REGENERATE** — the endpoint was substantially restructured or the test is fundamentally broken by the diff.
+- **VERIFY** — the diff touches related code but the test is unaffected; no action needed.
+- **DELETE** — the endpoint the test covers was removed entirely.
+- **ADD** — existing tests for this endpoint do not capture a new scenario introduced by the diff (e.g. a new flow, a new field combination). A net-new test is needed alongside the existing ones.
+
+### For each **endpoint whose route definition is new in the diff** (no existing Skyramp test):
+- **ADD** — the diff introduced this route; generate a new test.
+- **VERIFY** — the endpoint existed before this diff (only a model/field change touched it); log as a coverage gap but do not generate a test.
+
+### Decision rules (apply in order):
+1. If the diff adds/removes/renames a field in a response this test asserts → **UPDATE** (not ADD).
+2. If the diff adds a **brand-new route definition** (e.g. a new \`@router.get\`, \`@app.route\`, \`router.get()\` line) → **ADD**.
+3. If an existing test covers the endpoint but doesn't test the specific new scenario (e.g. archived=true flow) → **ADD** (alongside the existing test).
+4. If the test is unrelated to the diff → **VERIFY** (no action).
+5. Only use **ADD** for endpoints whose route was introduced in this diff. An endpoint that existed before but now lacks a test is a pre-existing coverage gap — log it in \`additionalRecommendations\`, do NOT generate a test for it.
+6. Do NOT add a new test when an UPDATE to an existing test is the right fix.
+
+Output your decision table:
+\`\`\`
+Test/Endpoint | Action | Reason
+<file or METHOD /path> | <ACTION> | <1 sentence>
+\`\`\`
+
+---
+
+## Step 3: Act
+
+Execute the actions from Step 2. Limit total generated/updated tests to ${maxGenerate}.
+
+### UPDATE
+Edit the existing test file directly:
+- Add missing assertions for new response fields (e.g. \`assert "archived" in resp\` or \`assert resp["archived"] >= 0\`).
+- Fix path/method changes in the test.
+- Do not regenerate — only apply the minimal change needed.
+
+### REGENERATE
+Call the appropriate generation tool to replace the existing test from scratch.
+Use the same filename so it overwrites the old file.
+
+### ADD
+Generate a net-new test. Use a unique descriptive filename to avoid overwriting existing files.
+
+**How to generate each type (for ADD and REGENERATE):**
+- **Integration**: call \`skyramp_scenario_test_generation\` per step (sequentially), then \`skyramp_integration_test_generation\` with the scenario file.
+  Scenario JSON goes in the same \`outputDir\` (e.g. \`tests/scenario_<name>.json\`), not \`.skyramp/\`.
+- **Contract**: call \`skyramp_contract_test_generation\` with \`endpointURL\`, \`method\`, and \`requestData\` for POST/PUT/PATCH.
+  Pass \`apiSchema\` if an OpenAPI spec exists.
+- **Fuzz**: call \`skyramp_fuzz_test_generation\` with \`endpointURL\`, \`method\`, \`requestData\`.
+- **E2E/UI**: only if relevant Playwright traces exist in \`${testDirectory}\`, repo root, or \`.skyramp/\`.
+  Without traces, move to \`additionalRecommendations\` with scenario steps and trace recording instructions.
+- Skip smoke tests entirely.
+
+**Scenario quality:** Verify preconditions before each step (e.g. create before update).
+
+**After generation, fix chaining only:**
+- Path params like \`id = 'id'\` → \`skyramp.get_response_value(prev_response, "id")\`
+- Hardcoded IDs in request bodies → dynamic values from prior response
+- Change ONLY chaining values. Preserve everything else exactly as generated.
+
+After all actions, execute the changed/generated test files and record pass/fail.
+
+### VERIFY / DELETE
+- VERIFY: no file changes. Note in \`testMaintenance\`.
+- DELETE: remove the test file.
+
+---
+
+## Step 4: Submit Report
+
+Call \`skyramp_submit_report\` with \`summaryOutputFile\`: "${summaryOutputFile}".
 
 \`commitMessage\`: under 72 chars, e.g. "add integration tests for /products and /orders"
 
-**newTestsCreated** — list every generated test file (at most ${maxGenerate}):
-   \`testType\`, \`endpoint\`, \`fileName\`, \`description\`, \`scenarioFile\`, \`traceFile\`, \`frontendTrace\`
-   Use the actual file path returned by the generation tool for \`scenarioFile\`.
-   Include scenario JSON files in the git commit alongside test files.
-   Every test file in the commit should appear here. If you over-generated, delete extras first.
-   If no tests were generated (e.g. frontend-only PR without traces), pass an empty array.
+**newTestsCreated** — every file generated or updated (at most ${maxGenerate}):
+   \`testType\`, \`endpoint\`, \`fileName\`, \`description\`, \`scenarioFile\`
+   If action was UPDATE, set \`testType\` to \`"<type> (updated)"\`.
+   If no tests were generated or updated, pass an empty array.
 
-**additionalRecommendations** — remaining recommendations not generated:
-   \`testType\`, \`scenarioName\`, \`priority\`, \`description\`, \`steps\`, artifact paths
+**additionalRecommendations** — items you could not act on (quota exceeded, no traces, etc.):
+   \`testType\`, \`scenarioName\`, \`priority\`, \`description\`, \`steps\`
 
-**businessCaseAnalysis** — based only on PR data and tool outputs.`;
+**businessCaseAnalysis** — 2-3 sentences based only on the diff and tool outputs.`;
 }
 export function registerTestbotPrompt(server) {
     logger.info("Registering testbot prompt");
@@ -144,9 +145,13 @@ export function registerTestbotPrompt(server) {
                 .number()
                 .default(MAX_TESTS_TO_GENERATE)
                 .describe(`Maximum number of tests to generate.`),
+            prNumber: z
+                .number()
+                .optional()
+                .describe("GitHub PR number. Passed to skyramp_analyze_changes to fetch previous TestBot comments for recommendation consistency across commits."),
         },
     }, (args) => {
-        const prompt = getTestbotPrompt(args.prTitle, args.prDescription, args.diffFile, args.testDirectory, args.summaryOutputFile, args.repositoryPath, args.baseBranch, args.maxRecommendations, args.maxGenerate);
+        const prompt = getTestbotPrompt(args.prTitle, args.prDescription, args.diffFile, args.testDirectory, args.summaryOutputFile, args.repositoryPath, args.baseBranch, args.maxRecommendations, args.maxGenerate, args.prNumber);
         AnalyticsService.pushMCPToolEvent("skyramp_testbot_prompt", undefined, {}).catch(() => { });
         return {
             messages: [
@@ -179,7 +184,8 @@ export function registerTestbotResource(server) {
         const param = (name, fallback) => uri.searchParams.get(name) ?? fallback;
         const maxRec = parseInt(uri.searchParams.get("maxRecommendations") || "", 10);
         const maxGen = parseInt(uri.searchParams.get("maxGenerate") || "", 10);
-        const prompt = getTestbotPrompt(param("prTitle", ""), param("prDescription", ""), param("diffFile", ".skyramp_git_diff"), param("testDirectory", "tests"), param("summaryOutputFile", ""), param("repositoryPath", "."), uri.searchParams.get("baseBranch") || undefined, isNaN(maxRec) ? MAX_RECOMMENDATIONS : maxRec, isNaN(maxGen) ? MAX_TESTS_TO_GENERATE : maxGen);
+        const prNum = parseInt(uri.searchParams.get("prNumber") || "", 10);
+        const prompt = getTestbotPrompt(param("prTitle", ""), param("prDescription", ""), param("diffFile", ".skyramp_git_diff"), param("testDirectory", "tests"), param("summaryOutputFile", ""), param("repositoryPath", "."), uri.searchParams.get("baseBranch") || undefined, isNaN(maxRec) ? MAX_RECOMMENDATIONS : maxRec, isNaN(maxGen) ? MAX_TESTS_TO_GENERATE : maxGen, isNaN(prNum) ? undefined : prNum);
         AnalyticsService.pushMCPToolEvent("skyramp_testbot_prompt", undefined, {}).catch(() => { });
         return {
             contents: [

package/build/services/ScenarioGenerationService.js

@@ -129,9 +129,13 @@ ${JSON.stringify(traceRequest, null, 2)}
             .some(v => v.includes("application/json"));
         const responseBody = params.responseBody || (isJsonResponse ? "{}" : "");
         const authHeaderName = params.authHeader || "Authorization";
+        let authValue = params.authToken ?? "";
+        if (!authValue && authHeaderName === "Authorization") {
+            authValue = "Bearer SKYRAMP_PLACEHOLDER_TOKEN";
+        }
         const requestHeaders = {
             "Content-Type": ["application/json"],
-            [authHeaderName]: [params.authToken ?? ""],
+            [authHeaderName]: [authValue],
         };
         return {
             Source: "192.168.65.1:39998",