@skyramp/mcp 0.3.7 → 0.3.8

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

@@ -3,6 +3,7 @@ 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 { setReportLanguage } from "../../utils/reportLanguage.js";
+import { setPlanOnlyMode } from "../../utils/planOnlyMode.js";
 import { TASK_ANALYZE_MAINTAIN, TASK_GENERATE, TASK_SUBMIT, taskRef, } from "../test-recommendation/recommendationShared.js";
 import { getTraceRecordingPromptText } from "../../playwright/traceRecordingPrompt.js";
 import { isContractConsumerModeEnabled, isPomReuseEnabled, isUtilsReuseEnabled, } from "../../utils/featureFlags.js";
@@ -119,6 +120,13 @@ export function getTestbotPrompt(opts) {
     // 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);
+    // SKYR-4250: same capture point, same last-render-wins rule, for the
+    // plan-only lane. skyramp_submit_report's SKYR-3883 guard
+    // (findUnchangedFileClaims) verifies newTestsCreated against the working
+    // tree; a plan-only run writes no files, so without this every declaration
+    // is unchanged-file-flagged and the agent is forced to demote it to
+    // additionalRecommendations.
+    setPlanOnlyMode(planOnly);
     let reportLanguageBlock = "";
     if (language && language !== "en") {
         const reportLanguageName = new Intl.DisplayNames(["en"], { type: "language" }).of(language) ??
@@ -222,6 +230,9 @@ ${maintenanceBeforeExecStep}
    - Incorrect arithmetic in business logic (discount calculations, price aggregation)
    Log each finding in \`issuesFound\` with a \`severity\` (critical/high/medium/low). These bugs should inform your test design in Task 2.
 
+   **Requirement check — does the code do what the PR says it does?** Read the \`<TITLE>\` and \`<DESCRIPTION>\` above as a statement of *intended* behavior and check the diff against it, requirement by requirement. The description is not outranked by the code: when the two disagree, that is a \`requirement_conflict\`, not a case of "the description loses". Detection, the requirements-file rules, the four false-red pre-checks and the promotion ordering are specified in the Code Review step of the Execution Plan \`skyramp_analyze_changes\` returned — follow them there rather than improvising; read any requirements file the description names from \`${repositoryPath}\`.
+   - **On a mismatch, do both.** (a) Add an \`issuesFound\` entry at severity \`high\` or \`critical\` — never \`medium\` or below — quoting the requirement and naming the file and line that contradicts it. (b) Carry it into Task 2 as a \`requirement_conflict\` candidate: a test asserting **what the description requires**, which therefore FAILS on the current code. Where no such test is recordable, record the Execution Plan's VERIFY-style entry in \`additionalRecommendations\` instead — never resolve the disagreement by asserting what the code does.
+
 4. **Blueprint Citation Invariant** (UI test recommendations only). Every named UI element in your recommendation must correspond to an element actually captured in one of the blueprints you captured from the UI Blueprint Capture section of \`skyramp_analyze_changes\`. For **every** UI recommendation — both \`newTestsCreated[]\` entries (tests you generated) AND \`additionalRecommendations[]\` entries (deferred tests) with \`testType: "ui"\` — populate **four** fields: \`description\`, \`reasoning\`, \`targetElements\`, and \`pageContext\`. \`description\` and \`reasoning\` carry different roles — fill BOTH (see Field 4 below). The structured fields (\`targetElements\`, \`pageContext\`) are required on UI recs in BOTH arrays; non-UI recs (contract / integration / e2e / batch-scenario) MUST omit them.
 
    **Field 1 — \`targetElements\`** (the elements the test targets — array, length 1+):
@@ -431,7 +442,7 @@ ${maintenanceBeforeExecStep}
 **Self-check before calling \`skyramp_submit_report\`:** count your final GENERATE list, then confirm \`newTestsCreated\` has exactly that many entries — one per GENERATE item. A GENERATE item always goes in \`newTestsCreated\` (even though no file was generated in this run — the declaration IS the deliverable); \`additionalRecommendations\` holds ONLY candidates that are NOT in the GENERATE list. Reporting a GENERATE item as a recommendation instead of a declaration is the single most common plan-only reporting error — recheck the placement before submitting.`;
     }
     else {
-        task3CountRule = `Otherwise (your Budget Plan is non-zero): in \`newTestsCreated\`, you must have exactly as many budget-counting new tests as your committed Budget Plan's generate count (at most ${maxGenerate}). Only new files (ADD) created for the planned GENERATE items count toward this target — GENERATE items converted to UPDATE do not. You may also include at most one additional discovered-scenario file in \`newTestsCreated\` (the bug-catching test generated after all planned items); that extra test does **not** count against the budget. If you have fewer budget-counting new tests than your generate count, backfill from the remaining ADDITIONAL candidates before proceeding. Only proceed with fewer if all candidates failed after retry AND the fallback single-contract test also failed.`;
+        task3CountRule = `Otherwise (your Budget Plan is non-zero): in \`newTestsCreated\`, you must have exactly as many budget-counting new tests as your committed Budget Plan's generate count (at most ${maxGenerate}). Only new files (ADD) created for the planned GENERATE items count toward this target — GENERATE items converted to UPDATE do not. You may also include at most one additional discovered-scenario file in \`newTestsCreated\` (the bug-catching test generated after all planned items); that extra test does **not** count against the budget. If you have fewer budget-counting new tests than your generate count, backfill from the remaining ADDITIONAL candidates before proceeding. Only proceed with fewer if every remaining candidate failed after retry — and, on a PR with backend changes, the fallback single-contract test also failed. A frontend-only PR has no backend fallback: its exhausted candidates go to \`additionalRecommendations\` with the failure reason.`;
     }
     // Task 2 branches wholesale in plan-only eval runs (SKYR-3879 plan-only
     // lane): the standard task mandates generation and execution, which a
@@ -443,9 +454,9 @@ ${maintenanceBeforeExecStep}
 
 This is a plan-only evaluation run: the application under test is NOT running, and this run evaluates test SELECTION only. Nothing is generated or executed in this task.
 
-- Draft your complete candidate list exactly as the Execution Plan directs — every API test (contract / integration / batch-scenario) you would generate OR recommend for this PR, grounded in the analysis output and the diff. Favor tests that would FAIL if the changed logic were buggy, not just tests that exercise the new surface.
+- Draft your complete candidate list exactly as the Execution Plan directs — every test you would generate OR recommend for this PR, grounded in the analysis output and the diff. Favor tests that would FAIL if the changed logic were buggy, not just tests that exercise the new surface.
 - If a tool named \`skyramp_register_test_plan\` is available, call it with the full candidate union — include a \`discriminator\` claim \`{kind, changedCodeAnchor}\` for every candidate that probes changed logic — and treat its returned GENERATE list as your final selection. If that tool is not available, commit to your Budget Plan's GENERATE selection (at most ${maxGenerate}).
-- Skip UI and E2E candidates entirely — with no running app there are no blueprints to ground them, and this lane evaluates API test selection only.
+- Include UI and E2E candidates on the same footing as the API types. The app is not running, so you cannot capture a blueprint — plan them ungrounded rather than drop them. For every UI entry, set \`targetElements: null\`, omit \`pageContext\`, and prefix BOTH \`description\` and \`reasoning\` with \`[no-blueprint-data]\`. Describe the page or feature the test would exercise; do not name an element you have not seen. This lane is the one case where you fall back without attempting a capture first, so do NOT log the fallback in \`issuesFound\` — capture was never applicable here, and nothing failed.
 - Take no other actions in this task: no test generation tools, no browser traces or blueprint captures, no test files written, no test executions. Proceed directly to ${taskRef(TASK_SUBMIT)}.`;
     }
     else {
@@ -453,8 +464,8 @@ 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 — 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)}.
+- **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. **Every \`requirement_conflict\` candidate from Task 1's requirement check belongs in this registration** — register it with category \`requirement_conflict\` so it ranks in the top tier and takes the first promoted slot rather than losing one to a bug-catching candidate; omitting it from the candidate list is how a stated requirement silently loses its test.${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 returned by \`skyramp_register_test_plan\`.** A change to an EXISTING covered endpoint or component is maintenance only where an existing test asserts the changed value: handle that in ${taskRef(TASK_ANALYZE_MAINTAIN)} by UPDATE/DELETE of the existing test. A changed value, option, or behavior that no existing test asserts is not maintenance — it is a candidate you register (GENERATE or ADDITIONAL), however small the change. 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:
   - If the existing test source is \`[external]\`, skip the resource entirely — the external test already provides coverage. Do NOT UPDATE, REGENERATE, or DELETE external tests.
@@ -479,6 +490,9 @@ ${userPrompt ? "Generate only the tests that the user requested from the Additio
 - **Always generate a test for critical bugs, even if it will fail.** When a GENERATE-tagged item targets a page or endpoint with a known bug, do NOT skip it because you expect the test to fail — a failing test that documents a bug is more valuable than a text-only description. This applies within the existing GENERATE budget; do not add extra tests beyond the plan.
    - For UI rendering bugs: navigate to the broken page and add a \`browser_assert\` that verifies the page rendered its expected content (e.g. assert the page heading is visible). The assertion will fail on the broken page, which is the correct outcome — it documents the bug as a failing test.
    - The assertion MUST target the broken page itself, not a different page that works. If \`/orders/{id}/edit\` crashes, assert on \`/orders/{id}/edit\` (e.g. "Edit Order" heading visible), NOT on \`/orders\`.
+- **The same rule covers a \`requirement_conflict\` from Task 1's requirement check — and it is promoted first.** Generate the test that asserts what the PR description requires, not what the code implements. It fails today; that is the deliverable, and it turns green when the code is fixed to match the description. Do NOT re-aim it at the implemented behavior to get a passing run, and do NOT drop it because a bug-catching test already occupies a slot — requirement conflicts take the first slots of the promotion bound, so the bug-catching tests yield to it, not the other way round.
+   - For a "should no longer be present" requirement: navigate to the page the description names, confirm from the capture that the element still renders, then assert its **absence**. The element name comes from the live capture, so the assertion is grounded; the failure is the conflict. Assert on the page the requirement is about — not a sibling page where the element is genuinely gone.
+   - For a "should now do X" requirement the code does not do: assert X. Same rule — the stated requirement is the expectation.
 - **Critical categories first**: At least 1 of the generated tests MUST be from a critical category (security_boundary, business_rule, data_integrity, breaking_change) if such candidates exist in the GENERATE set.
 - **Parallel generation (IMPORTANT for speed)**: Generate **independent tests in parallel** whenever possible. Tests targeting different endpoints with different output files can be generated concurrently in the same tool call batch. Specifically:
   - Call \`skyramp_batch_scenario_test_generation\` for ALL integration scenarios AND \`skyramp_contract_test_generation\` for ALL contract tests **in the same tool call batch**.
@@ -565,7 +579,6 @@ ${CONTRACT_MODE_GUIDANCE}
   - **\`browser_visual_snapshot\` — for visual/appearance checks**: when the instruction asks to take a screenshot, capture a baseline, or verify how a page/element/region *looks* (not its text or value), call \`browser_visual_snapshot\` — it records a \`toHaveScreenshot()\` assertion so the generated test pixel-compares against a baseline on every run. Do NOT use \`browser_take_screenshot\` for this: it captures a throwaway image that is dropped at export and never appears in the generated test (use it only to view the page yourself).
   - **Wait for stable state before the second capture**: After performing an action that affects computed fields (filling a discount, submitting a form, adding an item), check the current page state before calling the second \`browser_blueprint\` (the capture after the action). If a computed field — total, price, count, derived text — still shows its initial empty or zero value (e.g. \`$0.00\`, \`0\`, \`Loading...\`, empty string), that means async data hasn't finished loading yet. Use \`browser_wait_for\` to wait up to 10 seconds for the field to update to a real value (for example, wait for the total to show a non-zero amount like \`$799.99\` instead of \`$0.00\`). Once the field shows a real value, THEN call the second \`browser_blueprint\` to capture stable state. If after 10 seconds the field still hasn't updated, skip the assertion on that field — don't capture and assert a value that hasn't loaded.
   If \`browser_navigate\` fails (app not running / connection refused), apply skip condition (a) above: move the intended test to \`additionalRecommendations\` with the failure reason AND record the outage in \`issuesFound\`.
-  Record at most 2-3 UI traces per run to stay within tool call budget. Quality over quantity: 1 great test is better than 3 mediocre ones — do not pad to reach the count.
   **Strategic assertions** — key checkpoints only, 3 to 5 per test:
     - **After the main action completes**: verify the outcome is visible (new item appears, form saves, confirmation shows)
     - **State transitions**: verify counts, totals, or status fields update correctly
@@ -631,6 +644,8 @@ If a test **execution** (\`skyramp_execute_test\`) fails for a newly generated t
 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.
 
+   **A \`requirement_conflict\` test failing is likewise the intended outcome.** It asserts what the PR description requires and the code does not do; a red result is the finding, so report \`status: "Fail"\` with the conflict named in \`issuesFound\` and move on. Do NOT retry it, do NOT relax the assertion toward the implemented behavior, and do NOT delete the test — either of those hides the disagreement the run exists to surface.
+
    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.
@@ -683,7 +698,7 @@ If you skipped here due to non-application changes (per Task 1), submit with emp
 
 **If you generated zero new tests because the PR has no testable behavioral surface:**
 This applies when the diff contains ONLY changes with no observable API or UI behavior change. Examples:
-- Cosmetic/docs/style: JSDoc updates, CSS reformats, comment-only changes
+- Docs/comments only: JSDoc updates, comment-only changes
 - Dependency-only: version bumps with no API surface change
 - Dead code / unintegrated utility or component: a new helper function, utility, or UI component added to the codebase but not imported, mounted, or rendered anywhere — use this classification only after confirming the new symbol does not appear as an import or render call in any other source file; do NOT classify as dead code based solely on the diff. For UI components specifically: an unintegrated component has no DOM node in the running app and cannot be browser-tested regardless of how complex its logic is
 - Config-only: linter rules, build config, environment variable additions with no runtime behavior change
@@ -694,6 +709,8 @@ In these cases:
 - \`businessCaseAnalysis\` must be a one-sentence summary of what the PR actually does (do NOT leave it blank)
 - \`additionalRecommendations\` must be \`[]\` — do NOT recommend tests for a no-surface PR
 
+**This zero-test path does NOT apply when the requirement check found a \`requirement_conflict\`.** A requirement the PR description states and the diff did not implement is testable surface: report the conflict in \`issuesFound\` at severity \`high\` or above, and carry either the failing \`requirement_conflict\` test in \`newTestsCreated\` or its VERIFY-style entry in \`additionalRecommendations\`. Abstaining there hands the author back their own code as though it were the requirement.
+
 ${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.
@@ -703,7 +720,7 @@ ${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.
+- **additionalRecommendations**: AT MOST ${maxRecommendations} minus the number of budget-counting tests in \`newTestsCreated\` — an unused generate slot becomes a recommendation slot. The one optional discovered-scenario test does not count against the budget, so it does not reduce this allowance either.
   - 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, modularizeViaGenerationResult: UI_UTILS_REUSE })}`;

