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

package/build/tools/submitReportTool.js

@@ -12,6 +12,7 @@ import { toolError, testFileMatches } from "../utils/utils.js";
 import { matchesApprovedPlan } from "../utils/planMatchKeys.js";
 import { isTestbotEnabled } from "../utils/featureFlags.js";
 import { findUnbackedClaims, listChangedFiles } from "../utils/reportVerification.js";
+import { rederiveReuseOutcome } from "./code-refactor/reuse-state.js";
 // SKYR-3879 Path B: which testTypes the register-plan checkpoint gates. Mirrors
 // the generation tools actually wired to planGuard (batch-scenario/integration,
 // contract) — UI and E2E are on a separate blueprint-grounded pipeline and are
@@ -337,6 +338,34 @@ function computeReportMetrics(params) {
         issuesLow: String(countBy(params.issuesFound, (i) => i.severity === "low")),
     };
 }
+/**
+ * Attach the POM code-reuse outcome for a UI test, matched by the report's
+ * `fileName` (the basename skyramp_reuse_code keyed run state on).
+ *
+ * Server-derived, never supplied by the LLM — the same line this file already
+ * draws for testMaintenance's beforeStatus/afterStatus. `skyramp_reuse_code`
+ * computes every value in-process (tier-1 detection by selectScopedPoms, the call
+ * counts and violations by verifyReuse, the declines from the `// kept inline:`
+ * comments in the spec), so asking the agent to read them out of tool text and
+ * retype them later would leave the signal prose-mediated — droppable and
+ * fabricable, which is the failure this field exists to fix.
+ *
+ * The counts are RE-DERIVED from the delivered spec rather than read back from
+ * state: the execution fix-up can restore `<testFile>.raw.bak` over it afterwards
+ * by plain `cp`, which this tool never sees. See rederiveReuseOutcome.
+ *
+ * Non-UI tests, tests the reuse tool never ran for, and specs whose outcome cannot
+ * be re-derived all get nothing — which consumers already treat as "no reuse
+ * summary". */
+async function attachReuseOutcome(test, outcomes) {
+    if (test.testType !== TestType.UI || !outcomes)
+        return test;
+    const found = outcomes[path.basename(test.fileName)];
+    if (!found)
+        return test;
+    const reuse = await rederiveReuseOutcome(found);
+    return reuse ? { ...test, reuse } : test;
+}
 function deduplicateById(items) {
     const seen = new Set();
     const result = [];
@@ -582,7 +611,7 @@ export function registerSubmitReportTool(server) {
         // generation — downstream scoring scripts don't expect them and fail if
         // they encounter these string fields while traversing the object.
         // Also normalize each item's `repository` (blank → undefined).
-        const sanitizedNewTests = dedupedNewTests.map(({ scenarioFile: _sf, traceFile: _tf, frontendTrace: _ft, ...rest }) => normalizeRepository(rest));
+        const sanitizedNewTests = await Promise.all(dedupedNewTests.map(({ scenarioFile: _sf, traceFile: _tf, frontendTrace: _ft, ...rest }) => attachReuseOutcome(normalizeRepository(rest), stateData.reuseOutcomes)));
         const report = {
             businessCaseAnalysis: params.businessCaseAnalysis,
             newTestsCreated: sanitizedNewTests,

package/build/tools/test-management/analyzeChangesTool.d.ts

@@ -16,11 +16,12 @@ export declare const analyzeChangesInputSchema: {
     scope: z.ZodOptional<z.ZodDefault<z.ZodEnum<["full_repo", "branch_diff"]>>>;
     baseBranch: z.ZodOptional<z.ZodString>;
     testDirectory: z.ZodOptional<z.ZodString>;
-    topN: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    topN: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     maxGenerate: z.ZodOptional<z.ZodNumber>;
     prNumber: z.ZodOptional<z.ZodNumber>;
     repository: z.ZodOptional<z.ZodString>;
     testsRepoDir: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    includeUncommitted: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 };
 export declare const NO_UI_INSTRUCTIONS = "No UI changes detected \u2014 no blueprint capture needed.";
 export declare const NO_RESOLVABLE_URLS_INSTRUCTIONS = "Frontend changes detected but no candidate URLs could be resolved (workspace baseUrl missing or no router files matched). UI recommendations will be source-grounded only.";

package/build/tools/test-management/analyzeChangesTool.js

@@ -287,8 +287,8 @@ export const analyzeChangesInputSchema = {
         .describe("Directory containing existing tests (auto-detected if omitted)"),
     topN: z
         .number()
-        .default(MAX_RECOMMENDATIONS)
         .optional()
+        .default(MAX_RECOMMENDATIONS)
         .describe(`Number of ranked test recommendations to generate. Defaults to ${MAX_RECOMMENDATIONS}.`),
     maxGenerate: z
         .number()
@@ -309,6 +309,11 @@ export const analyzeChangesInputSchema = {
         .refine((v) => path.isAbsolute(v), { message: "testsRepoDir must be an absolute path" })
         .optional()
         .describe("Absolute path to a separate test repository clone. When set, existing test discovery scans this directory instead of repositoryPath. Used in cross-repo test delivery mode where tests live in a separate repo."),
+    includeUncommitted: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("When true, diffs the base ref against the working tree (captures uncommitted and unstaged changes). Use for local-dev workflows. Defaults to false (CI mode — committed changes only)."),
 };
 // ── UI blueprint-capture instructions ──
 // Moved here from the former skyramp_ui_analyze_changes pre-flight tool. These
@@ -391,7 +396,7 @@ export function registerAnalyzeChangesTool(server) {
             if (analysisScope === AnalysisScope.CurrentBranchDiff) {
                 await sendProgress(10, 100, "Computing branch diff...");
                 try {
-                    diffData = await computeBranchDiff(params.repositoryPath, params.baseBranch);
+                    diffData = await computeBranchDiff(params.repositoryPath, params.baseBranch, params.includeUncommitted ?? false);
                     logger.info("Branch diff computed", {
                         currentBranch: diffData.currentBranch,
                         baseBranch: diffData.baseBranch,
@@ -489,7 +494,7 @@ export function registerAnalyzeChangesTool(server) {
                 const removalCandidateFiles = selectRemovalCandidateFiles(diffData);
                 const git = simpleGit(params.repositoryPath);
                 const recoveredBaseEndpoints = removalCandidateFiles.length > 0
-                    ? await recoverRemovedEndpointsFromBase(removalCandidateFiles, (file) => git.show([`${diffData.baseBranch}:${file}`]))
+                    ? await recoverRemovedEndpointsFromBase(removalCandidateFiles, (file) => git.show([`${diffData.baseBranch}:${file}`]), params.repositoryPath, diffData.baseBranch)
                     : [];
                 classifiedEndpoints = classifyEndpointsByChangedFiles(diffData, scannedEndpoints, recoveredBaseEndpoints);
                 classifiedEndpoints = {
@@ -1181,6 +1186,56 @@ export function registerAnalyzeChangesTool(server) {
                 affectedServices: classifiedEndpoints.affectedServices,
                 summary: "",
             } : undefined;
+            // ── Route discovery context for LLM grounding and state persistence ──
+            // fullAnalysis lives only in inMemorySessionStore (for MCP resources
+            // and registerRecommendTestsPrompt). The disk state carries only the
+            // slim fields that downstream tools (health, execute, actions) need.
+            // routerMountContext and candidateRouteFiles are computed here so they
+            // can be persisted to the state file for downstream tools (health, drift).
+            // Without them, analyzeTestHealth would work only off the static catalog
+            // which has wrong paths for nested resources and unsupported frameworks.
+            const routeLikeUnmatchedFiles = [];
+            for (const file of classifiedEndpoints?.unmatchedFiles ?? []) {
+                const routeLike = SOURCE_EXTS.test(file) &&
+                    (ROUTE_FILE_PATTERN.test(file) || ROUTE_FILE_BASENAME_PATTERN.test(path.basename(file)));
+                if (routeLike && !(await isGraphQLFile(file, params.repositoryPath))) {
+                    routeLikeUnmatchedFiles.push(file);
+                }
+            }
+            const shouldIncludeCandidateRouteFiles = analysisScope !== AnalysisScope.CurrentBranchDiff ||
+                rawRelatedEndpointCount === 0 ||
+                scannedEndpoints.length === 0 ||
+                routeLikeUnmatchedFiles.length > 0;
+            let candidateRouteFiles;
+            if (shouldIncludeCandidateRouteFiles) {
+                candidateRouteFiles = [];
+                for (const file of findCandidateRouteFiles(params.repositoryPath)) {
+                    if (!(await isGraphQLFile(file, params.repositoryPath))) {
+                        candidateRouteFiles.push(file);
+                    }
+                }
+            }
+            // Write the full diff to a temp file before building state so the path
+            // can be persisted and read by analyzeTestHealthTool for per-line detection.
+            let diffFilePath;
+            if (diffData?.diffContent) {
+                diffFilePath = path.join(os.tmpdir(), `skyramp-diff-${sessionId}.diff`);
+                await fs.promises.writeFile(diffFilePath, diffData.diffContent, { encoding: "utf-8", mode: 0o600 });
+            }
+            const routeDiscovery = {
+                candidateFiles: [
+                    ...(diffData?.changedFiles ?? []),
+                    ...(candidateRouteFiles ?? []),
+                ].filter((file, index, files) => files.indexOf(file) === index),
+                staticHints: scannedEndpoints.map((ep) => ({
+                    path: ep.path,
+                    methods: ep.methods,
+                    sourceFile: ep.sourceFile,
+                })),
+                openApiPaths: specPaths ? [...specPaths] : [],
+                routerMountContext,
+                ...(diffFilePath ? { diffFilePath } : {}),
+            };
             const fullAnalysis = {
                 metadata: {
                     repositoryName: path.basename(params.repositoryPath),
@@ -1237,6 +1292,7 @@ export function registerAnalyzeChangesTool(server) {
                     hasCoverageReports: false,
                     relevantExternalTestPaths,
                 },
+                routeDiscovery,
                 ...(diffContext ? { branchDiffContext: diffContext } : {}),
             };
             // Store RecommendationState in memory so it's compatible with skyramp_recommend_tests if needed
@@ -1246,42 +1302,6 @@ export function registerAnalyzeChangesTool(server) {
                 analysis: fullAnalysis,
             };
             storeSessionData(sessionId, recommendationState);
-            // ── Step 11: Build UnifiedAnalysisState and save ──
-            // fullAnalysis lives only in inMemorySessionStore (for MCP resources
-            // and registerRecommendTestsPrompt). The disk state carries only the
-            // slim fields that downstream tools (health, execute, actions) need.
-            // routerMountContext and candidateRouteFiles are computed here so they
-            // can be persisted to the state file for downstream tools (health, drift).
-            // Without them, analyzeTestHealth would work only off the static catalog
-            // which has wrong paths for nested resources and unsupported frameworks.
-            const routeLikeUnmatchedFiles = [];
-            for (const file of classifiedEndpoints?.unmatchedFiles ?? []) {
-                const routeLike = SOURCE_EXTS.test(file) &&
-                    (ROUTE_FILE_PATTERN.test(file) || ROUTE_FILE_BASENAME_PATTERN.test(path.basename(file)));
-                if (routeLike && !(await isGraphQLFile(file, params.repositoryPath))) {
-                    routeLikeUnmatchedFiles.push(file);
-                }
-            }
-            const shouldIncludeCandidateRouteFiles = analysisScope !== AnalysisScope.CurrentBranchDiff ||
-                rawRelatedEndpointCount === 0 ||
-                scannedEndpoints.length === 0 ||
-                routeLikeUnmatchedFiles.length > 0;
-            let candidateRouteFiles;
-            if (shouldIncludeCandidateRouteFiles) {
-                candidateRouteFiles = [];
-                for (const file of findCandidateRouteFiles(params.repositoryPath)) {
-                    if (!(await isGraphQLFile(file, params.repositoryPath))) {
-                        candidateRouteFiles.push(file);
-                    }
-                }
-            }
-            // Write the full diff to a temp file before building state so the path
-            // can be persisted and read by analyzeTestHealthTool for per-line detection.
-            let diffFilePath;
-            if (diffData?.diffContent) {
-                diffFilePath = path.join(os.tmpdir(), `skyramp-diff-${sessionId}.diff`);
-                await fs.promises.writeFile(diffFilePath, diffData.diffContent, { encoding: "utf-8", mode: 0o600 });
-            }
             // SKYR-3879 Path B: size-capped raw diff text, persisted (not just the
             // file path above) so skyramp_register_test_plan can verify a
             // discriminator's changedCodeAnchor occurs verbatim in the diff without
@@ -1367,7 +1387,7 @@ export function registerAnalyzeChangesTool(server) {
                     source: CandidateSource.SERVER,
                     candidateId: computeCandidateId(scenario),
                 }));
-                const plan = selectPlan(serverCandidates, budgetCtx);
+                const plan = selectPlan(serverCandidates, { ...budgetCtx, diffText });
                 approvedPlan = {
                     planId: crypto.randomUUID(),
                     createdAt: new Date().toISOString(),
@@ -1429,6 +1449,7 @@ export function registerAnalyzeChangesTool(server) {
                     sessionId,
                     routerMountContext,
                     candidateRouteFiles,
+                    routeDiscovery,
                     relevantExternalTestPaths,
                 },
             };
@@ -1526,6 +1547,8 @@ export function registerAnalyzeChangesTool(server) {
                     modifiedEndpointCount: classifiedEndpoints?.changedEndpoints.length ?? 0,
                     removedEndpointCount: classifiedEndpoints?.removedEndpoints.length ?? 0,
                     endpointCount: skeletonEndpoints.reduce((acc, ep) => acc + ep.methods.length, 0),
+                    newEndpoints: (classifiedEndpoints?.newEndpoints ?? []).flatMap((ep) => ep.methods.map((m) => `${m} ${ep.path}`)),
+                    modifiedEndpoints: (classifiedEndpoints?.changedEndpoints ?? []).flatMap((ep) => ep.methods.map((m) => `${m} ${ep.path}`)),
                 },
                 // Surface uiContext inline so the testbot prompt can iterate
                 // candidateUiPages and inspect changedFrontendFiles without

package/build/tools/test-management/analyzeTestHealthTool.d.ts

@@ -1,2 +1,13 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Names of services whose workspace.yml records a runnable external-test suite
+ * (a reader-backed framework — playwright/pytest/jest/vitest/mocha — +
+ * a `runtimeDetails.testSuites` entry with a testRunCommand) — i.e. what skyramp_run_existing_tests can
+ * actually run. Used to scope the confirm gate so it only fires on repos that
+ * went through Test Environment Setup. Checks each service's suites via
+ * `resolveSuites` (rather than calling resolveRunConfig) so every
+ * `runtimeDetails.testSuites` entry is recognized. Returns [] on any read/parse
+ * error so a config problem can never block drift analysis.
+ */
+export declare function runnableTestEnvServices(repositoryPath: string): Promise<string[]>;
 export declare function registerAnalyzeTestHealthTool(server: McpServer): void;

package/build/tools/test-management/analyzeTestHealthTool.js

@@ -5,6 +5,9 @@ import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { buildDriftAnalysisPrompt } from "../../prompts/test-maintenance/drift-analysis-prompt.js";
 import { TestSource } from "../../types/TestAnalysis.js";
 import { toolError } from "../../utils/utils.js";
+import { WorkspaceConfigManager } from "../../workspace/workspace.js";
+import { resolveSuites } from "../../workspace/testSuites.js";
+import { frameworkHasReader } from "../runExistingTestsTool.js";
 const TOOL_NAME = "skyramp_analyze_test_health";
 // UI test frameworks. "playwright-ui" and "cypress-ui" are the browser-interaction
 // variants detected when the file uses the page fixture (not just the request fixture).
@@ -26,6 +29,27 @@ function isUiTest(t) {
     const isUiSnap = UI_SNAPSHOT_EXT.test(t.testFile);
     return UI_COMPONENT_FRAMEWORKS.has(fw) || UI_TEST_EXTENSIONS.test(t.testFile) || isUiSnap;
 }
+/**
+ * Names of services whose workspace.yml records a runnable external-test suite
+ * (a reader-backed framework — playwright/pytest/jest/vitest/mocha — +
+ * a `runtimeDetails.testSuites` entry with a testRunCommand) — i.e. what skyramp_run_existing_tests can
+ * actually run. Used to scope the confirm gate so it only fires on repos that
+ * went through Test Environment Setup. Checks each service's suites via
+ * `resolveSuites` (rather than calling resolveRunConfig) so every
+ * `runtimeDetails.testSuites` entry is recognized. Returns [] on any read/parse
+ * error so a config problem can never block drift analysis.
+ */
+export async function runnableTestEnvServices(repositoryPath) {
+    try {
+        const config = await new WorkspaceConfigManager(repositoryPath).read();
+        return (config.services ?? [])
+            .filter((s) => resolveSuites(s).some((suite) => frameworkHasReader(suite.framework) && !!suite.testRunCommand))
+            .map((s) => s.serviceName);
+    }
+    catch {
+        return [];
+    }
+}
 export function registerAnalyzeTestHealthTool(server) {
     server.registerTool(TOOL_NAME, {
         annotations: {
@@ -75,6 +99,44 @@ export function registerAnalyzeTestHealthTool(server) {
             const skyrampCount = existingTests.filter((t) => t.source !== TestSource.External).length;
             const externalCount = existingTests.length - skyrampCount;
             logger.info(`Loaded ${skyrampCount} Skyramp + ${externalCount} relevant external tests from state file`);
+            // ── External-test confirm gate ────────────────────────────────────
+            // When the diff touches the repo's OWN [external] tests AND the workspace
+            // has a runnable test-env config (runtimeDetails.test*), the drift
+            // assessment must be grounded in a real run of those tests
+            // (skyramp_run_existing_tests mode:confirm), not the agent's guess from
+            // source. Prompt prose alone proved model-fragile — agents read the config
+            // and still skipped the confirm, leaving the repo's own tests at
+            // afterStatus=Unknown — so enforce ordering here: refuse to produce the
+            // drift prompt until a confirm run has been recorded. Loop-safe:
+            // skyramp_run_existing_tests persists an externalTestResults record for
+            // EVERY outcome (pass/fail/skip/unhealthy), so one confirm call clears the
+            // gate. Only a confirm-mode record counts — a verify run (or any future
+            // record type) must not bypass the required confirm pass.
+            // Scoped by runnableTestEnvServices so it never fires on repos without
+            // test-env setup, and fail-open on any config error.
+            const confirmAttempted = (stateData.externalTestResults ?? []).some((r) => r.mode === "confirm");
+            const runnableServices = externalCount > 0 && !confirmAttempted
+                ? await runnableTestEnvServices(repositoryPath)
+                : [];
+            if (runnableServices.length > 0) {
+                const externalFiles = existingTests
+                    .filter((t) => t.source === TestSource.External)
+                    .map((t) => t.testFile);
+                // Cap the enumerated examples — a broad diff can mark dozens of external
+                // tests, and the agent already has the full [external] list from
+                // skyramp_analyze_changes.
+                const shown = externalFiles.slice(0, 8);
+                const filesList = shown.map((f) => `"${f}"`).join(", ") +
+                    (externalFiles.length > shown.length
+                        ? `, …(+${externalFiles.length - shown.length} more)`
+                        : "");
+                // With >1 runnable service the tool needs an explicit `service`.
+                const serviceHint = runnableServices.length > 1
+                    ? ` Multiple runnable test services are configured — pass service: "${runnableServices[0]}".`
+                    : "";
+                return toolError(`This repository has a configured test environment (runtimeDetails.test*) and ${externalCount} external test${externalCount === 1 ? "" : "s"} relevant to this diff, but skyramp_run_existing_tests has not run yet. Run the repo's OWN tests BEFORE assessing drift so the assessment is grounded in real pass/fail (otherwise these tests are left at status Unknown). ` +
+                    `Call skyramp_run_existing_tests with mode: "confirm", stateFile: "${stateManager.getStatePath()}"${args.repository ? `, repository: "${args.repository}"` : ""}, and testSelectors set to the [external] test files skyramp_analyze_changes marked (e.g. ${filesList}).${serviceHint} Then call skyramp_analyze_test_health again.`);
+            }
             // Delete stale diff files only — state files must remain for the caller's skyramp_actions call.
             try {
                 await StateManager.cleanupOldFiles(24, undefined, []);
@@ -120,7 +182,7 @@ export function registerAnalyzeTestHealthTool(server) {
                 const relatedRepoPaths = (await Promise.all(relatedRepoKeys.map(r => stateManager.getRepoRepositoryPath(r)))).filter((p) => typeof p === "string");
                 allRepoPaths = [repositoryPath, ...relatedRepoPaths];
             }
-            const promptText = buildDriftAnalysisPrompt(stateManager.getStatePath(), apiTests.map((t) => ({ testFile: t.testFile, source: t.source })), uiDriftParams, allRepoPaths);
+            const promptText = buildDriftAnalysisPrompt(stateManager.getStatePath(), apiTests.map((t) => ({ testFile: t.testFile, source: t.source })), uiDriftParams, allRepoPaths, stateData?.externalTestResults);
             return {
                 structuredContent: { prompt: promptText },
                 content: [{ type: "text", text: "Drift analysis prompt generated. Follow the prompt field to assess each test." }],

package/build/tools/test-management/registerTestPlanTool.js

@@ -8,7 +8,7 @@ import { toolError } from "../../utils/utils.js";
 import { buildApprovedPlanItem } from "../../utils/planMatchKeys.js";
 import { SCENARIO_CATEGORIES, CATEGORY_PRIORITY, Novelty, PriorityTier } from "../../types/TestRecommendation.js";
 import { HttpMethod, TestType } from "../../types/TestTypes.js";
-import { CandidateSource, computeCandidateId, DiscriminatorKind } from "../../types/Recommendation.js";
+import { CandidateSource, computeCandidateId, scenarioMergeKey, DiscriminatorKind } from "../../types/Recommendation.js";
 import { selectPlan } from "../../recommendation/planRanker.js";
 import { validateDiscriminator } from "../../recommendation/discriminators.js";
 import { isAttackSurfaceSecurityBoundary } from "../../prompts/test-recommendation/recommendationShared.js";
@@ -220,6 +220,39 @@ function renderPlanItem(item, rank) {
     const discriminatorNote = item.verifiedDiscriminator ? `, verified discriminator: ${item.verifiedDiscriminator}` : "";
     return `${rank}. [${item.testType}] "${item.scenarioName}" (${item.category}${discriminatorNote}) — ${describeGenerationCall(item)}`;
 }
+/**
+ * Whether this run generates UI/E2E tests is a deterministic property of the
+ * approved plan, so it is decided here rather than left to the agent to resolve
+ * from prompt prose. The prompt owns HOW to record a UI trace and the runtime
+ * conditions the server cannot know (app unreachable, unintegrated component);
+ * this directive owns WHETHER and HOW MANY.
+ */
+function renderGenerationDirective(plan) {
+    const uiCount = plan.generate.filter((item) => item.testType === TestType.UI || item.testType === TestType.E2E).length;
+    const nonUICount = plan.generate.length - uiCount;
+    const tests = (n) => `${n} test${n === 1 ? "" : "s"}`;
+    if (plan.generate.length === 0) {
+        return [
+            "### Generation directive: GENERATE NOTHING",
+            "Create zero new tests of any type this run and proceed to the report. An empty `newTestsCreated` is the CORRECT " +
+                "result for this PR — there is no new observable surface to cover. Do not record a browser trace and do not invent " +
+                "a spec to have something to report; report your maintenance work and the ADDITIONAL candidates as recommendations instead.",
+        ];
+    }
+    if (uiCount === 0) {
+        return [
+            "### Generation directive: NO UI/E2E GENERATION",
+            `This plan allocates no UI/E2E generation. Generate the ${tests(nonUICount)} listed above and create zero UI tests ` +
+                "— do not record a browser trace and do not add a UI spec to fill `newTestsCreated`.",
+        ];
+    }
+    return [
+        `### Generation directive: UI/E2E GENERATION REQUIRED (${uiCount})`,
+        `This plan allocates ${tests(uiCount)} of type UI/E2E. You MUST attempt to record and generate each one — do not ` +
+            "downgrade them to recommendations while the app is reachable." +
+            (nonUICount > 0 ? ` Generate the ${tests(nonUICount)} of other types as well.` : ""),
+    ];
+}
 function renderPlanText(plan) {
     const lines = [];
     lines.push(`## Approved Test Plan (${plan.planId})`);
@@ -249,6 +282,8 @@ function renderPlanText(plan) {
             lines.push(`- ${demotion.candidateId}: ${demotion.reason}`);
         }
     }
+    lines.push("");
+    lines.push(...renderGenerationDirective(plan));
     return lines.join("\n");
 }
 // ── Tool registration ───────────────────────────────────────────────────────
@@ -285,14 +320,27 @@ export function registerRegisterTestPlanTool(server) {
             const allScenarios = stateData.repositoryAnalysis?.scenarios ?? [];
             const { candidates: agentCandidates, demotions } = buildAgentCandidates(params.candidates ?? [], diffText);
             const serverCandidates = recoverServerCandidates(stateData.approvedPlan, allScenarios);
-            // Merge by candidateId; a pre-seeded server candidate wins over an agent
-            // submission that happens to hash to the same id (identical scenario
-            // content) — source: "server" is preserved per the unified-plan design.
+            // Merge by scenario-name identity, NOT the full content-hashed candidateId:
+            // the server (analyze_changes) and the agent frequently draft their own
+            // independent steps[] for "the same" scenario (identical scenarioName),
+            // which hash to different candidateIds — deduping on the full id let
+            // both survive as apparent duplicates (SKYR-4026). A pre-seeded server
+            // candidate wins over an agent submission for the same scenario name —
+            // source: "server" is preserved per the unified-plan design.
+            //
+            // Uses scenarioMergeKey (untruncated), not scenarioNameSlug — the
+            // latter's 48-char cap is fine for a short candidateId prefix combined
+            // with a content hash, but bare as a Map key it would silently collapse
+            // two distinct long scenario names sharing a common prefix. A missing
+            // scenarioName (schema requires one for agent candidates; only a
+            // malformed server-recovered scenario could lack one) falls back to
+            // the already-unique candidateId rather than a shared literal.
+            const mergeKey = (c) => scenarioMergeKey(c.scenario.scenarioName) || c.candidateId;
             const merged = new Map();
             for (const candidate of agentCandidates)
-                merged.set(candidate.candidateId, candidate);
+                merged.set(mergeKey(candidate), candidate);
             for (const candidate of serverCandidates)
-                merged.set(candidate.candidateId, candidate);
+                merged.set(mergeKey(candidate), candidate);
             const allCandidates = [...merged.values()];
             // An empty union would persist an authoritative plan with an empty
             // GENERATE list, which the generation gate then enforces — bricking
@@ -304,7 +352,7 @@ export function registerRegisterTestPlanTool(server) {
                 return errorResult;
             }
             const budgetContext = resolveBudgetContext(stateData);
-            const result = selectPlan(allCandidates, { ...budgetContext, demotions });
+            const result = selectPlan(allCandidates, { ...budgetContext, demotions, diffText });
             const approvedPlan = {
                 planId: crypto.randomUUID(),
                 createdAt: new Date().toISOString(),

package/build/tools/trace/startTraceCollectionTool.js

@@ -5,7 +5,7 @@ import { SkyrampClient } from "@skyramp/skyramp";
 import openProxyTerminalTracked from "../../utils/proxy-terminal.js";
 import { getEntryPoint } from "../../utils/telemetry.js";
 import { logger } from "../../utils/logger.js";
-import { basePlaywrightSchema, baseSchema, SESSION_STORAGE_FILENAME, } from "../../types/TestTypes.js";
+import { basePlaywrightSchema, baseSchema, RuntimeEnvironment, SESSION_STORAGE_FILENAME, } from "../../types/TestTypes.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { resolveSessionPaths } from "./resolveSessionPaths.js";
 import { setSavedSessionPath } from "./sessionState.js";
@@ -67,8 +67,8 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
             playwrightSaveStoragePath: basePlaywrightSchema.shape.playwrightSaveStoragePath,
             playwrightViewportSize: basePlaywrightSchema.shape.playwrightViewportSize,
             runtime: z
-                .string()
-                .default("docker")
+                .literal(RuntimeEnvironment.DOCKER)
+                .default(RuntimeEnvironment.DOCKER)
                 .describe("Runtime environment for trace collection. Currently only 'docker' is supported and is used as the default."),
             include: z
                 .array(z.string())

package/build/types/ExternalTestExecution.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Neutral result shape for `skyramp_run_existing_tests` — a repo's OWN
+ * (external, user-authored) test suite, run at PR time to CONFIRM which failures
+ * a change actually causes. Framework-agnostic: the Playwright adapter (and
+ * future pytest/jest adapters) all normalize into these types so the
+ * maintenance pipeline and report consume one shape.
+ */
+/** `error` (fixture/collection/timeout) is kept distinct from `fail`
+ *  (assertion) end-to-end — see external-exec plan item 6. */
+export type ExternalTestStatus = "pass" | "fail" | "error" | "skipped";
+export interface ExternalTestResult {
+    /** Human-readable identity, e.g. `<file> › <describe…> › <title>`. */
+    testId: string;
+    /** Spec file the test lives in. */
+    file: string;
+    status: ExternalTestStatus;
+    /** Failure/error text (ANSI-stripped). Present only for fail/error. */
+    message?: string;
+    durationMs: number;
+}
+export interface ExternalRunSummary {
+    /** Tests that produced a real verdict (pass + fail + error); skipped excluded. */
+    ran: number;
+    failed: number;
+    errored: number;
+    skipped: number;
+    /** True when the candidate set was cut by maxTests/timeout — reported honestly. */
+    truncated: boolean;
+}
+/** Structured env-health diagnostics for logging (populated by the framework adapter). */
+export interface ExternalRunDiagnostics {
+    /** All top-level Playwright run-level error messages (ANSI-stripped, first line each). */
+    runLevelErrors: string[];
+    /** A global-setup/teardown (infra) spec reported fail/error — the environment genuinely
+     *  did not come up (distinct from a product-test failure). */
+    infraSpecFailed: boolean;
+    /** A run-level error is the `--max-failures` "stopped early" bail — benign for env-health
+     *  (it means a test failed and the bounded run stopped, NOT that the env is unhealthy). */
+    maxFailuresBail: boolean;
+}
+export interface ParsedExternalRun {
+    results: ExternalTestResult[];
+    summary: ExternalRunSummary;
+    /** False when a wall of red is environmental (setup/collection failure), not a
+     *  PR signal — consumers must NOT treat results as confirmed failures. */
+    environmentHealthy: boolean;
+    healthDetail?: string;
+    /** Structured diagnostics for logging (optional; set by the Playwright adapter). */
+    diagnostics?: ExternalRunDiagnostics;
+    /** True when the run was skipped because the repo has no runnable external suite
+     *  (no Playwright service / no `testRunCommand`) — i.e. no external tests to
+     *  run. Distinct from a green zero-test run: consumers must treat this as "not
+     *  executed", never "passed". */
+    skipped?: boolean;
+    /** Why the run was skipped (present only when `skipped`). */
+    skipReason?: string;
+}
+/** One persisted run of the external suite, appended to
+ *  UnifiedAnalysisState.externalTestResults so drift analysis / the report can
+ *  fold in CONFIRMED failures instead of guesses. */
+export interface ExternalTestRunRecord extends ParsedExternalRun {
+    mode: "confirm" | "verify";
+    /** ISO timestamp when the run completed. */
+    ranAt: string;
+    /** owner/repo this run targeted (multi-repo runs); absent → primary. */
+    repository?: string;
+}

package/build/types/ExternalTestExecution.js

@@ -0,0 +1,8 @@
+/**
+ * Neutral result shape for `skyramp_run_existing_tests` — a repo's OWN
+ * (external, user-authored) test suite, run at PR time to CONFIRM which failures
+ * a change actually causes. Framework-agnostic: the Playwright adapter (and
+ * future pytest/jest adapters) all normalize into these types so the
+ * maintenance pipeline and report consume one shape.
+ */
+export {};

package/build/types/OneClickCommands.d.ts

@@ -4,7 +4,7 @@
  * and executed by the coding assistant following the workflow instructions.
  */
 /** Unique identifier for a one-click command */
-export type OneClickCommandId = "test_given_endpoint_comprehensively" | "full_repo_scan_recommend_generate_and_execute_top_n_tests";
+export type OneClickCommandId = "test_given_endpoint_comprehensively" | "full_repo_scan_recommend_generate_and_execute_top_n_tests" | "local_dev_test_changes";
 /** Metadata for intent recognition by coding assistants */
 export interface CommandIntentMetadata {
     /** Context indicators describing when to use and when NOT to use this workflow */

package/build/types/Recommendation.d.ts

@@ -74,6 +74,26 @@ export interface Budgeter {
     readonly name: string;
     select(ranked: Candidate[], ctx: BudgetContext): SelectionResult;
 }
+/**
+ * Slug of a scenario name alone (no content hash) — stable across independent
+ * drafts of "the same" scenario even when their steps[] differ (e.g. the
+ * server's auto-drafted version vs. the agent's own re-drafted version of a
+ * scenario with an identical name). Used to dedupe by scenario identity where
+ * `computeCandidateId`'s content-sensitive hash would wrongly treat two drafts
+ * of the same named scenario as distinct (SKYR-4026).
+ */
+export declare function scenarioNameSlug(scenarioName: string | undefined): string;
+/**
+ * Merge-dedup identity key for a scenario name — like {@link scenarioNameSlug}
+ * but NOT truncated and with no shared fallback for a missing name. The 48-char
+ * truncation in `scenarioNameSlug` is fine for `computeCandidateId` (combined
+ * with a content hash for uniqueness), but used bare as a Map key it would
+ * silently collapse two distinct scenarios sharing a long common prefix, and
+ * collapse every candidate with no scenarioName onto the same key. Returns ""
+ * for a missing name so the caller can fall back to something already unique
+ * (e.g. candidateId) instead of a shared literal.
+ */
+export declare function scenarioMergeKey(scenarioName: string | undefined): string;
 /**
  * Deterministic candidate id: a slug of the scenario name plus an 8-char content
  * hash. Pure and reproducible — the same scenario always yields the same id, so

package/build/types/Recommendation.js

@@ -17,6 +17,37 @@ export var CandidateSource;
     CandidateSource["AGENT"] = "agent";
     CandidateSource["SERVER"] = "server";
 })(CandidateSource || (CandidateSource = {}));
+/**
+ * Slug of a scenario name alone (no content hash) — stable across independent
+ * drafts of "the same" scenario even when their steps[] differ (e.g. the
+ * server's auto-drafted version vs. the agent's own re-drafted version of a
+ * scenario with an identical name). Used to dedupe by scenario identity where
+ * `computeCandidateId`'s content-sensitive hash would wrongly treat two drafts
+ * of the same named scenario as distinct (SKYR-4026).
+ */
+export function scenarioNameSlug(scenarioName) {
+    return ((scenarioName ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48) || "scenario");
+}
+/**
+ * Merge-dedup identity key for a scenario name — like {@link scenarioNameSlug}
+ * but NOT truncated and with no shared fallback for a missing name. The 48-char
+ * truncation in `scenarioNameSlug` is fine for `computeCandidateId` (combined
+ * with a content hash for uniqueness), but used bare as a Map key it would
+ * silently collapse two distinct scenarios sharing a long common prefix, and
+ * collapse every candidate with no scenarioName onto the same key. Returns ""
+ * for a missing name so the caller can fall back to something already unique
+ * (e.g. candidateId) instead of a shared literal.
+ */
+export function scenarioMergeKey(scenarioName) {
+    return (scenarioName ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
 /**
  * Deterministic candidate id: a slug of the scenario name plus an 8-char content
  * hash. Pure and reproducible — the same scenario always yields the same id, so
@@ -26,12 +57,7 @@ export var CandidateSource;
  * cosmetic re-serialization does not change the id while a real edit does.
  */
 export function computeCandidateId(scenario) {
-    const slugSource = scenario.scenarioName ?? "";
-    const slug = slugSource
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, 48) || "scenario";
+    const slug = scenarioNameSlug(scenario.scenarioName);
     const canonical = {
         scenarioName: scenario.scenarioName ?? "",
         category: scenario.category ?? "",