@skyramp/mcp 0.3.4 → 0.3.6-rc.1

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

@@ -2,11 +2,12 @@ import { z } from "zod";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { MAX_TESTS_TO_GENERATE, MAX_RECOMMENDATIONS, MAX_CRITICAL_TESTS, PATH_PARAM_UUID_GUIDANCE, AUTH_CONFLICT_ERROR_MSG, } from "../test-recommendation/recommendationSections.js";
-import { TASK_ANALYZE_MAINTAIN, TASK_GENERATE, TASK_SUBMIT, taskRef } from "../test-recommendation/recommendationShared.js";
+import { setReportLanguage } from "../../utils/reportLanguage.js";
+import { TASK_ANALYZE_MAINTAIN, TASK_GENERATE, TASK_SUBMIT, taskRef, } from "../test-recommendation/recommendationShared.js";
 import { getTraceRecordingPromptText } from "../../playwright/traceRecordingPrompt.js";
-import { isContractConsumerModeEnabled, isPomReuseEnabled } from "../../utils/featureFlags.js";
+import { isContractConsumerModeEnabled, isPomReuseEnabled, isUtilsReuseEnabled, } from "../../utils/featureFlags.js";
 import { resolveServiceDetailsRef } from "../../utils/utils.js";
-import { buildServiceContext, readWorkspaceServices, } from "../prompt-utils.js";
+import { buildServiceContext, readWorkspaceServices } from "../prompt-utils.js";
 // Cached at module-load — flags are process-wide and cannot change per call.
 const CONSUMER_MODE_ENABLED = isContractConsumerModeEnabled();
 const SERVICE_REFS = resolveServiceDetailsRef();