package/build/recommendation/budgeters/diversityBalancedBudgeter.js

@@ -27,16 +27,50 @@ function floorBalancedPick(items, count) {
             typesOrder.push(t);
         }
     }
-    const maxProtected = Math.max(0, count - (typesOrder.length - 1));
+    // Two passes, because "protected" is broader than "is a caught bug".
+    //
+    // A `bug_caught` candidate may take a type-floor slot: a caught bug is the
+    // strongest thing a run produces, and it outranks type spread. Every OTHER
+    // protected candidate — anything else CRITICAL, and attack-surface
+    // security_boundary items — still yields to the floor, which is what stops
+    // the SKYR-3879 skew where three CRITICAL integration candidates took all
+    // three slots and no contract test was generated.
+    //
+    // The second pass replaces `maxProtected = count - (typesOrder.length - 1)`,
+    // a static cap computed from the whole pool. It reserved a slot for every
+    // other type whether or not the picks already covered it, so at the default
+    // budget of 3 with three types present it evaluated to 1. Counting the types
+    // still uncovered keeps the same floor and drops the arithmetic that made a
+    // second finding unreachable.
+    // The same bound the prompt states (`maxGen - 1`, and the whole budget only
+    // at a budget of 1). Without it the first pass took every caught bug up to
+    // `count`, which put the SKYR-3879 skew back: at the default budget of 3, two
+    // same-type bugs left no slot for the type floor, and a measured 9-20% of
+    // backend-only pools lost a test type. It also evicted attack-surface
+    // security_boundary items the prompt in this same branch says to preserve
+    // while any non-bug slot remains.
+    const bugSlots = count <= 1 ? count : count - 1;
     const selected = [];
