@skyramp/mcp 0.3.5 → 0.3.6-rc.1

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

@@ -4,6 +4,7 @@ import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { CandidateUiPage } from "../../utils/uiPageEnumerator.js";
 import type { FrontendFileIntegration } from "../../types/FrontendIntegration.js";
 import { TraceFile } from "../../types/RepositoryAnalysis.js";
+import { BranchDiffData } from "../../utils/branchDiff.js";
 import { ScannedEndpoint } from "../../utils/repoScanner.js";
 import { TraceParseResult } from "../../utils/trace-parser.js";
 /** Exported for testing: maps a parsed trace result to a TraceFile. */
@@ -25,7 +26,7 @@ export declare const analyzeChangesInputSchema: {
     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.";
+export declare const NO_RESOLVABLE_URLS_INSTRUCTIONS = "Frontend changes detected but no candidate URLs could be resolved (no route files matched the changed files or their importers, and no frontend baseUrl to fall back to). UI recommendations will be source-grounded only.";
 export declare function buildCaptureInstructions(pages: CandidateUiPage[]): string;
 /**
  * Instruction block for changed frontend files the server determined have no
@@ -45,4 +46,26 @@ export declare function buildAnalyzeChangesResult(parts: {
     outputText: string;
     recommendationPrompt: string;
 }): CallToolResult;
+/**
+ * Coverage is discovered from the working tree, so a test file the PR itself adds looks
+ * identical to pre-existing coverage. This is what the budgeter reads to decide whether
+ * an empty plan is a dedup artifact or the author's own coverage.
+ *
+ * No diff means no answer, so it reports `true` and the reserve stays shut. `diffData` is
+ * absent in full-repo scope — where fullRepoCatalog deliberately drops externally covered
+ * scenarios, and promoting them back would contradict the prompt the agent reads — and
+ * after a branch-diff failure, where nothing is known about the changed files at all.
+ *
+ * Classification comes from discovery, not from `isTestFile`: the flag has to agree with
+ * whatever built the coverage keys it guards.
+ *
+ * `userChangedFiles` is the bot-filtered list. The bot commits its generated tests onto
+ * the branch it analyzed, and those filenames are exactly what the discovery patterns
+ * exist to match — so reading the raw base..HEAD list shut the reserve on every re-run
+ * of a branch: run 1 generates the tests, run 2 sees them. When the filter cannot answer
+ * (no bot commit yet, or a git failure) the raw list stands. That is safe in the same
+ * direction as the `!diffData` case: the raw list can only hold MORE files, so the
+ * fallback shuts the reserve rather than opening it.
+ */
+export declare function computeDiffChangesTestFiles(diffData: BranchDiffData | undefined, userChangedFiles?: string[] | null): boolean;
 export declare function registerAnalyzeChangesTool(server: McpServer): void;

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

@@ -14,13 +14,16 @@ import { StateManager, registerSession, storeSessionData, rememberTestsRepoDir,
 import { buildRecommendationPrompt, computeScoredCandidates } from "../../prompts/test-recommendation/test-recommendation-prompt.js";
 import { hasFlutterSdkDep, isFrontendFile, isTestFile } from "../../prompts/test-recommendation/scopeAssessment.js";
 import { buildExternalCoverageSet } from "../../prompts/test-recommendation/recommendationShared.js";
+import { resolveSubjectEndpoints } from "../../utils/subjectEndpoints.js";
+import { collectChangedRouteLines } from "../../utils/changedRoutes.js";
 import { CandidateSource, computeCandidateId } from "../../types/Recommendation.js";
 import { selectPlan } from "../../recommendation/planRanker.js";
 import { buildApprovedPlanItem } from "../../utils/planMatchKeys.js";
-import { enumerateCandidateUiPages } from "../../utils/uiPageEnumerator.js";
+import { enumerateCandidateUiPages, MAX_CANDIDATE_PAGES } from "../../utils/uiPageEnumerator.js";
 import { checkFrontendFileIntegration } from "../../utils/frontendIntegration.js";
 import { MAX_RECOMMENDATIONS, MAX_TESTS_TO_GENERATE } from "../../prompts/test-recommendation/recommendationSections.js";
 import { TestDiscoveryService } from "../../services/TestDiscoveryService.js";
+import { isDiscoveredTestFile } from "../../utils/testFileClassification.js";
 import { ScenarioSource, AnalysisScope } from "../../types/RepositoryAnalysis.js";
 import { computeBranchDiff } from "../../utils/branchDiff.js";
 import { classifyEndpointsByChangedFiles, selectRemovalCandidateFiles, recoverRemovedEndpointsFromBase, } from "../../utils/routeParsers.js";
@@ -324,23 +327,35 @@ export const analyzeChangesInputSchema = {
 // for UI recommendation reasoning (enforced at submit time by the Blueprint
 // Citation Invariant in the testbot prompt).
 export const NO_UI_INSTRUCTIONS = `No UI changes detected — no blueprint capture needed.`;
-export 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.`;
+export const NO_RESOLVABLE_URLS_INSTRUCTIONS = `Frontend changes detected but no candidate URLs could be resolved (no route files matched the changed files or their importers, and no frontend baseUrl to fall back to). UI recommendations will be source-grounded only.`;
 export function buildCaptureInstructions(pages) {
+    const pathOnly = pages.some((p) => p.baseUrlResolved === false);
     const pagesYaml = pages
-        .map((p, i) => `  ${i + 1}. ${p.url}  (sourcedFrom: ${p.sourcedFrom.join(", ") || "(none)"}, strategy: ${p.strategy})`)
+        .map((p, i) => `  ${i + 1}. ${p.url}  (sourcedFrom: ${p.sourcedFrom.join(", ") || "(none)"}${p.via ? `, via: ${p.via.join(", ")}` : ""}, strategy: ${p.strategy})`)
         .join("\n");
+    const capNote = pages.length >= MAX_CANDIDATE_PAGES
+        ? `\n(The list is capped at ${MAX_CANDIDATE_PAGES} pages — direct route matches first, then the pages that render the most changed files.)`
+        : "";
+    // The server could not resolve a frontend baseUrl (no frontend service with
+    // `api.baseUrl`, no SKYRAMP_TEST_BASE_URL). The paths are still exact; the
+    // agent supplies the host.
+    const baseUrlStep = pathOnly
+        ? `
+**The entries above are URL paths, not full URLs** — the workspace declares no frontend service with \`api.baseUrl\`. Determine the frontend base URL once before capturing — the testbot workflow's \`targetReadyCheckCommand\` or the dev-server port in \`package.json\` scripts usually names it — then prefix every path with it. Log an \`issuesFound\` info entry recommending that \`api.baseUrl\` be set on the frontend service in \`.skyramp/workspace.yml\`.
+`
+        : "";
     return `Frontend changes detected. **Before writing any UI recommendation \`reasoning\`, capture blueprints on the candidate UI pages below.** Those captures stay in your tool-result history and serve as element vocabulary — the recommendation catalog further down gives you the authoring rules; you bring the observed elements.
 
-**Candidate URLs:**
-${pagesYaml}
-
+**Candidate ${pathOnly ? "URL paths" : "URLs"}:**
+${pagesYaml}${capNote}
+${baseUrlStep}
 **For each candidate URL:**
   - \`browser_navigate\` to the URL
   - \`browser_blueprint\` to capture the page
 
 You don't need to thread the blueprints back into a tool call — they're in your context once captured.
 
-If a candidate URL 404s or redirects unexpectedly, navigate from the workspace baseUrl and explore (admin apps mount routes under base prefixes the source extraction can't see). If the page rendered but lacks the changed feature (gated UI: modal, dropdown, accordion), do NOT iterate further during this step — UI recs will fall back to source-grounded prose for those, and the agent's later trace recording (Task 2) will navigate into the gate via capture-act-capture.
+If a candidate URL 404s or redirects unexpectedly, navigate from the frontend base URL and explore (admin apps mount routes under base prefixes the source extraction can't see). If the page rendered but lacks the changed feature (gated UI: modal, dropdown, accordion), do NOT iterate further during this step — UI recs will fall back to source-grounded prose for those, and the agent's later trace recording (Task 2) will navigate into the gate via capture-act-capture.
 
 If \`browser_blueprint\` fails on every candidate URL (app unreachable, all 404s), proceed and log an \`issuesFound\` info entry. Recommendations will be source-grounded; non-UI work is unaffected.`;
 }
@@ -376,6 +391,32 @@ export function buildAnalyzeChangesResult(parts) {
     const executionPlan = `\`\`\`json\n${parts.structuredSummary}\n\`\`\`\n\n## UI Blueprint Capture — do this BEFORE writing UI recommendation reasoning\n${parts.uiInstructions}\n\n${parts.outputText}\n\n---\n\n## Pre-built Test Catalog — Fill in placeholders from source code, then display verbatim\n⚠️ Do NOT reformat, rename sections, or generate a new catalog. Replace \`<…from source>\` values, then show this output exactly as-is, grouped by test type.\n\n${parts.recommendationPrompt}`;
     return dualChannelResult({ executionPlan });
 }
+/**
+ * Coverage is discovered from the working tree, so a test file the PR itself adds looks
+ * identical to pre-existing coverage. This is what the budgeter reads to decide whether
+ * an empty plan is a dedup artifact or the author's own coverage.
+ *
+ * No diff means no answer, so it reports `true` and the reserve stays shut. `diffData` is
+ * absent in full-repo scope — where fullRepoCatalog deliberately drops externally covered
+ * scenarios, and promoting them back would contradict the prompt the agent reads — and
+ * after a branch-diff failure, where nothing is known about the changed files at all.
+ *
+ * Classification comes from discovery, not from `isTestFile`: the flag has to agree with
+ * whatever built the coverage keys it guards.
+ *
+ * `userChangedFiles` is the bot-filtered list. The bot commits its generated tests onto
+ * the branch it analyzed, and those filenames are exactly what the discovery patterns
+ * exist to match — so reading the raw base..HEAD list shut the reserve on every re-run
+ * of a branch: run 1 generates the tests, run 2 sees them. When the filter cannot answer
+ * (no bot commit yet, or a git failure) the raw list stands. That is safe in the same
+ * direction as the `!diffData` case: the raw list can only hold MORE files, so the
+ * fallback shuts the reserve rather than opening it.
+ */
+export function computeDiffChangesTestFiles(diffData, userChangedFiles) {
+    if (!diffData)
+        return true;
+    return (userChangedFiles ?? diffData.changedFiles).some(isDiscoveredTestFile);
+}
 export function registerAnalyzeChangesTool(server) {
     server.registerTool(TOOL_NAME, {
         annotations: {
@@ -1323,19 +1364,21 @@ export function registerAnalyzeChangesTool(server) {
             // same classification without re-deriving it. Absent on backend-only PRs.
             //
             // candidateUiPages is enumerated programmatically via the strategy
-            // ladder in uiPageEnumerator (framework route grep, source-grounded
-            // routes, root fallback). The agent uses these to capture
+            // ladder in uiPageEnumerator (framework route grep + import graph,
+            // source-grounded routes, root fallback). The agent uses these to capture
             // browser_blueprints — see uiInstructions below, which this tool returns
             // so the agent captures element vocabulary for UI rec reasoning.
             const uiContext = await (async () => {
                 // changedFrontendFiles computed above (before discoverTests) — reuse here.
                 if (changedFrontendFiles.length === 0)
                     return undefined;
-                const candidateUiPages = await enumerateCandidateUiPages(params.repositoryPath, changedFrontendFiles);
                 // SKYR-3855: deterministic production-importer check, computed here so
                 // downstream consumers (testbot prompt) can skip UI generation for
                 // unintegrated components on a server fact instead of a mid-run grep.
+                // Computed first: the enumerator resolves changed non-route files to
+                // the pages that import them.
                 const frontendFileIntegration = checkFrontendFileIntegration(params.repositoryPath, changedFrontendFiles);
+                const candidateUiPages = await enumerateCandidateUiPages(params.repositoryPath, changedFrontendFiles, frontendFileIntegration);
                 return {
                     changedFrontendFiles,
                     candidateUiPages,
@@ -1372,13 +1415,29 @@ export function registerAnalyzeChangesTool(server) {
             // computeScoredCandidates is the single source of truth for both.
             const topN = params.topN ?? MAX_RECOMMENDATIONS;
             const scoredResult = computeScoredCandidates(fullAnalysis, analysisScope, topN, params.maxGenerate);
+            // Resolve each scenario's subject endpoints once, here — this is the only
+            // point that has the scenarios, the diff, and runs before BOTH consumers
+            // (selectPlan below, and the two prompt renderers). `scored.scenario` is
+            // the SAME object as the entry in `allDraftedScenarios` (assigned by
+            // reference into businessContext.draftedScenarios, then into
+            // repositoryAnalysis.scenarios below), so this mutation also fills what
+            // gets persisted. Filling later would leave one consumer keying off a
+            // different subject (SKYR-4214).
+            const changedRoutesForSubjects = collectChangedRouteLines(diffText ?? "");
+            for (const scored of scoredResult.scored) {
+                scored.scenario.subjectEndpoints = resolveSubjectEndpoints(scored.scenario, {
+                    changedRoutes: changedRoutesForSubjects,
+                });
+            }
             const externalCoverage = buildExternalCoverageSet(testLocationsByType);
+            const diffChangesTestFiles = computeDiffChangesTestFiles(diffData, await getUserChangedFiles(params.repositoryPath));
             const planBudgetContext = {
                 maxGenerate: scoredResult.maxGen,
                 maxTotal: topN,
                 isUIOnlyPR: scoredResult.isUIOnlyPR,
                 hasFrontendChanges: scoredResult.hasFrontendChanges,
                 externalCoverageKeys: [...externalCoverage],
+                diffChangesTestFiles,
             };
             let approvedPlan;
             if (scoredResult.scored.length > 0) {
@@ -1388,6 +1447,7 @@ export function registerAnalyzeChangesTool(server) {
                     isUIOnlyPR: planBudgetContext.isUIOnlyPR,
                     hasFrontendChanges: planBudgetContext.hasFrontendChanges,
                     externalCoverage,
+                    diffChangesTestFiles,
                 };
                 const serverCandidates = scoredResult.scored.map(({ scenario, priority, novelty }) => ({
                     scenario,
@@ -1403,6 +1463,7 @@ export function registerAnalyzeChangesTool(server) {
                     generate: plan.generate.map(buildApprovedPlanItem),
                     additional: plan.additional.map(buildApprovedPlanItem),
                     demotions: [],
+                    dropped: plan.dropped,
                 };
             }
             const unifiedState = {

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

@@ -175,13 +175,13 @@ export function registerAnalyzeTestHealthTool(server) {
             // every repo in a multi-repo run (endpoints in Repo A, tests in Repo B).
             // TODO(multi-repo): existingTests is scoped to the current repo only — related
             // repo tests are not pre-loaded, discoverable only via the grep instruction.
-            // Skip the async lookups when there are no tests — symbol discovery is a no-op.
-            let allRepoPaths = [repositoryPath];
-            if (existingTests.length > 0) {
-                const relatedRepoKeys = await stateManager.listRelatedRepos();
-                const relatedRepoPaths = (await Promise.all(relatedRepoKeys.map(r => stateManager.getRepoRepositoryPath(r)))).filter((p) => typeof p === "string");
-                allRepoPaths = [repositoryPath, ...relatedRepoPaths];
-            }
+            // Every root in the RUN, not the requested repo plus the related ones: on a
+            // related-repo call the latter omits the primary and repeats the requested
+            // repo (SKYR-4246). Dedupe by root because a legacy untagged primary can also
+            // appear as a related section holding the same path.
+            const allRepoPaths = [
+                ...new Set((await stateManager.listRepoCheckouts()).map(c => c.root)),
+            ];
             const promptText = buildDriftAnalysisPrompt(stateManager.getStatePath(), apiTests.map((t) => ({ testFile: t.testFile, source: t.source })), uiDriftParams, allRepoPaths, stateData?.externalTestResults);
             return {
                 structuredContent: { prompt: promptText },

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

@@ -1,2 +1,205 @@
+import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { HttpMethod, TestType } from "../../types/TestTypes.js";
+import { Candidate, DiscriminatorKind } from "../../types/Recommendation.js";
+import { ChangedRoute } from "../../utils/changedRoutes.js";
+declare const registerCandidateSchema: z.ZodObject<{
+    scenarioName: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodEnum<["new_endpoint", "bug_caught", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>;
+    priority: z.ZodEnum<["high", "medium", "low"]>;
+    testType: z.ZodEffects<z.ZodNativeEnum<typeof TestType>, TestType, TestType>;
+    steps: z.ZodArray<z.ZodObject<{
+        order: z.ZodNumber;
+        method: z.ZodNativeEnum<typeof HttpMethod>;
+        path: z.ZodString;
+        description: z.ZodString;
+        interactionType: z.ZodEnum<["success", "error", "edge-case"]>;
+        requestBody: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        queryParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        responseBody: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodAny>, z.ZodArray<z.ZodAny, "many">]>>;
+        expectedStatusCode: z.ZodNumber;
+        expectedResponseFields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        bodyMustInclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        chainsFrom: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+            sourceStep: z.ZodNumber;
+            sourceField: z.ZodString;
+            sourceLocation: z.ZodEnum<["body", "header", "cookie"]>;
+            targetParam: z.ZodString;
+            targetLocation: z.ZodEnum<["path", "body", "query", "header", "cookie"]>;
+        }, "strip", z.ZodTypeAny, {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }, {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }>, z.ZodArray<z.ZodObject<{
+            sourceStep: z.ZodNumber;
+            sourceField: z.ZodString;
+            sourceLocation: z.ZodEnum<["body", "header", "cookie"]>;
+            targetParam: z.ZodString;
+            targetLocation: z.ZodEnum<["path", "body", "query", "header", "cookie"]>;
+        }, "strip", z.ZodTypeAny, {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }, {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }>, "many">]>>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        method: HttpMethod;
+        description: string;
+        order: number;
+        interactionType: "error" | "success" | "edge-case";
+        expectedStatusCode: number;
+        queryParams?: Record<string, any> | undefined;
+        requestBody?: Record<string, any> | undefined;
+        responseBody?: any[] | Record<string, any> | undefined;
+        expectedResponseFields?: string[] | undefined;
+        chainsFrom?: {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        } | {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }[] | undefined;
+        bodyMustInclude?: string[] | undefined;
+    }, {
+        path: string;
+        method: HttpMethod;
+        description: string;
+        order: number;
+        interactionType: "error" | "success" | "edge-case";
+        expectedStatusCode: number;
+        queryParams?: Record<string, any> | undefined;
+        requestBody?: Record<string, any> | undefined;
+        responseBody?: any[] | Record<string, any> | undefined;
+        expectedResponseFields?: string[] | undefined;
+        chainsFrom?: {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        } | {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }[] | undefined;
+        bodyMustInclude?: string[] | undefined;
+    }>, "many">;
+    discriminator: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodNativeEnum<typeof DiscriminatorKind>;
+        changedCodeAnchor: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: DiscriminatorKind;
+        changedCodeAnchor: string;
+    }, {
+        kind: DiscriminatorKind;
+        changedCodeAnchor: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    priority: "high" | "medium" | "low";
+    testType: TestType;
+    scenarioName: string;
+    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    steps: {
+        path: string;
+        method: HttpMethod;
+        description: string;
+        order: number;
+        interactionType: "error" | "success" | "edge-case";
+        expectedStatusCode: number;
+        queryParams?: Record<string, any> | undefined;
+        requestBody?: Record<string, any> | undefined;
+        responseBody?: any[] | Record<string, any> | undefined;
+        expectedResponseFields?: string[] | undefined;
+        chainsFrom?: {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        } | {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }[] | undefined;
+        bodyMustInclude?: string[] | undefined;
+    }[];
+    discriminator?: {
+        kind: DiscriminatorKind;
+        changedCodeAnchor: string;
+    } | undefined;
+}, {
+    description: string;
+    priority: "high" | "medium" | "low";
+    testType: TestType;
+    scenarioName: string;
+    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    steps: {
+        path: string;
+        method: HttpMethod;
+        description: string;
+        order: number;
+        interactionType: "error" | "success" | "edge-case";
+        expectedStatusCode: number;
+        queryParams?: Record<string, any> | undefined;
+        requestBody?: Record<string, any> | undefined;
+        responseBody?: any[] | Record<string, any> | undefined;
+        expectedResponseFields?: string[] | undefined;
+        chainsFrom?: {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        } | {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }[] | undefined;
+        bodyMustInclude?: string[] | undefined;
+    }[];
+    discriminator?: {
+        kind: DiscriminatorKind;
+        changedCodeAnchor: string;
+    } | undefined;
+}>;
+type RegisterCandidateInput = z.infer<typeof registerCandidateSchema>;
+/** Build the agent-submitted candidates. Discriminator claims are verified
+ *  later, by {@link applyDiscriminatorClaims}, once the merge has settled which
+ *  scenario each name resolves to. Exported for the direct unit test in
+ *  registerTestPlanTool.test.ts — a candidate that does not survive selection
+ *  never reaches the persisted plan, so its subjectEndpoints fill is not
+ *  observable through the tool's output, and testing here avoids coupling the
+ *  fill to what selection happens to keep. */
+export declare function buildAgentCandidates(candidates: RegisterCandidateInput[], changedRoutes: ChangedRoute[]): Candidate[];
 export declare function registerRegisterTestPlanTool(server: McpServer): void;
+export {};

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

@@ -10,6 +10,8 @@ import { SCENARIO_CATEGORIES, CATEGORY_PRIORITY, Novelty, PriorityTier } from ".
 import { HttpMethod, TestType } from "../../types/TestTypes.js";
 import { CandidateSource, computeCandidateId, scenarioMergeKey, DiscriminatorKind } from "../../types/Recommendation.js";
 import { selectPlan } from "../../recommendation/planRanker.js";
+import { resolveSubjectEndpoints } from "../../utils/subjectEndpoints.js";
+import { collectChangedRouteLines } from "../../utils/changedRoutes.js";
 import { reservedUISlots } from "../../recommendation/budgeters/shared.js";
 import { inferScenarioType } from "../../recommendation/diversity.js";
 import { validateDiscriminator } from "../../recommendation/discriminators.js";
@@ -49,7 +51,10 @@ const registerStepSchema = z.object({
         .record(z.any())
         .optional()
         .describe("Query parameters with concrete values. Also scanned for boundary_equality and negative_match verification."),
-    responseBody: z.record(z.any()).optional().describe("Expected response body shape/values, when asserted."),
+    responseBody: z
+        .union([z.record(z.any()), z.array(z.any())])
+        .optional()
+        .describe("Expected response body shape/values, when asserted. An array for a collection/list endpoint that returns a JSON array."),
     expectedStatusCode: z.number().int().describe("HTTP status code this step asserts (e.g. 201, 400, 404)."),
     expectedResponseFields: z
         .array(z.string())
@@ -119,8 +124,8 @@ function toScenarioStep(step) {
         chainsFrom: step.chainsFrom,
     };
 }
-function toDraftedScenario(input) {
-    return {
+function toDraftedScenario(input, changedRoutes) {
+    const scenario = {
         scenarioName: input.scenarioName,
         description: input.description,
         category: input.category,
@@ -131,13 +136,20 @@ function toDraftedScenario(input) {
         estimatedComplexity: "moderate",
         testType: input.testType,
     };
+    // Resolved here, at the one boundary that has both the steps and the diff, so
+    // every later dedup stage reads one recorded value (SKYR-4214).
+    return { ...scenario, subjectEndpoints: resolveSubjectEndpoints(scenario, { changedRoutes }) };
 }
 /** Build the agent-submitted candidates. Discriminator claims are verified
  *  later, by {@link applyDiscriminatorClaims}, once the merge has settled which
- *  scenario each name resolves to. */
-function buildAgentCandidates(candidates) {
+ *  scenario each name resolves to. Exported for the direct unit test in
+ *  registerTestPlanTool.test.ts — a candidate that does not survive selection
+ *  never reaches the persisted plan, so its subjectEndpoints fill is not
+ *  observable through the tool's output, and testing here avoids coupling the
+ *  fill to what selection happens to keep. */
+export function buildAgentCandidates(candidates, changedRoutes) {
     return candidates.map((input) => {
-        const scenario = toDraftedScenario(input);
+        const scenario = toDraftedScenario(input, changedRoutes);
         return {
             scenario,
             priority: derivePriorityTier(scenario),
@@ -230,6 +242,13 @@ function resolveBudgetContext(stateData, fullState) {
         isUIOnlyPR: pbc?.isUIOnlyPR ?? false,
         hasFrontendChanges: pbc?.hasFrontendChanges ?? false,
         externalCoverage: new Set(pbc?.externalCoverageKeys ?? []),
+        // `true` for the same reason `computeDiffChangesTestFiles` answers `true` with
+        // no diff: an unknown must shut the reserve, not open it. State written by an
+        // older MCP build carries no such field, and if that PR did add its own tests
+        // the reserve would recommend duplicates of them — the failure this flag
+        // exists to stop, reached by version skew alone. It is also the pre-reserve
+        // behaviour: covered candidates were dropped.
+        diffChangesTestFiles: pbc?.diffChangesTestFiles ?? true,
     };
     const relatedSections = Object.values(fullState?.relatedRepos ?? {}).map((section) => section.data);
     if (relatedSections.length === 0)
@@ -260,6 +279,12 @@ function resolveBudgetContext(stateData, fullState) {
         isUIOnlyPR: hasFrontendChanges && !hasApiChanges,
         hasFrontendChanges,
         externalCoverage,
+        // Unioned across sections like the flags above: a pull request that adds
+        // its own tests in ANY repo of the run must shut the reserve, or that repo's
+        // own coverage becomes grounds to recommend duplicates of it. A section with
+        // no budget context is an unknown, and an unknown shuts the reserve — the
+        // same direction `computeDiffChangesTestFiles` takes with no diff.
+        diffChangesTestFiles: sections.some((s) => s?.planBudgetContext?.diffChangesTestFiles ?? true),
     };
 }
 function describeGenerationCall(item) {
@@ -315,7 +340,7 @@ function renderGenerationDirective(plan) {
             (nonUICount > 0 ? ` Generate the ${tests(nonUICount)} of other types as well.` : ""),
     ];
 }
-function renderPlanText(plan) {
+function renderPlanText(plan, dropped) {
     const lines = [];
     lines.push(`## Approved Test Plan (${plan.planId})`);
     lines.push("");
@@ -338,10 +363,41 @@ function renderPlanText(plan) {
         plan.additional.forEach((item, i) => lines.push(renderPlanItem(item, plan.generate.length + i + 1)));
     }
     if (plan.demotions.length > 0) {
+        // A demotion (failed discriminator claim) and a drop (removed by the
+        // budgeter for an unrelated reason — coverage or budget) are independent:
+        // a candidate can suffer both. Split so the report never claims a
+        // dropped candidate is "still registered".
+        const dropReasonByCandidateId = new Map(dropped.map((d) => [d.candidateId, d.reason]));
+        const registeredDemotions = plan.demotions.filter((d) => !dropReasonByCandidateId.has(d.candidateId));
+        const removedDemotions = plan.demotions.filter((d) => dropReasonByCandidateId.has(d.candidateId));
+        if (registeredDemotions.length > 0) {
+            lines.push("");
+            lines.push(`### Demotions (${registeredDemotions.length}) — discriminator claims that did NOT verify (candidate still registered, claim dropped)`);
+            for (const demotion of registeredDemotions) {
+                lines.push(`- ${demotion.candidateId}: ${demotion.reason}`);
+            }
+        }
+        if (removedDemotions.length > 0) {
+            lines.push("");
+            lines.push(`### Demoted AND removed (${removedDemotions.length}) — the claim failed to verify AND the candidate left the plan. It is NOT registered.`);
+            for (const demotion of removedDemotions) {
+                lines.push(`- ${demotion.candidateId}: claim failed — ${demotion.reason}; removed — ${dropReasonByCandidateId.get(demotion.candidateId)}`);
+            }
+        }
+    }
+    // Every other removal — budget or coverage, with no failed claim attached.
+    // This section is independent of `demotions`: the two channels are unrelated,
+    // and the motivating case has drops and NO demotions. Nesting it inside the
+    // demotion block returned empty GENERATE/ADDITIONAL lists with no candidate id
+    // and no reason, which is the state item 5 exists to make visible. Measured on
+    // eval run 32586610615, fixture repo15-P14: 10 drops, 0 demotions.
+    const demotedIds = new Set(plan.demotions.map((d) => d.candidateId));
+    const removedWithoutDemotion = dropped.filter((d) => !demotedIds.has(d.candidateId));
+    if (removedWithoutDemotion.length > 0) {
         lines.push("");
-        lines.push(`### Demotions (${plan.demotions.length}) — discriminator claims that did NOT verify (candidate still registered, claim dropped)`);
-        for (const demotion of plan.demotions) {
-            lines.push(`- ${demotion.candidateId}: ${demotion.reason}`);
+        lines.push(`### Removed (${removedWithoutDemotion.length}) — candidates the selection stage dropped. They are NOT registered.`);
+        for (const drop of removedWithoutDemotion) {
+            lines.push(`- ${drop.candidateId}: ${drop.reason}`);
         }
     }
     lines.push("");
@@ -409,7 +465,8 @@ export function registerRegisterTestPlanTool(server) {
                 ...(fullState?.repositoryAnalysis?.scenarios ?? []),
                 ...Object.values(fullState?.relatedRepos ?? {}).flatMap((section) => section.data?.repositoryAnalysis?.scenarios ?? []),
             ];
-            const agentCandidates = buildAgentCandidates(params.candidates ?? []);
+            const changedRoutes = collectChangedRouteLines(diffText);
+            const agentCandidates = buildAgentCandidates(params.candidates ?? [], changedRoutes);
             // The approved plan is run-wide and persists at the ROOT (see the
             // persist step below), so prior-plan recovery reads the root first;
             // the section fallback covers state written by older builds.
@@ -501,6 +558,7 @@ export function registerRegisterTestPlanTool(server) {
                 generate: result.generate.map(buildApprovedPlanItem),
                 additional: result.additional.map(buildApprovedPlanItem),
                 demotions: result.demotions,
+                dropped: result.dropped,
             };
             // The approved plan is the ONE run-wide authority (the prompt mandates
             // a single pooled registration on multi-repo runs), so it persists at
@@ -518,7 +576,7 @@ export function registerRegisterTestPlanTool(server) {
                 return errorResult;
             }
             return {
-                content: [{ type: "text", text: renderPlanText(approvedPlan) }],
+                content: [{ type: "text", text: renderPlanText(approvedPlan, result.dropped) }],
             };
         }
         catch (error) {