@@ -19,13 +20,46 @@ const CONTRACT_MODE_GUIDANCE = CONSUMER_MODE_ENABLED
   Both modes (\`providerMode: true, consumerMode: true\`): For diff that contains BOTH provider signals (such as new/modified endpoint handlers, route changes this service owns) AND consumer signals (outbound HTTP client calls to another service, no new endpoint handlers).`
     : `  Always add \`providerMode: true\` — the tool generates provider-side contract tests only.`;
 const POM_REUSE_ENABLED = isPomReuseEnabled();
+// Utils reuse (SkyrampUtils consolidation for integration tests, and for UI tests
+// while the POM path is off) is customer-gated,
+// default OFF — like the POM flag, its value is baked into the prompt at module load,
+// so the MCP server must be restarted after flipping it.
+const UTILS_REUSE_ENABLED = isUtilsReuseEnabled();
+// The UI flow seeds a shared utils file (modularize-first) only with utils reuse
+// on and the POM path off — the same condition isModularizeFirstTarget applies
+// server-side. Every UI-chain statement in this prompt keys on this constant so
+// no line can ban the modularization call the generation result instructs.
+const UI_UTILS_REUSE = UTILS_REUSE_ENABLED && !POM_REUSE_ENABLED;
+// Step 4 of the post-generation list. On the modularize-first UI flow the
+// enhance call is the first sub-step of the generation result's chain — but
+// that chain exists only for a TS/JS UI generation with enhanceAssertions on,
+// which this prompt cannot see per call. So the step keeps the call and lets
+// the agent skip it only when it already made it for that file.
+const UI_ENHANCE_STEP = UI_UTILS_REUSE
+    ? `Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated UI test file, \`testType: "ui"\`, and \`enhanceType: "generation"\`, and apply every instruction returned to that file — UNLESS you already called it for this file as the first sub-step of step 3's chain, in which case skip it (never enhance the same file twice; never leave a generated UI test un-enhanced). The guidance below on which assertions to add applies to whichever call enhances the file.`
+    : `Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated UI test file, \`testType: "ui"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.`;
 // Post-generation code-reuse step for UI tests. The POM catalog, the `verify: true`
 // loop and the `.raw.bak` restore only exist on the POM-aware path — when that path
 // is flagged off, `skyramp_reuse_code` returns the SkyrampUtils workflow instead, so
 // the agent must not be sent looking for artifacts nothing produces.
 const UI_CODE_REUSE_STEP = POM_REUSE_ENABLED
     ? `3. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result directs you to call \`skyramp_reuse_code\` — do this BEFORE \`skyramp_enhance_assertions\`. Two outcomes: (1) a response starting "No reusable POM layer detected" — this is a normal outcome, continue immediately (do NOT retry); (2) a refactoring workflow — follow it to completion INCLUDING its verification loop (\`skyramp_reuse_code\` with \`verify: true\`), finish only when it reports PASSED. If a reused test later fails execution and the failure points at a substituted POM call, restore the saved \`<testFile>.raw.bak\` over the test file and re-run — do NOT hand-edit the customer's POM methods (this re-run counts toward the 2-attempt execution cap — prefer this restore over the generic timeout fix-up when the failing locator came from a POM substitution). **Cleanup before reporting:** \`.raw.bak\` files are internal scratch — after ALL test executions are complete (pass or fail) and before calling \`skyramp_submit_report\`, delete every \`*.raw.bak\` you created so they are not committed to the customer-facing branch. The \`skyramp-pom-catalog.md\` is NOT scratch — leave it in place (later runs reuse it).`
-    : `3. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result directs you to call \`skyramp_reuse_code\` — do this BEFORE \`skyramp_enhance_assertions\`. Follow the returned steps exactly. If it finds no existing helper functions to reuse, that is a normal outcome — leave the test file unchanged and continue immediately (do NOT retry).`;
+    : UI_UTILS_REUSE
+        ? `3. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result carries three CRITICAL NEXT STEPS — \`skyramp_enhance_assertions\` (on the freshly generated file, while its selectors are still inline), then \`skyramp_modularization\`, then \`skyramp_reuse_code\` — with the exact arguments for each. Do all three, in that order and to completion, for EVERY generated UI test file — the enhance sub-step is that file's step 4 below (do not call \`skyramp_enhance_assertions\` a second time for the same file, and do not skip it for later files). Sibling tests offering nothing to reuse is a normal outcome, but the reuse steps still move this test's own helpers into the shared utils file and import them back, so the test file IS expected to change. Then continue (do NOT retry).`
+        : `3. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result directs you to call \`skyramp_reuse_code\` — do this BEFORE \`skyramp_enhance_assertions\`. Follow the returned steps exactly. If it finds no existing helper functions to reuse, that is a normal outcome — leave the test file unchanged and continue immediately (do NOT retry).`;
+// Generation-call clause for the integration pipeline: only ask for codeReuse when
+// utils reuse is enabled — with the flag off, integration generation behaves exactly
+// as it did before the feature existed (no file-rewriting post-steps).
+const INTEGRATION_CODE_REUSE_GEN_CLAUSE = UTILS_REUSE_ENABLED
+    ? `, setting \`modularizeCode: false\` and \`codeReuse: true\` (TypeScript/JavaScript/Python — leave \`codeReuse\` unset for Java: cross-file helpers do not compile in the test executor)`
+    : ``;
+// The post-generation modularize → reuse steps are NOT listed here: the
+// generation tool's own result emits them (see TestGenerationService) when called
+// with codeReuse: true on a modularize-first flow (routing: isModularizeFirstTarget).
+// The UI clauses below keep `modularizeCode: false` deliberately: the
+// modularization happens via that hand-off, not the flag, so the instructions
+// exist only on runs that actually generated that test type. This prompt's job
+// is only the generation-call clauses that ask for codeReuse.
 /**
  * Parse the JSON-encoded `relatedRepositories` argument passed via the testbot
  * prompt/resource. Returns undefined for missing/blank input or malformed JSON so the
@@ -77,9 +111,18 @@ export function getTestbotPrompt(opts) {
     // SKYR-4023: user-facing report language. English display names improve
     // instruction-following vs bare codes; Intl.DisplayNames (Node >=18) names any
     // code correctly, falling back to the raw code only if it can't be resolved.
-    let reportLanguageBlock = '';
-    if (language && language !== 'en') {
-        const reportLanguageName = new Intl.DisplayNames(['en'], { type: 'language' }).of(language) ?? language;
+    // SKYR-4185: rendering the prompt is the single capture point for the
+    // report language — the prompt registration AND the testbot resource both
+    // come through here, so skyramp_submit_report's language guardrail sees it
+    // regardless of which surface served the prompt (no dual wiring to forget).
+    // Set on EVERY render, not just non-English ones: last render wins, so an
+    // en/argless render disarms a language captured earlier in a long-lived
+    // server process instead of falsely rejecting an English report.
+    setReportLanguage(language && language !== "en" ? language : undefined);
+    let reportLanguageBlock = "";
+    if (language && language !== "en") {
+        const reportLanguageName = new Intl.DisplayNames(["en"], { type: "language" }).of(language) ??
+            language;
         reportLanguageBlock = `**Report language: ${reportLanguageName}.** Write ALL user-facing free-text report fields in ${reportLanguageName}: \`businessCaseAnalysis\`, every \`description\` and \`reasoning\`, \`testResults[].details\`, \`issuesFound[].description\`, \`nextSteps[]\`, test-maintenance \`beforeDetails\`/\`afterDetails\`, and \`commitMessage\`. Do NOT translate: code identifiers, endpoint paths, file names, test IDs, \`scenarioName\`, enum values (\`Pass\`/\`Fail\`/\`Skipped\`, severity values, \`testType\`), or anything inside backticks.
 
 `;
@@ -134,7 +177,8 @@ Use those recommendations as your baseline. Only add or remove tests that the us
 
    **If \`skyramp_analyze_changes\` returns an error:** retry once only if the error is transient (timeout, network blip, temporary unavailability) — do NOT retry for permanent errors (invalid repository path, missing required parameter, authentication failure). If it fails again, call \`skyramp_submit_report\` with a minimal valid payload: leave all test arrays empty and add the error to \`issuesFound\`. Refer to the \`skyramp_submit_report\` schema for required fields. Do NOT attempt Task 2 without a valid stateFile.
    **If all changed files are non-application** (CI/CD, docs, lock files, config) → skip to Task 3 (Submit Report) with empty arrays. Put the one-paragraph summary in \`businessCaseAnalysis\` (always populated; that's where end-state narration belongs); leave \`issuesFound\` empty — a non-application diff is not an issue. Example narration for a Testbot onboarding PR (\`.github/workflows/skyramp-testbot.yml\` and/or files under \`.skyramp/\`): "This PR adds Skyramp Testbot GitHub Actions workflow configuration to enable automated test generation on every pull request. It also adds System Under Test (SUT) setup files under \`.skyramp/sut/\` required for the testbot workflow, to bring up services for testing. It contains no application code changes and has no testable behavioral surface."
-${hasRelatedRepos ? `
+${hasRelatedRepos
+            ? `
    **MULTI-REPO CONTEXT (MANDATORY).** This run includes ${relatedRepositories.length} related ${relatedRepositories.length === 1 ? "repository" : "repositories"} listed in the \`<related_repositories>\` block below, each with an explicit \`repository\` (\`owner/repo\`), \`path\`, and \`base_branch\`. Use the \`repository\` value verbatim — do NOT infer it from git remotes or paths. You MUST analyze EACH related repository — exactly one \`skyramp_analyze_changes\` call per listed repo (${relatedRepositories.length} ${relatedRepositories.length === 1 ? "call" : "calls"}), in addition to the primary call in step 2.
 
    **Run the primary call (step 2) FIRST, then the related repos in listed order — not in parallel.** All calls in this run automatically share ONE run-scoped state file — you do NOT pass a state-file path; setting \`repository\` is enough. The primary writes its root section; each related repo's call upserts its own section into that same file. Concurrent calls would race on the shared file, so they must be sequential. For each related repo:
@@ -153,7 +197,8 @@ ${hasRelatedRepos ? `
    Within a type, higher score wins regardless of which repo it came from. Everything not selected becomes an ADDITIONAL recommendation. This guarantees a frontend-only primary repo cannot starve a related backend repo's contract/integration tests of GENERATE slots (and vice versa). When you generate a test for a related repo's endpoint:
    - **Execute it only if that repo's service is already running and reachable.** The workflow's setup may have started multiple services; before generating an API test for a related repo, confirm its \`base_url\` (from that repo's workspace/Execution Plan) responds. If the service is unreachable, still GENERATE the test but mark its \`testResults\` status as \`Skipped\` with details "service not running in this run" — do NOT count an unreachable service as a failure.
    - **Write the test file into that service's own \`testDirectory\`** — the one declared for the service in the unified workspace.yml (the related repo's services were registered there in step 1(a), each with its \`repository\`). The \`testDirectory\` is interpreted relative to the **single delivery root** (the configured test repo if set, otherwise the primary repo), so all generated tests are delivered together by the existing single-target delivery. Do NOT invent a per-source-repo subdirectory, and do NOT write into the related repo's own checkout — it is read-only context. (If two repos happen to declare the same \`testDirectory\`, their files coexist there; the \`repository\` field on each report item — below — is what attributes ownership, not the path.)
-   - **Set the \`repository\` field** (\`owner/repo\`) on every such \`newTestsCreated\` / \`testResults\` item so the report attributes it to the originating repo (see Report Guidelines).` : ""}
+   - **Set the \`repository\` field** (\`owner/repo\`) on every such \`newTestsCreated\` / \`testResults\` item so the report attributes it to the originating repo (see Report Guidelines).`
+            : ""}
 
 2. **Maintain existing tests:**
 
@@ -169,7 +214,7 @@ ${maintenanceBeforeExecStep}
 
    f. Verify external-test fixes. **This step is not optional and it is the easiest one to forget — you have just edited files in step 2(e), so come back here before you move on to anything else.** It applies whenever step 2(a) reported a real pass/fail result for a file you then edited. It does NOT apply when step 2(a) returned \`skipped: true\` or \`ran: 0\` for every suite — there is no baseline to compare against, so say so in your report instead of re-running. When it applies: re-run those \`[external]\` files with \`skyramp_run_existing_tests\` (\`mode: "verify"\`, \`stateFile\`) and record each file's result as its \`afterStatus\`. Editing an \`[external]\` file that step 2(a) confirmed failing and NOT re-running it leaves your own fix unverified — you would be reporting a repair you never saw work. A still-failing verify is surfaced in the report — do not loop.
 
-3. **Code review:** From the \`skyramp_analyze_changes\` output and the existing test files you read for maintenance, note any logic bugs. Do NOT read additional source files just for code review — use what is already available from the analysis and test file reads. Common patterns to flag:
+3. **Code review:** Find the logic bugs in the code that this change touches. Read the implementation of each changed endpoint: the route handler, and the functions that it calls to read or write data. For a changed screen, read the component and the functions that it calls. Read these files even when the diff does not contain them — a defect often sits in the code that the change depends on. Report each finding in \`issuesFound\` with a severity, and say which file and line holds it. Common patterns to flag:
    - Computed fields not recalculated after mutation (e.g. \`total_amount\` unchanged after items are added/removed)
    - Incomplete CRUD: create without cleanup, update that adds new records without removing old ones
    - Missing input validation on new endpoints
@@ -186,8 +231,6 @@ ${maintenanceBeforeExecStep}
        "role": "button",
        "accessibleName": "Save changes",
        "testId": "save-changes-btn",
-       "stableId": null,
-       "contextText": null,
        "mutability": "mutable",
        "widgetType": "native"
      }
@@ -195,10 +238,10 @@ ${maintenanceBeforeExecStep}
    \`\`\`
    - **One element when the test has a single dominant target** (a click, a type, a single visibility check). Most tests fall here — use a length-1 array.
    - **Multiple elements when the test verifies several elements together** — render-state tests (heading + input + button on a form), workflow tests (click button A, assert state appears in element B), or form-fill tests (multiple inputs + submit button). Each element is its own array entry.
-   - Each element's fields are lifted verbatim from a captured blueprint element. \`role\`, \`accessibleName\` are required. \`testId\`/\`stableId\`/\`contextText\` are \`null\` when not present in the capture.
+   - Each element's fields come from a captured blueprint element. Copy the values that are present, and never invent one. \`role\` and \`accessibleName\` are always in the capture; the capture omits \`testId\`/\`stableId\`/\`contextText\` when the element has no such value, so omit them too.
    - \`mutability\` — copy from \`blueprint.element.mutability\`. \`'mutable'\` = behavioral-test target; \`'immutable'\` = smoke target.
    - \`widgetType\` — copy from \`blueprint.element.widgetType\`. \`'custom'\` = JavaScript-composite control (Radix, MUI, etc.) requiring click-to-open interaction; \`'native'\` = standard HTML element.
-   - \`contextText\` — only for elements inside repeating sections (table rows, list items). Lift from \`repeatingElement.items[].contextText\`. \`null\` otherwise.
+   - \`contextText\` — only for elements inside repeating sections (table rows, list items). Lift from \`repeatingElement.items[].contextText\`. Omit it otherwise.
 
    **Field 2 — \`pageContext\`** (where the test runs):
    \`\`\`json
@@ -350,19 +393,21 @@ ${maintenanceBeforeExecStep}
 
    **No upstream captures available?** Set \`targetElements\` to \`null\`, omit \`pageContext\`, and prefix \`description\` and \`reasoning\` with \`[no-blueprint-data]\`. Use page/feature-level prose; don't cite specific element names without grounding. Apply the marker per entry, not per PR — affected recs only. Log capture failures in \`issuesFound\` (one info-severity entry per failure mode, naming counts). Don't pre-emptively fall back without attempting capture first. Non-UI work is unaffected.
 `;
-    const serviceContext = services?.length ? buildServiceContext(services) : '';
+    const serviceContext = services?.length ? buildServiceContext(services) : "";
     // The <ui-credentials> tags are framing for the agent's prompt context —
     // not real XML — so credentials pass through verbatim and the agent can
     // type them directly into login fields. Reject the only string that would
     // break the framing: a credential containing the closing tag itself.
     const trimmedCredentials = uiCredentials?.trim();
-    if (trimmedCredentials && trimmedCredentials.includes('</ui-credentials>')) {
+    if (trimmedCredentials && trimmedCredentials.includes("</ui-credentials>")) {
         throw new Error("uiCredentials must not contain '</ui-credentials>'");
     }
     const uiCredentialsBlock = trimmedCredentials
         ? `<ui-credentials>\n${trimmedCredentials}\n</ui-credentials>`
-        : '';
-    const testsRepoDirBlock = testsRepoDir ? `<TESTS REPO DIR>${testsRepoDir}</TESTS REPO DIR>\n` : '';
+        : "";
+    const testsRepoDirBlock = testsRepoDir
+        ? `<TESTS REPO DIR>${testsRepoDir}</TESTS REPO DIR>\n`
+        : "";
     // Multi-repo context block. Each entry's `repositoryPath` is checked out at its
     // FEATURE ref; `baseBranch` is that repo's default branch (the diff base), so
     // skyramp_analyze_changes computes a real default…feature diff for the related repo.
@@ -373,7 +418,7 @@ ${maintenanceBeforeExecStep}
                 .map((r) => `  <repository repository="${r.repo}" path="${r.repositoryPath}" base_branch="${r.baseBranch || "auto-detect"}" />`)
                 .join("\n") +
             `\n</related_repositories>\n`
-        : '';
+        : "";
     const testDirInstruction = testsRepoDir
         ? `the \`<output_dir>\` from the \`<services>\` block, rooted under the test repository at \`${testsRepoDir}\` (i.e. \`${testsRepoDir}/<output_dir>\`). Write ALL test output files to paths under \`${testsRepoDir}\`, not under \`${repositoryPath}\`. Do NOT write any test files to the app repository.`
         : `${SERVICE_REFS.testDirRef}. Do NOT create a new \`tests/\` directory at the repo root — use that path. If no \`testDirectory\` is configured, default to the language-conventional location (e.g. \`src/test/java/...\` for Java, \`tests/\` for Python).`;
@@ -408,7 +453,7 @@ This is a plan-only evaluation run: the application under test is NOT running, a
 
 ${userPrompt ? "Generate only the tests that the user requested from the Additional Recommendations. The rules below still apply." : "Drift-based maintenance (Task 1) is complete. This step only processes the GENERATE list. Exception: if a GENERATE item targets a resource with an existing `[skyramp]` contract test, UPDATE that test file (see covered-resource handling below) — a new test case added to an existing file counts toward the budget and is reported in `newTestsCreated`."}
 
-- **MANDATORY — use the plan returned by \`skyramp_register_test_plan\` as-is**: Before generating anything, call \`skyramp_register_test_plan\` (\`stateFile\` required) with your complete candidate list — every test you would generate OR recommend, including the Execution Plan's own pre-ranked GENERATE/ADDITIONAL items and any candidate you drafted yourself, with a \`discriminator\` claim \`{kind, changedCodeAnchor}\` for candidates probing changed logic. Its returned GENERATE list — not the Execution Plan's raw pre-ranked GENERATE section — governs ADD actions from this point on. You MUST generate exactly those scenarios in the exact order listed, keeping each item's \`scenarioName\` exactly as registered — the generation tools match on it and reject renamed or substituted scenarios. If parameter grounding uncovers a distinct bug-catching scenario not already registered, generate it after all planned GENERATE items are complete and report it in \`newTestsCreated\` — this is an additional test driven by source-code analysis and does not count against the GENERATE budget.${hasRelatedRepos ? `\n  - **Multi-repo exception:** this run has related repositories, so the per-repo GENERATE lists are NOT final — they are candidates re-selected by the cross-repo round-robin described in Task 1's "Cross-repo test generation". Register the pooled, type-distributed selection instead of any single repo's GENERATE list. (In single-repo runs, register the GENERATE list exactly as-is.)` : ""}
+- **MANDATORY — use the plan returned by \`skyramp_register_test_plan\` as-is**: Before generating anything, call \`skyramp_register_test_plan\` (\`stateFile\` required) with your complete candidate list — every test you would generate OR recommend, including the Execution Plan's own pre-ranked GENERATE/ADDITIONAL items and any candidate you drafted yourself, with a \`discriminator\` claim \`{kind, changedCodeAnchor}\` for candidates probing changed logic. Its returned GENERATE list — not the Execution Plan's raw pre-ranked GENERATE section — governs ADD actions from this point on. You MUST generate exactly those scenarios in the exact order listed, keeping each item's \`scenarioName\` exactly as registered — the generation tools match on it and reject renamed or substituted scenarios. If parameter grounding uncovers a distinct bug-catching scenario not already registered, generate it after all planned GENERATE items are complete and report it in \`newTestsCreated\` — this is an additional test driven by source-code analysis and does not count against the GENERATE budget.${hasRelatedRepos ? `\n  - **Multi-repo exception:** this run has related repositories, so the per-repo GENERATE lists are NOT final — they are candidates re-selected by the cross-repo round-robin described in Task 1's "Cross-repo test generation". Register the pooled, type-distributed selection instead of any single repo's GENERATE list — call \`skyramp_register_test_plan\` ONCE for the whole run, with candidates from EVERY repo pooled into one list, including at least one UI candidate when any repo changed frontend files (the tool rejects a pooled registration without one). (In single-repo runs, register the GENERATE list exactly as-is.)` : ""}
 - **Do not fabricate tests outside the GENERATE list provided by \`skyramp_analyze_changes\`.** Changes that only modify, delete, or add fields to an EXISTING covered endpoint or component are maintenance: handle them in ${taskRef(TASK_ANALYZE_MAINTAIN)} by UPDATE/DELETE of the existing test, never by creating a new spec. If the GENERATE list is empty, create zero new tests and proceed to ${taskRef(TASK_SUBMIT)}.
 - Scenario JSON files are always new files — always generate them for new methods. Every generated scenario JSON must have a corresponding new integration test generated from it via \`skyramp_integration_test_generation\`.
 - Covered-resource handling (aligns with Execution Plan Step 0): When a GENERATE item targets a resource that already has an existing test file covering the same endpoint:
@@ -460,7 +505,7 @@ ${userPrompt ? "Generate only the tests that the user requested from the Additio
 4. Only pass \`authHeader: ""\` if you can confirm the endpoint is truly unauthenticated.
 
 **How to generate each type (for ADD):**
-- **Integration**: call \`skyramp_batch_scenario_test_generation\` with ALL steps in a single call (pass the \`steps\` array with method, path, requestBody, statusCode for each step). Then call \`skyramp_integration_test_generation\` with the returned scenario file.
+- **Integration**: call \`skyramp_batch_scenario_test_generation\` with ALL steps in a single call (pass the \`steps\` array with method, path, requestBody, statusCode for each step). Then call \`skyramp_integration_test_generation\` with the returned scenario file${INTEGRATION_CODE_REUSE_GEN_CLAUSE}.
   **Use the pre-built scenario JSON from the Execution Plan** — pass the steps array directly. Do NOT read source code models to construct request bodies if the plan already provides them.
   Scenario JSON and test files go in ${testDirInstruction}
   **Pipeline for speed**: Call ALL \`skyramp_batch_scenario_test_generation\` calls in one batch. When they return, call ALL \`skyramp_integration_test_generation\` calls in the next batch. Do NOT serialize per-scenario (batch→integration→batch→integration) — batch ALL scenarios first, then generate ALL integration tests.
@@ -478,7 +523,7 @@ ${CONTRACT_MODE_GUIDANCE}
   - Legacy format: \`username:password\` — the first \`:\` splits username from password.
   These are format hints, not a strict grammar — apply judgment on ambiguous input (e.g. a \`=\` or \`;\` inside a value of the key=value form: split on the \`;\` that precedes a plausible login-field key).
 
-  **Credential selection**: Use the first credential by default. When the scenario requires a specific role, find the credential whose \`role\` field matches (e.g. \`role=admin\`). If no credential matches the required role, use the first credential and add a note to \`issuesFound\` that no matching role was found.
+  **Credential selection**: When several credentials are provided, reason carefully about which one each test case needs BEFORE logging in. Multiple credentials exist so tests can exercise the app as different identities — an app with authorization levels behaves differently per account, and a test only has value when it runs as the identity it is about: an admin workflow needs the admin account, a permission-boundary test needs the restricted one, a plain user flow needs an ordinary user. Read what each credential says about itself — a labeling field (\`role\`, or whatever the customer named it: \`accessLevel\`, \`permissionLevel\`, a team/tenant name, …), the username itself, any extra fields — and match that against the test case's intent. When nothing about a test case calls for a specific identity, use the first credential. If the identity a test case needs is not among the credentials, use the closest match and add a note to \`issuesFound\` naming the identity that was missing. NEVER mix fields across credential lines — type the username, password, and every extra field from the SAME line. The exact values you type identify which credential the generated test will read from the environment at replay time, so a mixed or altered value breaks that binding.
 
   Type all values verbatim. Before navigating to ANY feature URL:
   1. \`browser_navigate\` to the login URL (e.g. \`{baseUrl}/login\`, \`/user/login\`, \`/signin\` — infer from the app's base URL and framework)
@@ -567,7 +612,7 @@ ${CONTRACT_MODE_GUIDANCE}
 
   **The Blueprint Citation Invariant applies during recording too.** Every assertion you emit cites element names — those names must come from blueprint captures, not invention. For N user-intent-level actions, the reference target is N+1 \`browser_blueprint\` calls (the first returns full, the rest return deltas). Traces that follow the pattern produce assertions grounded in observable state changes; traces that skip captures fall back to author-inferred assertions and risk citing names that don't exist in the rendered DOM.
 
-  The rest of the UI workflow stays the same: trace plan, browser auth, navigation, export (\`skyramp_export_zip\`), generation (\`skyramp_ui_test_generation\`), then \`skyramp_reuse_code\` (when \`codeReuse: true\`) and \`skyramp_enhance_assertions\` post-calls. Capture-act-capture adds blueprint captures alongside the existing steps; it doesn't replace anything.
+  The rest of the UI workflow stays the same: trace plan, browser auth, navigation, export (\`skyramp_export_zip\`), generation (\`skyramp_ui_test_generation\`), then the post-calls the generation result lists (${UI_UTILS_REUSE ? "`skyramp_enhance_assertions`, `skyramp_modularization`, `skyramp_reuse_code`, in that order" : "`skyramp_reuse_code` (when `codeReuse: true`) and `skyramp_enhance_assertions`"}). Capture-act-capture adds blueprint captures alongside the existing steps; it doesn't replace anything.
 - **E2E**: Only if BOTH a backend trace \`.json\` AND a Playwright \`.zip\` already exist in the repo. Without both, move to \`additionalRecommendations\`.
 - Skip smoke tests entirely.
 
@@ -585,8 +630,14 @@ If a test **generation** tool call fails:
 If a test **execution** (\`skyramp_execute_test\`) fails for a newly generated test:
 1. Read the error output to diagnose the root cause (4xx on prereq step, assertion mismatch, floating-point precision, 500 from app bug, timeout, etc.).
 2. **Expected failure check (no retry):** If the failure is an assertion error or HTTP error that matches the issue identified in the code analysis (e.g. the test was generated specifically to document a broken endpoint, a UI rendering bug, or a missing validation), then this is the **intended outcome** — the test is correctly catching the real bug. Report it immediately as \`status: "Fail"\` and move on. Do NOT retry.
+
+   This path also covers an assertion failure that application behavior outside this PR's diff explains — for example child records that survive the deletion of their parent, state inherited when an ID is recycled or reused, or a value that ignores a status the test set. Before you keep such a test red, confirm the cause in the source: read the handler, model, or query that should have done the work, and find the specific operation that is missing or wrong. If you find it, report the test as \`status: "Fail"\` and add an \`issuesFound\` entry for it. Do NOT retry.
+
+   If you cannot point at the missing or wrong line in application code, the app is not at fault — shared or seeded data, parallel test workers, or setup the test itself never did explain the collision. Treat that as an infrastructure failure: fix it and retry once as in step 3.
+
+   **If you did confirm the missing or wrong operation in the source, do NOT make the test pass.** Never add a reset, cleanup, or setup call for isolation. Never weaken the assertion — no \`==\` to \`>=\`, no exact value to a range. A failing test whose diagnosis names a pre-existing bug is the most valuable output of this run; a passing version of it reports nothing.
 3. Apply a targeted fix and retry **once** only for **infrastructure failures** — that means exactly **2 total \`skyramp_execute_test\` calls per test file** for these cases. Examples of infrastructure failures worth fixing:
-   - Assertion mismatch due to floating-point precision or wrong expected value (not a real bug)
+   - Assertion mismatch from floating-point precision, or an expected value mis-transcribed from the observed response or computed with an arithmetic slip. If application behavior outside the diff explains the mismatch, it is not an infrastructure failure — use step 2 instead.
    - Import error, syntax error, or missing dependency in the generated test file
    - Connection refused or timeout unrelated to the app under test
 4. If it still fails after the retry, report it as \`status: "Fail"\` with the error details and move on — do NOT edit and re-run a third time. A failing test that documents a real bug is a valid outcome.
@@ -597,13 +648,13 @@ If a generated UI test fails with a timeout waiting for an element after navigat
 2. Add \`await page.locator('[data-testid="some-element"]').waitFor({ state: 'visible', timeout: 10000 });\` for the specific element the test needs.
 Do NOT use \`page.waitForTimeout()\` with fixed delays. Do NOT retry more than once — if the test still fails after this fix, report it as "Fail".
 
-**After generation, you MUST do exactly these steps — nothing more, nothing less:**
+**After generation, you MUST do exactly these steps — nothing more, nothing less** (generation results may add their own CRITICAL NEXT STEPS — e.g. modularize-then-reuse for integration or UI tests generated with \`codeReuse: true\` — follow those too, in the order the result states):
 1. **[MANDATORY] After \`skyramp_integration_test_generation\`**: Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated integration test file, \`testType: "integration"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.
 2. **[MANDATORY] After \`skyramp_contract_test_generation\` with \`providerMode\`**: Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated provider contract test file, \`testType: "contract"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.
 ${UI_CODE_REUSE_STEP}
-4. **[MANDATORY] After \`skyramp_ui_test_generation\`**: Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated UI test file, \`testType: "ui"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file. The HIGH-tier \`possibleAssertions\` from your second \`browser_blueprint\` captures (after each action) during trace recording are in your context — when the enhance instructions ask you to add assertions for state-changing actions, use those grounded candidates first (they contain exact computed values from the DOM delta, e.g. \`toHaveText('Total: $899.98')\`). Only fall back to deriving values from the test file or source code when no HIGH-tier candidate covers the action.
-5. **Wait**: Do NOT proceed to test execution until steps 1–4 are complete and the verification checklist in the \`skyramp_enhance_assertions\` tool result has been validated for EVERY generated test file.
-Do not make any changes other than the code-reuse refactoring (step 3) and the assertion enhancements described above. For example: do not modify auth headers, cookies, tokens, env vars, or imports that the generation tool already set correctly — those are correct by construction and changing them breaks auth or execution.
+4. **[MANDATORY] After \`skyramp_ui_test_generation\`**: ${UI_ENHANCE_STEP} The HIGH-tier \`possibleAssertions\` from your second \`browser_blueprint\` captures (after each action) during trace recording are in your context — when the enhance instructions ask you to add assertions for state-changing actions, use those grounded candidates first (they contain exact computed values from the DOM delta, e.g. \`toHaveText('Total: $899.98')\`). Only fall back to deriving values from the test file or source code when no HIGH-tier candidate covers the action.
+5. **Wait**: Do NOT proceed to test execution until steps 1–4 (plus any generation-result CRITICAL NEXT STEPS) are complete and the verification checklist in the \`skyramp_enhance_assertions\` tool result has been validated for EVERY generated test file.
+Do not make any changes other than the code-reuse refactoring (step 3 and the generation-result reuse steps) and the assertion enhancements described above. For example: do not modify auth headers, cookies, tokens, env vars, or imports that the generation tool already set correctly — those are correct by construction and changing them breaks auth or execution.
 
 **Execution timing:**
 - **beforeStatus** (maintained tests only): execute each maintained test file **once at the start** (before any edits) to capture \`beforeStatus\`. This is the only execution allowed before edits.
@@ -611,11 +662,13 @@ Do not make any changes other than the code-reuse refactoring (step 3) and the a
 - Only report test results for files you actually ran.
 **Auth**: If \`skyramp_analyze_changes\` reports an auth token or \`SKYRAMP_TEST_TOKEN\` is set, pass it in **every** \`skyramp_execute_test\` call from the first attempt — do NOT wait for a 401/403 to discover auth is needed.`;
     }
-    const primaryRepoBlock = primaryRepo ? `<REPOSITORY>${primaryRepo}</REPOSITORY>\n` : '';
+    const primaryRepoBlock = primaryRepo
+        ? `<REPOSITORY>${primaryRepo}</REPOSITORY>\n`
+        : "";
     return `<TITLE>${prTitle}</TITLE>
 <DESCRIPTION>${prDescription}</DESCRIPTION>
 ${primaryRepoBlock}<REPOSITORY PATH>${repositoryPath}</REPOSITORY PATH>
-${relatedReposBlock}${testsRepoDirBlock}${serviceContext ? serviceContext + '\n' : ''}${uiCredentialsBlock ? uiCredentialsBlock + '\n' : ''}## Goal
+${relatedReposBlock}${testsRepoDirBlock}${serviceContext ? serviceContext + "\n" : ""}${uiCredentialsBlock ? uiCredentialsBlock + "\n" : ""}## Goal
 
 Every test this run delivers must be a usable functional test — one that exercises the running application through its real API or UI surface and that the user can keep running in CI. Optimize for catching real production bugs: business-rule and computed-field errors, data-integrity violations, security-boundary bypasses, broken user journeys. A test that would FAIL if the application's logic were wrong beats several that merely exercise new surface — prefer fewer, higher-signal tests over padded coverage. The tasks below define which tests are in scope for this run; use the Skyramp MCP server tools for all of them.
 
@@ -645,13 +698,15 @@ ${task3CountRule}
 
 ${reportLanguageBlock}Call \`skyramp_submit_report\` with \`stateFile\` (from \`skyramp_analyze_changes\` output) — the stateFile is required for execution outcome tracking, and the report is written beside it. Field names, types, and formats are defined in the tool's parameter schema — follow them exactly.
 
-${hasRelatedRepos ? `
+${hasRelatedRepos
+        ? `
 - **MULTI-REPO attribution**: Set the \`repository\` field (\`owner/repo\`) on EVERY \`newTestsCreated\`, \`testResults\`, \`issuesFound\`, and \`additionalRecommendations\` item — including items about the PRIMARY repo — so each finding is unambiguously attributed. The primary repo's \`repository\` is \`${primaryRepo || "<the primary repo's owner/repo>"}\`; items derived from a related repo's diff (from the \`<related_repositories>\` analysis) carry that repo's \`repository\` value. In \`businessCaseAnalysis\`, include a short per-repo subsection and call out any cross-repo correlations you found.
-` : ""}
+`
+        : ""}
 - **additionalRecommendations**: AT MOST ${maxRecommendations - maxGenerate} items.
   - For \`testType: "contract"\` entries: **\`primaryEndpoint\` is required** (e.g. \`"GET /api/v1/users/{user_id}"\`). The tool will reject the submission without it — do not omit it or you will be forced to resubmit.
 
-${getTraceRecordingPromptText({ outputDir: `${repositoryPath}/.skyramp`, modularize: false })}`;
+${getTraceRecordingPromptText({ outputDir: `${repositoryPath}/.skyramp`, modularize: false, modularizeViaGenerationResult: UI_UTILS_REUSE })}`;
     // Neither path reaches the agent any more: SKYR-4147 made the report derive from the
     // state file's directory, and that directory comes from the environment via
     // runArtifactDir(). Keep it that way — a path the model retypes out of this prose is a

package/build/recommendation/budgeters/shared.js

@@ -1,6 +1,6 @@
 import { TestType } from "../../types/TestTypes.js";
 import { inferScenarioType, prioritizeAttackSurfaceBundles } from "../diversity.js";
-import { externalDedupKey, scenarioCoverageKey, isAttackSurfaceSecurityBoundary, } from "../../prompts/test-recommendation/recommendationShared.js";
+import { externalDedupKeys, scenarioCoverageKeys, isAttackSurfaceSecurityBoundary, } from "../../prompts/test-recommendation/recommendationShared.js";
 import { logger } from "../../utils/logger.js";
 /**
  * Backend GENERATE slot count:
@@ -20,25 +20,39 @@ export function reservedUISlots(ctx) {
     return ctx.hasFrontendChanges && ctx.maxGenerate > 0 ? 1 : 0;
 }
 /**
- * Drop candidates whose method-aware resource+type is already covered by an
- * external test — except protected `bug_caught` / attack-surface scenarios,
- * which require semantic flaw coverage the external test may not provide.
+ * Split candidates by whether an external test already covers them. Protected
+ * `bug_caught` / attack-surface scenarios always count as uncovered — they
+ * require semantic flaw coverage the external test may not provide.
+ *
+ * A candidate is covered only when the set holds EVERY one of its keys. One
+ * match is not coverage: a scenario exercising two changed endpoints would lose
+ * the endpoint the external test does not reach (SKYR-4214). An empty key list
+ * carries no information, so it never removes anything.
+ *
+ * The covered group is held back, not discarded. `runBudget` moves it into
+ * ADDITIONAL when GENERATE's backend half would otherwise be empty (SKYR-4024),
+ * and records it as dropped, with a reason, when it does not.
  */
-function applyExternalDedup(ranked, externalCoverage) {
+function partitionByExternalCoverage(ranked, externalCoverage) {
     if (externalCoverage.size === 0)
-        return ranked;
-    return ranked.filter((item) => {
-        const key = externalDedupKey(item.scenario);
-        if (externalCoverage.has(key)) {
-            if (item.scenario.category === "bug_caught" || isAttackSurfaceSecurityBoundary(item.scenario)) {
-                logger.info(`External dedup: preserving "${item.scenario.scenarioName}" (${key}) — protected bug/attack-surface scenario requires semantic flaw coverage`);
-                return true;
-            }
-            logger.info(`External dedup: skipping "${item.scenario.scenarioName}" (${key}) — covered by external test`);
-            return false;
+        return { uncovered: ranked, covered: [] };
+    const uncovered = [];
+    const covered = [];
+    for (const item of ranked) {
+        const keys = externalDedupKeys(item.scenario);
+        if (keys.length === 0 || !keys.every((key) => externalCoverage.has(key))) {
+            uncovered.push(item);
+            continue;
         }
-        return true;
-    });
+        if (item.scenario.category === "bug_caught" || isAttackSurfaceSecurityBoundary(item.scenario)) {
+            logger.info(`External dedup: preserving "${item.scenario.scenarioName}" (${keys.join(", ")}) — protected bug/attack-surface scenario requires semantic flaw coverage`);
+            uncovered.push(item);
+            continue;
+        }
+        logger.info(`External dedup: "${item.scenario.scenarioName}" (${keys.join(", ")}) covered by an external test — eligible for the reserve`);
+        covered.push({ item, keys });
+    }
+    return { uncovered, covered };
 }
 /**
  * Shared budgeting pipeline. All Budgeters run the same external-dedup,
@@ -49,10 +63,11 @@ function applyExternalDedup(ranked, externalCoverage) {
  * diffExecutionPlan.ts exactly.
  */
 export function runBudget(ranked, ctx, pick) {
+    const dropped = [];
     const backend = backendGenerateCount(ctx);
     const uiSlots = reservedUISlots(ctx);
-    const deduped = applyExternalDedup(ranked, ctx.externalCoverage);
-    const slotOrdered = prioritizeAttackSurfaceBundles(deduped);
+    const { uncovered, covered } = partitionByExternalCoverage(ranked, ctx.externalCoverage);
+    const slotOrdered = prioritizeAttackSurfaceBundles(uncovered);
     // When UI slots are reserved, keep UI candidates out of the backend pick so the
     // reserved slot can always be filled below. Otherwise a high-ranked (e.g.
     // CRITICAL) UI candidate could be consumed by the backend pick on a mixed PR,
@@ -77,14 +92,77 @@ export function runBudget(ranked, ctx, pick) {
         chosen.add(item);
     }
     const generate = [...backendGenerate, ...uiGenerate];
-    // ADDITIONAL = everything not chosen for GENERATE, in rank order, capped at the
-    // remaining budget, minus any whose resource+type is already covered by GENERATE.
-    const generatedCoverage = new Set(generate.map((item) => scenarioCoverageKey(item.scenario)));
-    const additional = slotOrdered
-        .filter((it) => !chosen.has(it))
-        .slice(0, Math.max(0, ctx.maxTotal - generate.length))
-        .filter((item) => !generatedCoverage.has(scenarioCoverageKey(item.scenario)));
+    // SKYR-4024. A covered candidate is one an existing test already reaches, so
+    // generating a second test for it is wrong — maintenance updates the existing
+    // one. But dropping it outright removed it from the RECOMMENDATIONS too, and an
+    // empty GENERATE is authoritative downstream. The reserve surfaces it as
+    // ADDITIONAL instead. The emptiness test reads the backend half: on a mixed PR
+    // one UI candidate fills the reserved slot while every covered backend
+    // candidate would otherwise vanish.
+    //
+    // Two conditions keep the reserve shut where recommending nothing is right.
+    // Backend slots must exist, so a UI-only PR is left alone. And the PR must not
+    // touch a test file of its own: coverage is read from the working tree, and a
+    // test file without the Skyramp marker counts as external, so a PR that adds
+    // its own tests would have that coverage used as grounds to recommend
+    // duplicates of it.
+    const spendReserve = backendGenerate.length === 0 && backend > 0 && covered.length > 0 && !ctx.diffChangesTestFiles;
+    if (spendReserve) {
+        logger.info(`External dedup: GENERATE empty after dedup — recommending ${covered.length} held-back candidate(s) as ADDITIONAL rather than approving an empty plan`);
+    }
+    else if (covered.length > 0) {
+        // SKYR-4214. The reserve stayed shut, so these really are dropped — say so,
+        // with the reason, instead of leaving the agent an unexplained short list.
+        const reason = backendGenerate.length > 0
+            ? `the backend half of GENERATE is filled (${backendGenerate.length})`
+            : backend === 0
+                ? "no backend slots (UI-only PR)"
+                : "the PR changes test files of its own";
+        logger.info(`External dedup: dropping ${covered.length} covered candidate(s) — reserve shut because ${reason}`);
+        for (const { item, keys } of covered) {
+            dropped.push({
+                candidateId: item.candidateId,
+                reason: `covered by an external test (${keys.join(", ")})`,
+            });
+        }
+    }
+    // ADDITIONAL = everything not chosen for GENERATE, in rank order, minus any
+    // whose subject endpoints are ALL already covered by GENERATE, then capped at
+    // the remaining budget. All, not any: an item that also covers an endpoint no
+    // GENERATE item reaches is not a duplicate. An empty key list never removes
+    // an item.
+    //
+    // The duplicate filter runs BEFORE the cap. In the other order a duplicate
+    // took a slot and then vacated it, and nothing moved up: eval run
+    // 32543498147, fixture cc15-org-reviewer-role, filled 19 of a maxTotal of 20
+    // while 16 candidates carried the reason "beyond the maxTotal budget of 20".
+    // A candidate that is both a duplicate and past the cap now reports the
+    // duplicate — the stronger reason, and the only one that does not depend on
+    // where the cap happened to fall.
+    const additionalSource = spendReserve
+        ? [...slotOrdered, ...prioritizeAttackSurfaceBundles(covered.map((c) => c.item))]
+        : slotOrdered;
+    const notChosen = additionalSource.filter((it) => !chosen.has(it));
+    const remainingBudget = Math.max(0, ctx.maxTotal - generate.length);
+    const generatedCoverage = new Set(generate.flatMap((item) => scenarioCoverageKeys(item.scenario)));
+    const notDuplicate = notChosen.filter((item) => {
+        const keys = scenarioCoverageKeys(item.scenario);
+        if (keys.length === 0 || !keys.every((key) => generatedCoverage.has(key)))
+            return true;
+        dropped.push({
+            candidateId: item.candidateId,
+            reason: `covered by GENERATE (${keys.join(", ")})`,
+        });
+        return false;
+    });
+    const additional = notDuplicate.slice(0, remainingBudget);
+    for (const item of notDuplicate.slice(remainingBudget)) {
+        dropped.push({
+            candidateId: item.candidateId,
+            reason: `beyond the maxTotal budget of ${ctx.maxTotal}`,
+        });
+    }
     // Budgeting itself produces no demotions; the register-plan selection stage
     // (planRanker.selectPlan) fills this channel from discriminator verification.
-    return { generate, additional, reservedUISlots: uiSlots, demotions: [] };
+    return { generate, additional, reservedUISlots: uiSlots, demotions: [], dropped };
 }

package/build/recommendation/discriminators.js

@@ -281,9 +281,20 @@ function isNegativeAssertStep(step) {
     if (step?.expectedStatusCode === 404)
         return true;
     const assertions = [...toStringArray(step?.expectedResponseFields), ...toStringArray(step?.bodyMustInclude)];
-    return assertsEmptyOrZero(assertions);
+    return assertsEmptyOrZero(assertions, step?.responseBody);
 }
-function assertsEmptyOrZero(strings) {
+/**
+ * True when the step asserts an empty or zero result, reading the assertion
+ * strings AND `responseBody`. An EMPTY ARRAY body is itself the "no rows came
+ * back" assertion, and can be the only empty-result signal a step carries.
+ *
+ * `{}` deliberately does NOT count: an unspecified body is filled in as `{}`
+ * (ScenarioGenerationService), so it cannot be told apart from a body the agent
+ * never wrote. `isAssertStep` above already reads `{}` as asserting nothing.
+ */
+function assertsEmptyOrZero(strings, responseBody) {
+    if (Array.isArray(responseBody) && responseBody.length === 0)
+        return true;
     return strings.some((raw) => {
         const s = raw.toLowerCase();
         if (/\bcount\b/.test(s) && /\b0\b/.test(s))

package/build/recommendation/planRanker.d.ts

@@ -4,9 +4,9 @@ import { ScenarioCategory } from "../types/TestRecommendation.js";
 export interface RankOptions {
     /**
      * Categories that take the top carve-out tier ahead of everything else.
-     * Defaults to the `CATEGORY_PRIORITY === "CRITICAL"` categories (new_endpoint,
-     * bug_caught). Exposed so phase 2 can tune the carve-out WITHOUT reintroducing
-     * the agent's priority tag as a ranking input.
+     * Defaults to the `CATEGORY_PRIORITY === "CRITICAL"` categories (bug_caught only —
+     * new_endpoint is MEDIUM, not carved out). Exposed so phase 2 can tune the carve-out
+     * WITHOUT reintroducing the agent's priority tag as a ranking input.
      */
     carveOutCategories?: ScenarioCategory[];
     /**
@@ -32,9 +32,9 @@ export interface SelectPlanContext extends BudgetContext {
  * independent of input order (the final tiebreak is the stable `candidateId`).
  *
  * Ordering (highest first):
- *   1. Carve-out — bug_caught / CRITICAL-category scenarios (new_endpoint,
- *      bug_caught), preserving the protected-first convention of
- *      `roundRobinByType` / `prioritizeAttackSurfaceBundles`.
+ *   1. Carve-out — CRITICAL-category scenarios (bug_caught), preserving the
+ *      protected-first convention of `roundRobinByType` /
+ *      `prioritizeAttackSurfaceBundles`.
  *   2. Verified discriminators — candidates whose declared discriminator survived
  *      `validateDiscriminator` (marked via `verifiedDiscriminator`) float ahead of
  *      unverified peers in the same tier.

package/build/recommendation/planRanker.js

@@ -1,6 +1,6 @@
 import { CATEGORY_PRIORITY, PriorityTier } from "../types/TestRecommendation.js";
 import { diversityBalancedBudgeter } from "./budgeters/diversityBalancedBudgeter.js";
-import { parseRouteLine, normalizeDiffPath } from "../utils/routeParsers.js";
+import { collectChangedRouteLines, findStepOnChangedRoute } from "../utils/changedRoutes.js";
 const PRIORITY_RANK = {
     CRITICAL: 0,
     HIGH: 1,
@@ -14,9 +14,9 @@ const DEFAULT_CARVE_OUT_CATEGORIES = Object.keys(CATEGORY_PRIORITY).filter((cate
  * independent of input order (the final tiebreak is the stable `candidateId`).
  *
  * Ordering (highest first):
- *   1. Carve-out — bug_caught / CRITICAL-category scenarios (new_endpoint,
- *      bug_caught), preserving the protected-first convention of
- *      `roundRobinByType` / `prioritizeAttackSurfaceBundles`.
+ *   1. Carve-out — CRITICAL-category scenarios (bug_caught), preserving the
+ *      protected-first convention of `roundRobinByType` /
+ *      `prioritizeAttackSurfaceBundles`.
  *   2. Verified discriminators — candidates whose declared discriminator survived
  *      `validateDiscriminator` (marked via `verifiedDiscriminator`) float ahead of
  *      unverified peers in the same tier.
@@ -77,62 +77,7 @@ function categoryRank(candidate) {
     const tier = CATEGORY_PRIORITY[candidate.scenario?.category] ?? PriorityTier.LOW;
     return PRIORITY_RANK[tier];
 }
-/**
- * Extract method+path from every changed (`+`/`-`, non-header) line of a raw
- * unified diff. Reuses `parseRouteLine`, which already strips the leading
- * `+`/`-` marker and matches the same route-decorator patterns the endpoint
- * scanner does.
- */
-function collectChangedRouteLines(diffText) {
-    const routes = [];
-    let currentFile = "";
-    for (const line of diffText.split("\n")) {
-        // Track the current file from the unified-diff header so parseRouteLine
-        // gets the real path — its UI-component guard (UI_COMPONENT_EXT) depends
-        // on it, or a route-shaped line inside a .tsx/.jsx file (e.g. a client
-        // router registration) gets misparsed as a changed backend route.
-        if (line.startsWith("+++ ")) {
-            const spec = line.slice(4).trim().split("\t")[0];
-            currentFile = spec === "/dev/null" ? "" : normalizeDiffPath(spec);
-            continue;
-        }
-        if (line.startsWith("--- ") || line.startsWith("diff --git") || line.startsWith("index "))
-            continue;
-        if (!(line.startsWith("+") || line.startsWith("-")))
-            continue;
-        const parsed = parseRouteLine(line, currentFile);
-        if (parsed)
-            routes.push({ method: parsed.method, path: parsed.path });
-    }
-    return routes;
-}
-/**
- * Whether any step of `scenario` targets a method+path on the changed hunk.
- * Diff-extracted paths are local to the file's own router declaration (e.g.
- * "/suggestions"); scenario step paths are fully mounted (e.g.
- * "/api/recipes/suggestions") once drafted from a scanned/recovered endpoint.
- * A local path matches when the step path ends with it, so the cross-file
- * mount prefix difference (see recoverRemovedEndpointsFromBase, SKYR-4026)
- * doesn't prevent the match.
- */
+/** Whether any step of `scenario` targets a method+path on the changed hunk. */
 function scenarioOnChangedHunk(scenario, changedRoutes) {
-    if (changedRoutes.length === 0)
-        return false;
-    for (const step of scenario.steps ?? []) {
-        const stepMethod = (step.method ?? "").toUpperCase();
-        const stepPath = (step.path ?? "").replace(/\/+$/, "");
-        for (const route of changedRoutes) {
-            if (route.method.toUpperCase() !== stepMethod)
-                continue;
-            const routePath = route.path.replace(/\/+$/, "");
-            if (routePath === "") {
-                if (stepPath === "" || stepPath === "/")
-                    return true;
-                continue;
-            }
-            if (stepPath === routePath || stepPath.endsWith(routePath))
-                return true;
-        }
-    }
-    return false;
+    return !!findStepOnChangedRoute(scenario.steps, changedRoutes);
 }