+    const deferred = [];
     const pool = [];
-    let protectedTaken = 0;
+    let bugsTaken = 0;
     for (const it of items) {
+        if (it.scenario?.category === "bug_caught" && bugsTaken < bugSlots && selected.length < count) {
+            selected.push(it);
+            bugsTaken++;
+        }
+        else {
+            deferred.push(it);
+        }
+    }
+    const takenTypes = new Set(selected.map(typeOf));
+    for (const it of deferred) {
+        const stillUncovered = typesOrder.filter((t) => !takenTypes.has(t) && t !== typeOf(it)).length;
         if (isProtectedCandidate(it.priority, it.scenario) &&
-            protectedTaken < maxProtected &&
-            selected.length < count) {
+            selected.length < count &&
+            count - (selected.length + 1) >= stillUncovered) {
             selected.push(it);
-            protectedTaken++;
+            takenTypes.add(typeOf(it));
         }
         else {
             pool.push(it);

package/build/recommendation/budgeters/shared.d.ts

@@ -1,13 +1,26 @@
 import { Candidate, BudgetContext, SelectionResult } from "../../types/Recommendation.js";
 /**
- * Backend GENERATE slot count:
- *  - UI-only PR: 0 (all slots are UI placeholders)
- *  - Mixed PR:   maxGenerate - 1 (last slot reserved for a UI placeholder)
- *  - Backend-only PR: maxGenerate
+ * What each PR class GUARANTEES in GENERATE (SKYR-4275). These are floors, not
+ * quotas: the slots above them are open to either kind, decided by `pick`.
+ * An open slot goes to whichever candidate `pick` chooses on rank, so a backend
+ * candidate takes one when it outranks the UI candidates, not merely because it
+ * exists. Measured against main on random mixed pools at `maxGenerate` 5 with no
+ * caught bugs: 35% get fewer backend tests than main did, average 3.53 to 3.24.
+ *
+ * Backend-only floors nothing on purpose: of 86 backend-only diffs in the eval
+ * corpus, ZERO generated a UI test, so a floor there would guarantee what
+ * already happens every time.
+ *
+ * At one slot there is no room for a floor plus an open slot, so each class
+ * keeps that slot for its own kind.
+ *
+ * The floors always sum to at most `maxGenerate`, which is what lets
+ * `applyFloors` satisfy both without one starving the other.
  */
-export declare function backendGenerateCount(ctx: BudgetContext): number;
-/** UI placeholder slots the render layer fills (UI-only → all; mixed → one). */
-export declare function reservedUISlots(ctx: BudgetContext): number;
+export declare function generateFloors(ctx: BudgetContext): {
+    ui: number;
+    backend: number;
+};
 /**
  * Shared budgeting pipeline. All Budgeters run the same external-dedup,
  * attack-surface prioritization, and ADDITIONAL set-difference; they differ
@@ -16,4 +29,4 @@ export declare function reservedUISlots(ctx: BudgetContext): number;
  * With `pick = roundRobinByType` this reproduces the pre-refactor selection in
  * diffExecutionPlan.ts exactly.
  */
-export declare function runBudget(ranked: Candidate[], ctx: BudgetContext, pick: (items: Candidate[], count: number) => Candidate[]): SelectionResult;
+export declare function runBudget(ranked: Candidate[], rawCtx: BudgetContext, pick: (items: Candidate[], count: number) => Candidate[]): SelectionResult;

package/build/recommendation/budgeters/shared.js

@@ -1,28 +1,76 @@
 import { TestType } from "../../types/TestTypes.js";
 import { inferScenarioType, prioritizeAttackSurfaceBundles } from "../diversity.js";
 import { externalDedupKeys, scenarioCoverageKeys, isAttackSurfaceSecurityBoundary, } from "../../prompts/test-recommendation/recommendationShared.js";
+import { isFlawTargetingCategory } from "../../types/TestRecommendation.js";
 import { logger } from "../../utils/logger.js";
 /**
- * Backend GENERATE slot count:
- *  - UI-only PR: 0 (all slots are UI placeholders)
- *  - Mixed PR:   maxGenerate - 1 (last slot reserved for a UI placeholder)
- *  - Backend-only PR: maxGenerate
+ * What each PR class GUARANTEES in GENERATE (SKYR-4275). These are floors, not
+ * quotas: the slots above them are open to either kind, decided by `pick`.
+ * An open slot goes to whichever candidate `pick` chooses on rank, so a backend
+ * candidate takes one when it outranks the UI candidates, not merely because it
+ * exists. Measured against main on random mixed pools at `maxGenerate` 5 with no
+ * caught bugs: 35% get fewer backend tests than main did, average 3.53 to 3.24.
+ *
+ * Backend-only floors nothing on purpose: of 86 backend-only diffs in the eval
+ * corpus, ZERO generated a UI test, so a floor there would guarantee what
+ * already happens every time.
+ *
+ * At one slot there is no room for a floor plus an open slot, so each class
+ * keeps that slot for its own kind.
+ *
+ * The floors always sum to at most `maxGenerate`, which is what lets
+ * `applyFloors` satisfy both without one starving the other.
  */
-export function backendGenerateCount(ctx) {
+export function generateFloors(ctx) {
+    // Number.isFinite, not Math.max: `Math.max(0, NaN)` is NaN, which compares
+    // false against 0 and would fall through to the class branches below.
+    const max = Number.isFinite(ctx.maxGenerate) ? Math.max(0, Math.floor(ctx.maxGenerate)) : 0;
+    if (max === 0)
+        return { ui: 0, backend: 0 };
     if (ctx.isUIOnlyPR)
-        return 0;
-    return ctx.hasFrontendChanges ? Math.max(0, ctx.maxGenerate - 1) : ctx.maxGenerate;
+        return { ui: max === 1 ? 1 : max - 1, backend: 0 };
+    if (ctx.hasFrontendChanges)
+        return max === 1 ? { ui: 1, backend: 0 } : { ui: 1, backend: 1 };
+    return { ui: 0, backend: 0 };
 }
-/** UI placeholder slots the render layer fills (UI-only → all; mixed → one). */
-export function reservedUISlots(ctx) {
-    if (ctx.isUIOnlyPR)
-        return ctx.maxGenerate;
-    return ctx.hasFrontendChanges && ctx.maxGenerate > 0 ? 1 : 0;
+/**
+ * Raise a chosen GENERATE set to meet the floors, by swapping rather than
+ * re-picking. `pick` runs ONCE over the whole pool, so its protected-first
+ * ordering, its one-slot-per-test-type coverage and attack-surface bundle
+ * adjacency are all settled before this runs. Picking each floor from its own
+ * slice instead would compute those guarantees per slice and collapse them —
+ * measured at 25% of mixed-PR inputs losing a test type, 8.3% losing contract
+ * coverage outright.
+ *
+ * A floor is raised only as far as the pool allows. Satisfying one floor cannot
+ * starve the other, because `generateFloors` never returns two that sum above
+ * the budget — `generateFloors.test.ts` pins that invariant.
+ */
+function applyFloors(generate, slotOrdered, floors, isUI) {
+    const isBackend = (item) => !isUI(item);
+    const result = [...generate];
+    for (const [want, wanted] of [
+        [floors.ui, isUI],
+        [floors.backend, isBackend],
+    ]) {
+        const spare = slotOrdered.filter((item) => wanted(item) && !result.includes(item));
+        let shortfall = Math.min(want, result.filter(wanted).length + spare.length) - result.filter(wanted).length;
+        // Swap from the END: `pick` returns its slots in preference order, so the
+        // last one it chose is the one this PR class needs least.
+        for (let i = result.length - 1; i >= 0 && shortfall > 0; i--) {
+            if (wanted(result[i]))
+                continue;
+            result[i] = spare.shift();
+            shortfall--;
+        }
+    }
+    return result;
 }
 /**
  * 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.
+ * `bug_caught` / `requirement_conflict` / 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
@@ -44,8 +92,8 @@ function partitionByExternalCoverage(ranked, externalCoverage) {
             uncovered.push(item);
             continue;
         }
-        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`);
+        if (isFlawTargetingCategory(item.scenario.category) || isAttackSurfaceSecurityBoundary(item.scenario)) {
+            logger.info(`External dedup: preserving "${item.scenario.scenarioName}" (${keys.join(", ")}) — protected bug/requirement-conflict/attack-surface scenario requires semantic flaw coverage`);
             uncovered.push(item);
             continue;
         }
@@ -62,36 +110,27 @@ function partitionByExternalCoverage(ranked, externalCoverage) {
  * With `pick = roundRobinByType` this reproduces the pre-refactor selection in
  * diffExecutionPlan.ts exactly.
  */
-export function runBudget(ranked, ctx, pick) {
+export function runBudget(ranked, rawCtx, pick) {
+    // SKYR-4292: maxTotal is the budget; maxGenerate is how much of it to generate.
+    // Every producer clamps upstream (getTestbotPrompt, computeScoredCandidates,
+    // buildScopeAssessmentSection), but a state file is the tool boundary and can
+    // carry maxGenerate > maxTotal — the UI-only branch then reserved maxGenerate
+    // slots and planned more items than the total. Clamp once here so every
+    // budgeter agrees with the prompt. It must stay ABOVE generateFloors(ctx):
+    // the floors are computed from the clamped budget, and moving the clamp
+    // below them would let the floors sum past maxTotal again (review on #835).
+    const ctx = { ...rawCtx, maxGenerate: Math.min(rawCtx.maxGenerate, rawCtx.maxTotal) };
     const dropped = [];
-    const backend = backendGenerateCount(ctx);
-    const uiSlots = reservedUISlots(ctx);
+    const floors = generateFloors(ctx);
     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,
-    // leaving the UI-promotion loop with nothing to promote and GENERATE short.
-    const backendSource = uiSlots > 0
-        ? slotOrdered.filter((item) => inferScenarioType(item.scenario) !== TestType.UI)
-        : slotOrdered;
-    const backendGenerate = pick(backendSource, Math.min(backend, backendSource.length));
-    // Fill the reserved UI slots the `pick` step leaves empty: the backend count
-    // is 0 on a UI-only PR (and maxGenerate-1 on a mixed PR), so UI candidates are
-    // never chosen above even though reservedUISlots budgets for them. Promote the
-    // top-ranked UI candidates not already chosen, up to the reserved count, so
-    // GENERATE is complete instead of an empty list plus a dropped count.
-    const chosen = new Set(backendGenerate);
-    const uiGenerate = [];
-    for (const item of slotOrdered) {
-        if (uiGenerate.length >= uiSlots)
-            break;
-        if (chosen.has(item) || inferScenarioType(item.scenario) !== TestType.UI)
-            continue;
-        uiGenerate.push(item);
-        chosen.add(item);
-    }
-    const generate = [...backendGenerate, ...uiGenerate];
+    const isUICandidate = (item) => inferScenarioType(item.scenario) === TestType.UI;
+    // ONE pick over the whole pool — the shape the backend pick always had — so
+    // `pick` decides protected-first order, per-type coverage and bundle adjacency
+    // exactly once. `applyFloors` then corrects only the UI/backend mix.
+    const budget = Number.isFinite(ctx.maxGenerate) ? Math.max(0, Math.floor(ctx.maxGenerate)) : 0;
+    const picked = pick(slotOrdered, Math.min(budget, slotOrdered.length));
+    const generate = applyFloors(picked, slotOrdered, floors, isUICandidate);
     // 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
@@ -100,24 +139,50 @@ export function runBudget(ranked, ctx, pick) {
     // 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;
+    // Three conditions keep the reserve shut where recommending nothing is right.
+    // A UI-only PR is left alone. A zero budget is an explicit abstention, so it
+    // must not be talked out of recommending nothing. 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.
+    //
+    // One pick over the whole pool leaves no "backend half" to count, so the
+    // emptiness test reproduces what that half used to mean per class. On a mixed
+    // PR the UI slot must not read as backend coverage, or a covered backend
+    // candidate vanishes behind it. On a backend-only PR the pick always drew from
+    // the whole pool, so a non-empty GENERATE closed the reserve even when every
+    // item was UI — keep that, or an all-UI pool opens a reserve it never opened.
+    const backendChosen = generate.filter((item) => !isUICandidate(item));
+    const backendHalfEmpty = ctx.hasFrontendChanges
+        ? backendChosen.length === 0
+        : generate.length === 0;
+    // One per-class behaviour DID change here, deliberately. On a mixed PR at a
+    // budget of 1 the old gate also required `backendGenerateCount > 0`, which is
+    // 0 for that class, so a covered backend candidate was dropped outright. The
+    // reserve exists because dropping removes a candidate from the
+    // RECOMMENDATIONS too (SKYR-4024), and a budget of 1 is the case where that
+    // costs most — there is no second slot to find it later. It is now
+    // recommended instead of dropped. `reserveOpensForMixedPRAtBudgetOne` in
+    // shared.test.ts pins it, so a future change has to mean it.
+    const spendReserve = backendHalfEmpty &&
+        !ctx.isUIOnlyPR &&
+        budget > 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";
+        const reason = !backendHalfEmpty
+            ? `the backend half of GENERATE is filled (${backendChosen.length || generate.length})`
+            : ctx.isUIOnlyPR
+                ? "a UI-only PR keeps its slots for UI"
+                : budget === 0
+                    ? "the budget is zero"
+                    : "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({
@@ -142,6 +207,7 @@ export function runBudget(ranked, ctx, pick) {
     const additionalSource = spendReserve
         ? [...slotOrdered, ...prioritizeAttackSurfaceBundles(covered.map((c) => c.item))]
         : slotOrdered;
+    const chosen = new Set(generate);
     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)));
@@ -149,6 +215,18 @@ export function runBudget(ranked, ctx, pick) {
         const keys = scenarioCoverageKeys(item.scenario);
         if (keys.length === 0 || !keys.every((key) => generatedCoverage.has(key)))
             return true;
+        // Same exemption the EXTERNAL dedup above already makes, for the same
+        // reason: a flaw-targeting scenario (a caught bug, or a requirement the code
+        // contradicts) or an attack-surface boundary asserts a specific defect, and
+        // sharing an endpoint with a GENERATE item is not evidence that the defect is
+        // covered. Without it a PR with two defects in one handler had its second one
+        // deleted here — the first took a GENERATE slot, and the key is method +
+        // resource + test type + interaction + status, which two tests on one
+        // endpoint share.
+        if (isFlawTargetingCategory(item.scenario.category) || isAttackSurfaceSecurityBoundary(item.scenario)) {
+            logger.info(`GENERATE dedup: preserving "${item.scenario.scenarioName}" (${keys.join(", ")}) — protected bug/requirement-conflict/attack-surface scenario requires semantic flaw coverage`);
+            return true;
+        }
         dropped.push({
             candidateId: item.candidateId,
             reason: `covered by GENERATE (${keys.join(", ")})`,
@@ -164,5 +242,5 @@ export function runBudget(ranked, ctx, pick) {
     }
     // Budgeting itself produces no demotions; the register-plan selection stage
     // (planRanker.selectPlan) fills this channel from discriminator verification.
-    return { generate, additional, reservedUISlots: uiSlots, demotions: [], dropped };
+    return { generate, additional, reservedUISlots: floors.ui, demotions: [], dropped };
 }

package/build/recommendation/planRanker.d.ts

@@ -4,8 +4,10 @@ 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 (bug_caught only —
-     * new_endpoint is MEDIUM, not carved out). Exposed so phase 2 can tune the carve-out
+     * Defaults to the `CATEGORY_PRIORITY === "CRITICAL"` categories (bug_caught and
+     * requirement_conflict — new_endpoint is MEDIUM, not carved out). The two CRITICAL
+     * categories are carved out independently, so a requirement conflict never competes
+     * with a code-review bug for one slot. Exposed so phase 2 can tune the carve-out
      * WITHOUT reintroducing the agent's priority tag as a ranking input.
      */
     carveOutCategories?: ScenarioCategory[];
@@ -32,7 +34,7 @@ export interface SelectPlanContext extends BudgetContext {
  * independent of input order (the final tiebreak is the stable `candidateId`).
  *
  * Ordering (highest first):
- *   1. Carve-out — CRITICAL-category scenarios (bug_caught), preserving the
+ *   1. Carve-out — CRITICAL-category scenarios (bug_caught, requirement_conflict), preserving the
  *      protected-first convention of `roundRobinByType` /
  *      `prioritizeAttackSurfaceBundles`.
  *   2. Verified discriminators — candidates whose declared discriminator survived

package/build/recommendation/planRanker.js

@@ -14,7 +14,7 @@ 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 — CRITICAL-category scenarios (bug_caught), preserving the
+ *   1. Carve-out — CRITICAL-category scenarios (bug_caught, requirement_conflict), preserving the
  *      protected-first convention of `roundRobinByType` /
  *      `prioritizeAttackSurfaceBundles`.
  *   2. Verified discriminators — candidates whose declared discriminator survived

package/build/tools/submitReportTool.js

@@ -13,6 +13,7 @@ import { toolError, testFileMatches } from "../utils/utils.js";
 import { matchesApprovedPlan } from "../utils/planMatchKeys.js";
 import { isTestbotEnabled } from "../utils/featureFlags.js";
 import { findInvalidSourceCitations, findUnchangedFileClaims, listChangedFiles, listChangedFilesAcross, listChangedFilesAbs, } from "../utils/reportVerification.js";
+import { isPlanOnlyMode } from "../utils/planOnlyMode.js";
 import { getReportLanguage, isEnforcedReportLanguage, findLanguageViolations, findLanguageNearMisses, reportLanguageDisplayName, } from "../utils/reportLanguage.js";
 import { canonicalTestPath, findAssertionRecordByFileName, rederiveAssertionOutcome, } from "./code-refactor/assertion-state.js";
 import { rederiveReuseOutcome, reuseChainSkipped, samePath, } from "./code-refactor/reuse-state.js";
@@ -343,7 +344,8 @@ const issueFoundSchema = z
         .optional()
         .describe("Issue severity. critical = feature broken/unusable (e.g. page doesn't load, data corruption). " +
         "high = incorrect behavior (e.g. wrong calculation, stale data returned). " +
-        "medium = minor functional gap. low = cosmetic or informational."),
+        "medium = minor functional gap. low = cosmetic or informational. " +
+        "Floor: a requirement conflict — the PR title/description (or a requirements file it references) states a requirement the implemented behavior contradicts — is 'high' or 'critical', never 'medium' or below."),
     category: z
         .nativeEnum(IssueFoundCategory)
         .describe("Issue classification. bug = a product/code defect, e.g. found by a test or in the diff. " +
@@ -1109,6 +1111,9 @@ export function registerSubmitReportTool(server) {
                         newTests: dedupedNewTests,
                         verdicts: stateData.maintenanceVerdicts ?? [],
                         primaryRepository: fullState?.metadata?.repository,
+                        // SKYR-4250: captured at prompt-render time, since planOnly is a
+                        // prompt-only argument (mirrors the SKYR-4185 language capture).
+                        planOnly: isPlanOnlyMode(),
                     });
                     if (unbacked.length > 0) {
                         // Offer the attribution-correction path explicitly and show what DID change:

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

@@ -6,7 +6,7 @@ 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"]>;
+    category: z.ZodEnum<["new_endpoint", "bug_caught", "requirement_conflict", "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<{
@@ -124,7 +124,7 @@ declare const registerCandidateSchema: z.ZodObject<{
     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";
+    category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
     steps: {
         path: string;
         method: HttpMethod;
@@ -160,7 +160,7 @@ declare const registerCandidateSchema: z.ZodObject<{
     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";
+    category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
     steps: {
         path: string;
         method: HttpMethod;