@skyramp/mcp 0.3.0-rc.1 → 0.3.0

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

@@ -15,11 +15,13 @@ export function buildFileRenameStrategy() {
 }
 /** Strategy string for in-place UPDATE edits. */
 export function buildUpdateStrategy() {
-    return `For each file in update_context, apply the changes described in context. Preserve all existing test logic — only add or adjust what is described in context.
+    return `Apply each file in update_context yourself with the Edit tool, using its current_content and the changes described in context. Preserve all existing test logic — only add or adjust what context describes.
+
+When a file provides edit_sites, apply each site directly using its anchor as the Edit target — do not re-grep or re-page the file to relocate the sites; they were already found for you.
 
 UPDATE is an in-place edit to the existing baseline file — do not create a new test file to cover the same page or component.
 
-After applying all edits, call skyramp_enhance_assertions with each updated file path.`;
+After editing, re-read each file to confirm the change landed, then call skyramp_enhance_assertions with each updated file path.`;
 }
 /** Strategy string for REGENERATE — call generation tool to overwrite the file. */
 export function buildRegenerateStrategy() {

package/build/prompts/test-maintenance/drift-analysis-prompt.d.ts

@@ -4,6 +4,15 @@ export type UiDriftParams = {
     }>;
     changedFrontendFiles: string[];
     blueprintCaptured?: boolean;
+    /**
+     * Changed frontend files imported by 2+ production files, with their importer
+     * lists (server-computed). Drives the shared-component drift rule: a test may not
+     * be assigned IGNORE for one of these files until every importer has been read.
+     */
+    sharedComponents?: Array<{
+        file: string;
+        importers: string[];
+    }>;
 };
 /**
  * Build the drift analysis prompt.

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

@@ -61,14 +61,15 @@ export function buildDriftAnalysisPrompt(stateFile, apiTests, ui, repoPaths) {
 ${ui.changedFrontendFiles.length > 0
             ? ui.changedFrontendFiles.map(f => `- ${f}`).join("\n")
             : "(none)"}
-
-**Tests to Assess:**
-${ui.tests.length > 0
-            ? ui.tests.map(t => `- ${t.testFile}`).join("\n")
-            : "(none)"}
-
+${ui.sharedComponents && ui.sharedComponents.length > 0
+            ? `
+**Shared frontend components (imported by 2+ production files — cross-consumer blast radius):**
+${ui.sharedComponents.map(c => `- ${c.file} — ${c.importers.length} importer(s): ${c.importers.join(", ")}`).join("\n")}
+For any test whose changed target appears here, you MUST NOT assign IGNORE, and may assign UPDATE only after reading every listed importer (see "Component behavior changes").
+`
+            : ""}
 **Instructions:**
-For each test above, read it to determine its type, then apply the scope gate from the decision tree. Assign the appropriate action (DELETE, REGENERATE, UPDATE, VERIFY, IGNORE).
+For each test in \`<tests_to_assess>\`, read it to determine its type, then apply the scope gate from the decision tree. Assign the appropriate action (DELETE, REGENERATE, UPDATE, VERIFY, IGNORE).
 </ui_analysis_context>
 
 `;

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

@@ -3,7 +3,7 @@
  * mirroring the recommendationSections.ts pattern.
  */
 import { AUTH_MIDDLEWARE_PATTERNS_STR } from "../../utils/workspaceAuth.js";
-import { buildApiAssignAction } from "./driftAnalysisShared.js";
+import { buildApiAssignAction, EMPTY_TEST_LIST_PLACEHOLDER, NO_PRELOADED_TESTS_NOTE } from "./driftAnalysisShared.js";
 // TODO: Replace the open-ended diff-line categories below with a two-tier structure:
 // Tier 1 — mechanical patterns (specific token + file-path criteria, zero judgment needed).
 // Tier 2 — residual open-ended scan for anything observable not covered by tier 1.
@@ -173,6 +173,7 @@ Diff signals and actions:
 }
 export function buildCheckAssignAction() {
     return buildApiAssignAction(`- If the Additive Fields check flagged a new field with output layer signal confirmed in the diff → action is UPDATE. If the Additive Fields check returned VERIFY (model-only signal, no output layer change) → action remains VERIFY.
+- **Request/response contract change** (a field made required, a type change, or a removal): the changed schema/DTO line is the quotable trigger. You MUST read the body of every candidate test that could reach the changed endpoint before assigning it an action — a speculative "may/uncertain" rationale on a file you have not read is not allowed. After reading, assign UPDATE if the test sends a request the new contract now rejects (e.g. it POSTs without the now-required field — it need not name the changed symbol); assign IGNORE only with a concrete reason quoted from the file (it already supplies the field, or never calls the endpoint). Use VERIFY only when the test's behavior genuinely cannot be determined from its own body. When a single UPDATE file needs the same change at more than a couple of places, record each one in \`editSites\` (line + a verbatim anchor copied from that line) as you read it — this list is handed to the apply step so it edits each site directly instead of re-scanning the file.
 - **Scope gate:** If the changed code is clearly not reachable through the service or base URL this test targets, assign IGNORE.
 - **When uncertain, use VERIFY not IGNORE:** If the diff touches a model or migration and this test's endpoint reads from that model, assign VERIFY — you cannot confirm from the diff alone whether the field is exposed.`);
 }
@@ -200,10 +201,8 @@ export function buildDriftOutputChecklist(stateFile, existingTests) {
             const label = (t.source ?? "skyramp") === "external" ? " [external]" : "";
             return `- ${t.testFile}${label}`;
         }).join("\n")
-        : "- (none)";
-    const noTestsNote = !hasTests
-        ? `\nNo existing tests were found. Call \`skyramp_actions\` with \`recommendations: []\` and explain in your report why no maintenance was needed (e.g. "no existing tests cover the changed endpoints" or "PR adds a new endpoint with no prior coverage").\n`
-        : "";
+        : EMPTY_TEST_LIST_PLACEHOLDER;
+    const noTestsNote = !hasTests ? NO_PRELOADED_TESTS_NOTE : "";
     const existingTestSection = `**Existing tests (${existingTests?.length ?? 0} total) — assess ALL of the following:**
 ${testList}
 ${noTestsNote}

package/build/prompts/test-maintenance/driftAnalysisShared.d.ts

@@ -5,6 +5,17 @@
  * covering aliases, indirect renders, and shared hooks the diff doesn't mention.
  */
 export declare function buildSymbolDiscoveryStep(hasTests: boolean, repoPaths?: string[]): string;
+/** Placeholder shown in place of an empty pre-loaded test list — the agent must still
+ *  discover tests via the shared Symbol discovery step before concluding none apply. */
+export declare const EMPTY_TEST_LIST_PLACEHOLDER = "- (none pre-loaded \u2014 discover them via the Symbol discovery step above before assessing)";
+/**
+ * Shared note for the drift output checklist when no tests were pre-loaded. An empty
+ * pre-load is not evidence that no tests exist — in PR mode external (user-written) tests
+ * are discovered by the agent via the Symbol discovery step, not pre-loaded. Defers the
+ * empty-recommendations bail to genuine grep discovery finding nothing. Used by both the
+ * API and UI checklists so the wording stays in one place.
+ */
+export declare const NO_PRELOADED_TESTS_NOTE = "\nNo tests were pre-loaded into the list above. This does NOT mean none exist \u2014 external (user-written) tests are discovered by you via the Symbol discovery step, not pre-loaded. First complete that grep, then assess every test file it surfaces using the actions below. Only call `skyramp_actions` with `recommendations: []` if that discovery genuinely finds no test exercising the changed code \u2014 and in that case state in your report exactly what you grepped for (endpoints, function/class names, changed type names).\n";
 /** One source of truth for the recommendations[] contract passed to skyramp_actions. */
 export declare const RECOMMENDATIONS_INSTRUCTION = "Pass VERIFY, UPDATE, REGENERATE, and DELETE entries to `recommendations[]`. Omit IGNORE.";
 export declare function buildSharedExternalTestPolicy(): string;

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

@@ -5,23 +5,39 @@
  * covering aliases, indirect renders, and shared hooks the diff doesn't mention.
  */
 export function buildSymbolDiscoveryStep(hasTests, repoPaths) {
-    if (!hasTests)
-        return "";
     const repoList = repoPaths && repoPaths.length > 1
         ? repoPaths.map(p => `\`${p}\``).join(", ")
         : repoPaths?.[0] ? `\`${repoPaths[0]}\`` : "the repository";
-    return `**Symbol discovery (before assessing):** Find additional test files that reference changed code:
+    // When no tests were pre-loaded this step is REQUIRED, not optional: in PR mode external
+    // (user-written) tests are discovered by the agent, not pre-loaded, so an empty list means
+    // "not yet discovered", not "none exist". Suppressing this step in that case is the bug that
+    // let schema-only diffs silently maintain nothing (SKYR-3924).
+    const intro = hasTests
+        ? `**Symbol discovery (before assessing):** Find *additional* test files that reference changed code beyond those already listed:`
+        : `**Symbol discovery (REQUIRED — do this before concluding anything):** No tests were pre-loaded. That does NOT mean none exist — external (user-written) tests are discovered here, not pre-loaded. Find the test files that exercise the changed code:`;
+    return `${intro}
 
 1. **Hunk context:** Extract function and class names from \`@@\` context lines and changed endpoint URL path segments. Grep ${repoList} for each.
-2. **Full file exports:** For each changed source file in the diff, read it and extract all exported symbols (component names, function names, hooks, class names). Grep ${repoList} for each (case-insensitive). This catches tests using aliased imports, indirect renders, or shared hooks not visible in the diff hunk.
+2. **Full file exports:** For each changed source file in the diff, read it and extract all exported symbols (component names, function names, hooks, class names) — and for schema/model/DTO files, the changed type/schema names. Grep ${repoList} for each (case-insensitive). This catches tests using aliased imports, indirect renders, shared hooks, or a changed type referenced by name that the diff hunk doesn't mention.
 
-Add any matched test files not already in your assessment, and include them in \`recommendations[]\`.`;
+Add every matched test file to your assessment below${hasTests ? " (if not already listed)" : ""}, and include the resulting VERIFY/UPDATE/REGENERATE/DELETE entries in \`recommendations[]\`.`;
 }
+/** Placeholder shown in place of an empty pre-loaded test list — the agent must still
+ *  discover tests via the shared Symbol discovery step before concluding none apply. */
+export const EMPTY_TEST_LIST_PLACEHOLDER = "- (none pre-loaded — discover them via the Symbol discovery step above before assessing)";
+/**
+ * Shared note for the drift output checklist when no tests were pre-loaded. An empty
+ * pre-load is not evidence that no tests exist — in PR mode external (user-written) tests
+ * are discovered by the agent via the Symbol discovery step, not pre-loaded. Defers the
+ * empty-recommendations bail to genuine grep discovery finding nothing. Used by both the
+ * API and UI checklists so the wording stays in one place.
+ */
+export const NO_PRELOADED_TESTS_NOTE = `\nNo tests were pre-loaded into the list above. This does NOT mean none exist — external (user-written) tests are discovered by you via the Symbol discovery step, not pre-loaded. First complete that grep, then assess every test file it surfaces using the actions below. Only call \`skyramp_actions\` with \`recommendations: []\` if that discovery genuinely finds no test exercising the changed code — and in that case state in your report exactly what you grepped for (endpoints, function/class names, changed type names).\n`;
 /** One source of truth for the recommendations[] contract passed to skyramp_actions. */
 export const RECOMMENDATIONS_INSTRUCTION = `Pass VERIFY, UPDATE, REGENERATE, and DELETE entries to \`recommendations[]\`. Omit IGNORE.`;
 export function buildSharedExternalTestPolicy() {
     return `**For user-written (external) tests** marked \`[external]\` in the test list:
-- UPDATE is permitted — pass the exact file that needs editing as \`testFile\`. This can be the test file itself, a snapshot file, a page object, or a fixture. \`skyramp_actions\` will edit that file using \`updateInstructions\`; application source files are automatically rejected.
+- UPDATE is permitted — pass the exact file that needs editing as \`testFile\`. This can be the test file itself, a snapshot file, a page object, or a fixture. \`skyramp_actions\` returns edit instructions for that file; application source files are automatically rejected.
 - REGENERATE and DELETE: assign these actions when the evidence clearly warrants them (page gone → DELETE, component structure fundamentally changed → REGENERATE). \`skyramp_actions\` handles execution restrictions at apply time — assign the action that the evidence supports. Leave user-authored test files unchanged; edits go only through \`skyramp_actions\` with explicit \`updateInstructions\`. VERIFY means "uncertain, need more context" — assign DELETE or REGENERATE when you have confirmed the failure, and VERIFY only when you genuinely cannot determine impact without more information.`;
 }
 /** Shared boilerplate: VERIFY rule, pre-commit structure, and external policy. */

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

@@ -7,7 +7,7 @@
  * (RTL/Flutter widget/vue-test-utils/angular-testbed) go through the same gate.
  * Component tests always use source-only analysis regardless of blueprintCaptured.
  */
-import { buildUiAssignAction } from "./driftAnalysisShared.js";
+import { buildUiAssignAction, EMPTY_TEST_LIST_PLACEHOLDER, NO_PRELOADED_TESTS_NOTE } from "./driftAnalysisShared.js";
 /**
  * Build the UI Action Decision Tree section.
  * This is the main entry point for UI drift analysis.
@@ -20,10 +20,12 @@ For each UI test listed in the \`<ui_analysis_context>\` above, assess whether t
 - Route paths (URL changes)
 - Component behavior (state changes, visibility conditions)
 
-**Scope gate:** Read each test file to determine its type, then apply the correct gate:
-- **Browser test** (has \`page.goto()\`, \`cy.visit()\`, \`driver.get()\`): check that the test navigates to a page the changed frontend file serves. Infer from the changed file's directory path (e.g. \`modules/bookings/\` → bookings page) or explicit route-path diff signals.
-- **Component/widget test** (has \`render(<…>)\`, \`mount()\`, \`shallowMount()\`): check if it directly renders/mounts a changed component. If none of the rendered components match a changed file, the test is unaffected.
-If neither condition applies, assign **IGNORE** and skip remaining checks.
+**Scope gate:** Read each test file to determine its type. A test is in scope if the diff's changed file reaches it, directly or transitively:
+- **Browser test** (has \`page.goto()\`, \`cy.visit()\`, \`driver.get()\`): via a page/route it navigates to — the file *is* that page/route (infer from its directory path, e.g. \`modules/bookings/\` → bookings page, or from route-path diff signals), or a component that page renders.
+- **Component/widget test** (has \`render(<…>)\`, \`mount()\`, \`shallowMount()\`): via the component it mounts.
+- **Shared / design-system component:** the changed file is a shared component (e.g. a \`design-system\`/\`ui\` package, or one imported by many consumers), so it reaches every consumer — use symbol discovery to find the consumer tests and treat each as in scope. A different package or directory does not make a test unrelated when it consumes the changed component.
+
+Matching none does **not** mean IGNORE — first run the selector safety net: match the class / \`data-testid\` / \`aria-*\` literals the diff changed or added against the test body and any page object it imports. A match puts the test in scope. Assign **IGNORE** only when a test matches none of the conditions **and** the selector safety net finds nothing. Assess every in-scope test under the rules below.
 
 
 **Severity order (highest first): DELETE > REGENERATE > UPDATE > VERIFY > IGNORE**
@@ -37,24 +39,12 @@ If neither condition applies, assign **IGNORE** and skip remaining checks.
 
 Build a detection list first: for each matched diff line, write one line: \`{pattern type} — "{diff line}" — affects {route/component}\`.
 
-**Action definitions:**
-- **DELETE**: The test targets a page/route that no longer exists, or all selectors the test uses have been removed and there's no migration path.
-- **REGENERATE**: The interaction model changed so fundamentally that the test flow itself is broken — not just selector values, but the sequence of actions (e.g. a form replaced by a modal, buttons replaced by a dropdown, a multi-step flow collapsed into one). There is no rename mapping; re-recording from scratch is the only viable approach.
-- **UPDATE**: Specific selectors need updating, assertions need adjustment, or new elements were added to a page the test already exercises. Always an in-place edit to the existing file — do not generate a new spec to cover the same page or component.
-- **VERIFY**: The test may be impacted but you cannot confirm breakage without reading more context (e.g. selectors are hidden in a page object file you have not read, or the component is imported indirectly).
-- **IGNORE**: The changed code cannot reach this test's routes or rendered components — the test covers unchanged functionality. If you cannot point to a diff line that affects this test's routes, selectors, or rendered components, the action is IGNORE or VERIFY, not UPDATE.
-
-**Rules:**
-- DELETE when all routes the test covers were removed or all critical selectors are gone.
-- REGENERATE when the interaction model changed fundamentally — the test's sequence of actions is broken with no migration path (e.g. a click-to-update button replaced by an auto-updating stepper; a remove button moved into a dropdown). The number of broken selectors alone does not determine REGENERATE; what matters is whether the flow can still be expressed with targeted edits.
-- UPDATE when specific selectors changed (renamed classes, moved data-testid) but the test flow remains valid, or when new elements were added to a page the test already covers — append the assertion to the existing file.
-- VERIFY when a page object or indirect import hides the affected selectors — read the imported file before escalating to UPDATE.
-- IGNORE when the diff touches unrelated frontend code (different routes, different components).
-
-**Additional rule for component/widget tests** ([rtl], [flutter-widget], [vue-test-utils], [angular-testbed]):
-- Rule #7: Component deleted — source file removed with no re-export → **DELETE** (report-only for external tests). These tests have no navigation; the rendered component is their only target.
-- Skip the route-existence check (step 1.1) for component/widget tests — they have no \`page.goto()\` or equivalent navigation calls.
-- Primary matching signal: read the test to check if it directly renders a changed component — if so, it is impacted.
+**Rules (assign exactly one action per test; severity order above):**
+- **DELETE** when the test's target is gone: all routes/pages it covers no longer exist; all critical selectors were removed with no migration path; or, for a component/widget test, the component it renders was deleted (source removed with no re-export; report-only for external tests).
+- **REGENERATE** when the interaction model changed so fundamentally that the test's action sequence is broken with no migration path: the flow itself changed, not just selector values (e.g. a form replaced by a modal, buttons replaced by a dropdown, a click-to-update button replaced by an auto-updating stepper). Re-recording from scratch is the only viable approach. Broken-selector count alone does not decide REGENERATE; if the flow still works with targeted edits, it is UPDATE.
+- **UPDATE** when the test's flow still holds but something it relies on shifted on a page or component it exercises: a selector (className, data-testid, aria-*) was renamed or moved, a new selector was added that the test should adopt or assert (including a dynamic class like \`+ \`btn--\${variant}\`\`), or an assertion needs adjusting. Fix it in place in the existing file, never a new spec for the same page or component. An added selector is still drift, not a no-op. Read the test/POM to confirm the component is targeted and prefer UPDATE; fall back to VERIFY only when reading leaves impact undetermined.
+- **VERIFY** when the test may be impacted but you cannot confirm breakage without reading more context (e.g. the affected selectors live in a page object or indirect import you have not read). Read that file before escalating to UPDATE.
+- **IGNORE** when the changed code cannot reach this test's routes or rendered components (the diff touches different routes or components). If you cannot point to a diff line affecting this test's routes, selectors, or rendered components, the action is IGNORE or VERIFY, not UPDATE.
 </ui_decision_rules>`;
 }
 /**
@@ -89,6 +79,7 @@ Diff signals to look for:
 - Tailwind changes: \`- tw="p-4"\` / \`+ tw="p-6"\`
 - Test ID changes: \`- data-testid="old-id"\` / \`+ data-testid="new-id"\`
 - ARIA changes: \`- aria-label="Old"\` / \`+ aria-label="New"\`
+- Selector ADDED with no paired removal: \`+ data-testid="new-id"\`, \`+ className="new-class"\`, or a dynamically-composed class \`+ \`btn--\${variant}\`\`
 - Component restructuring: \`+ <NewWrapper>\` around existing content, \`- <OldWrapper>\`
 
 **When blueprints are available** (\`blueprintCaptured=true\`): compare extracted selectors against \`browser_blueprint_diff\` for the affected page — elements absent from the new blueprint signal breakage.
@@ -96,9 +87,10 @@ Diff signals to look for:
 **When blueprints are not available** (\`blueprintCaptured=false\`): use diff signals only. If a selector the test uses matches a value renamed or removed in the diff, assign UPDATE. If you cannot confirm breakage from the diff alone (e.g. selectors live in a page object you have not read), assign VERIFY rather than guessing.
 
 Actions:
-- Selectors confirmed unchanged (diff or blueprint) → **IGNORE** (no drift)
+- Selectors confirmed unchanged (diff or blueprint) → **IGNORE** (no drift). "Absent from the diff" is NOT "confirmed unchanged": a \`data-testid\` or selector can MOVE to a different element while keeping its value, producing no \`-\`/\`+\` literal to match. If the test renders or navigates a changed component but no selector literal appears in the diff, the selector may have moved — assign **VERIFY** (confirm via blueprint or by reading the changed component), not IGNORE.
 - Selectors renamed (class, testid, aria-label changed) → **UPDATE** (patch selector values)
 - Selectors removed with no confirmed replacement → **UPDATE** (find replacement; use blueprint if available, diff otherwise)
+- Selector ADDED with no paired removal (new class, testid, or \`+ \`btn--\${variant}\`\`) → **UPDATE** (adopt the new selector or assert the new variant)
 - Major restructuring (most selectors gone) → **REGENERATE** (page structure fundamentally changed)
 - All selectors gone, no replacement elements → **DELETE** (page no longer testable)
 - Cannot confirm without reading page object or additional files → **VERIFY**
@@ -151,7 +143,7 @@ Actions:
 - New conditional rendering → **UPDATE** (update assertions to match new conditions)
 - Auth behavior changed → **UPDATE** (adjust login flow in test)
 - Async delays added → **UPDATE** (add appropriate waits/timeouts)
-- Shared component changed (used across multiple pages, dialogs, or layouts): if the test covers only one consumer and you have not read all other consumers, assign **VERIFY** — the blast radius across other consumers is indeterminate. Only assign UPDATE if you have confirmed the change is isolated to this test's consumer.`;
+- Shared component changed: if the changed file appears under **Shared frontend components** in \`<ui_analysis_context>\` (imported by 2+ production files), the importer list there is authoritative — do NOT rely on your own count. You may NOT assign **IGNORE** for such a file. Assign **UPDATE** only after reading every importer listed there and confirming the change is isolated to this test's consumer; until you have read all of them, assign **VERIFY** — the blast radius across the other consumers is indeterminate.`;
 }
 /**
  * Assign the final UI drift action.
@@ -170,25 +162,25 @@ export function buildUiDriftOutputChecklist(stateFile, tests) {
     const hasTests = (tests?.length ?? 0) > 0;
     const testList = hasTests
         ? tests.map(t => `- ${t.testFile}${t.source === "external" ? " [external]" : ""}`).join("\n")
-        : "- (none)";
-    const noTestsNote = !hasTests
-        ? `\nNo existing tests were found. Call \`skyramp_actions\` with \`recommendations: []\`.\n`
-        : "";
+        : EMPTY_TEST_LIST_PLACEHOLDER;
+    const noTestsNote = !hasTests ? NO_PRELOADED_TESTS_NOTE : "";
     const existingTestSection = `**Tests (${tests?.length ?? 0} total) — assess ALL of the following:**
+<tests_to_assess>
 ${testList}
+</tests_to_assess>
 ${noTestsNote}
 
 **Execution policy:**
 - Skyramp-generated tests: UPDATE/REGENERATE/DELETE applied automatically by \`skyramp_actions\`. Run via \`skyramp_execute_test\`.
 - External tests (Playwright, Cypress, RTL, etc.): \`skyramp_actions\` applies UPDATE edits to \`testFile\` — which can be the test itself, a snapshot file, a page object, or a fixture. Application source files are automatically rejected. After a successful UPDATE, call \`skyramp_execute_test\` to confirm the patched test passes (the test environment is already running). Record the result as the after-state in the report. For DELETE and REGENERATE on external tests, see the execution policy in the decision rules above.
 
-For each UI test above, output one structured entry in \`recommendations[]\`:
+For each UI test in \`<tests_to_assess>\`, output one structured entry in \`recommendations[]\`:
 - **IGNORE**: \`{testFile} — IGNORE: {specific reason the diff cannot reach this test — name the route or component that differs}\` — do not pass to \`skyramp_actions\`
 - **VERIFY**: \`{testFile} — VERIFY: {uncertain element, e.g. "selectors hidden in page object not yet read"}\`
 \`\`\`
 Test: {testFile}
 Action: UPDATE
-Rationale: UPDATE because {quoted diff line}; {selector/route/behavior change}
+Rationale: UPDATE because {quoted diff line}; name the concrete before→after value (e.g. data-testid "old-id" → "new-id", class "btn-old" → "btn-new", route "/old" → "/new") — this rationale is the report's record of what was maintained, so a vague "selector changed" is not enough
 UpdateInstructions: {what must change — specific selectors to update, routes to patch, assertions to add}
 \`\`\`
 \`\`\`

package/build/prompts/test-recommendation/diffExecutionPlan.d.ts

@@ -14,4 +14,10 @@ export declare function buildExecutionPlan(scored: Array<{
     scenario: DraftedScenario;
     priority: PriorityTier;
     novelty: string;
-}>, maxGen: number, topN: number, baseUrl: string, authHeaderValue: string, authSchemeSnippet: string, authTypeValue: string, seed: string, endpointCount: number, isUIOnlyPR: boolean, hasFrontendChanges?: boolean, hasTraces?: boolean, externalCoverage?: Set<string>, relevantExternalTestPaths?: string[]): string;
+}>, maxGen: number, topN: number, baseUrl: string, authHeaderValue: string, authSchemeSnippet: string, authTypeValue: string, seed: string, endpointCount: number, isUIOnlyPR: boolean, hasFrontendChanges?: boolean, hasTraces?: boolean, externalCoverage?: Set<string>, relevantExternalTestPaths?: string[], 
+/**
+ * Whether the diff classified at least one new/modified/removed endpoint.
+ * Defaults to true so existing callers keep the fixed-budget rendering.
+ * See buildScopeAssessmentSection's hasClassifiedApiChanges (SKYR-3820).
+ */
+hasApiChanges?: boolean): string;

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

@@ -217,8 +217,18 @@ function roundRobinByType(rankOrdered, count) {
     }
     return selected;
 }
-export function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, authSchemeSnippet, authTypeValue, seed, endpointCount, isUIOnlyPR, hasFrontendChanges = false, hasTraces = false, externalCoverage = new Set(), relevantExternalTestPaths = []) {
+export function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, authSchemeSnippet, authTypeValue, seed, endpointCount, isUIOnlyPR, hasFrontendChanges = false, hasTraces = false, externalCoverage = new Set(), relevantExternalTestPaths = [], 
+/**
+ * Whether the diff classified at least one new/modified/removed endpoint.
+ * Defaults to true so existing callers keep the fixed-budget rendering.
+ * See buildScopeAssessmentSection's hasClassifiedApiChanges (SKYR-3820).
+ */
+hasApiChanges = true) {
     const frontendUrl = "<frontend_url>";
+    // SKYR-3820: backend diff with zero classified endpoint changes — the Budget
+    // Plan defaults to 0 (see scopeAssessment), so every "fill the budget" nudge
+    // in this plan must flip to its abstention-aware variant.
+    const zeroClassifiedPR = !isUIOnlyPR && !hasFrontendChanges && !hasApiChanges;
     // Slot allocation:
     // - UI-only PR: all GENERATE slots are UI placeholders (no pre-ranked backend scenarios)
     // - Mixed PR:   last GENERATE slot is a UI placeholder; remaining slots are backend
@@ -443,7 +453,9 @@ export function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValu
 - **UI**: ${hasTraces ? "Use an existing Playwright `.zip` trace with `skyramp_ui_test_generation`." : `Record a trace using \`browser_navigate\` + \`browser_snapshot\` + \`skyramp_export_zip\`, then call \`skyramp_ui_test_generation({ playwrightInput: "<zip_path>", outputDir: "<frontend_output_dir>" })\` — set \`outputDir\` to ${SERVICE_REFS.frontendTestDirRef}.`}
 Derive scenario names and steps from the actual changed frontend files. If your Budget Plan calls for 0% UI/E2E, omit this entirely.`
         : "";
-    const supplementNote = `\n**If your Budget Plan total exceeds the pre-ranked items listed above:** draft additional tests from source-code enrichment (Step ${EXEC_STEP_ENRICH}). For each new or changed endpoint, identify boundary or variation scenarios — formula parameters, search/filter constraints, required field validation. Only after exhausting PR-specific scenarios, add generic patterns (auth boundary → 401, non-existent ID → 404). Do NOT supplement with tests whose endpoint + test type match a GENERATE item.`;
+    const supplementNote = zeroClassifiedPR
+        ? `\n**Supplements:** With a 0-total Budget Plan, do not draft supplements. If you claimed the Scope Assessment ceiling, draft tests ONLY for endpoints whose observable behavior your code review showed actually changed in this diff — never generic patterns on unchanged endpoints.`
+        : `\n**If your Budget Plan total exceeds the pre-ranked items listed above:** draft additional tests from source-code enrichment (Step ${EXEC_STEP_ENRICH}). For each new or changed endpoint, identify boundary or variation scenarios — formula parameters, search/filter constraints, required field validation. Only after exhausting PR-specific scenarios, add generic patterns (auth boundary → 401, non-existent ID → 404). Do NOT supplement with tests whose endpoint + test type match a GENERATE item.`;
     // ── PR / branch-diff mode: execution plan ────────────────────────────────
     const externalTestFilesList = relevantExternalTestPaths.length > 0
         ? `**Read these external test files first** (paths are relative to the \`repositoryPath\` you passed to \`skyramp_analyze_changes\` — prepend it to get the absolute path). Determine exactly which HTTP methods + paths each one covers. This is the definitive source of truth for external coverage:\n${relevantExternalTestPaths.map((p) => `- \`${p}\``).join("\n")}\n\n`
@@ -455,9 +467,9 @@ Derive scenario names and steps from the actual changed frontend files. If your
         enrichStepLabel: EXEC_STEP_ENRICH,
     };
     return `## Execution Plan
-Seed: ${seed} | Endpoints: ${endpointCount} | Max: ${maxGen} generate + up to ${Math.max(topN - maxGen, 0)} additional (your Budget Plan determines the exact count)
+Seed: ${seed} | Endpoints: ${endpointCount} | Max: ${zeroClassifiedPR ? `0 generate by default (the Scope Assessment exception may raise it to ${maxGen} generate + up to ${Math.max(topN - maxGen, 0)} additional)` : `${maxGen} generate + up to ${Math.max(topN - maxGen, 0)} additional (your Budget Plan determines the exact count)`}
 
-${buildScopeAssessmentSection(topN, maxGen, isUIOnlyPR, isUIOnlyPR ? 100 : hasFrontendChanges ? undefined : 0, hasFrontendChanges)}
+${buildScopeAssessmentSection(topN, maxGen, isUIOnlyPR, isUIOnlyPR ? 100 : hasFrontendChanges ? undefined : 0, hasFrontendChanges, hasApiChanges)}
 
 ${_execPlan.render(_ctx)}
 
@@ -467,7 +479,9 @@ ${isUIOnlyPR
         ? uiGenerateBlocks ||
             "  (no UI generate items — derive scenarios from changed frontend files)"
         : [generateBlocks, uiPlaceholderBlock].filter(Boolean).join("\n\n") ||
-            "  (no pre-ranked generate items — draft your own based on endpoint analysis)"}
+            (zeroClassifiedPR
+                ? "  (no pre-ranked generate items — the Budget Plan defaults to 0 total; add items only under the Scope Assessment exception)"
+                : "  (no pre-ranked generate items — draft your own based on endpoint analysis)")}
 
 ### ADDITIONAL (list in additionalRecommendations in this order after Step ${EXEC_STEP_ENRICH} insertion)
 
@@ -476,7 +490,7 @@ ${uiGroundingGuidance}
 ${uiGuidance}
 ${supplementNote}
 
-**Honor your Budget Plan: produce exactly the total you committed to (GENERATE + ADDITIONAL). No fewer, no padding with low-value tests.**
+**Honor your Budget Plan: produce exactly the total you committed to (GENERATE + ADDITIONAL). No fewer, no padding with low-value tests. A Budget Plan of 0 total means zero tests — abstain and follow the zero-test report path; do not backfill.**
 
 ## Recommendation Stability
 - **Carry forward** previous additionalRecommendations that still apply — match by scenarioName (multi-step) or endpoint (single-endpoint). Re-derive category and priority from test content.

package/build/prompts/test-recommendation/scopeAssessment.d.ts

@@ -52,4 +52,13 @@ export declare function buildScopeAssessmentSection(maxTotal?: number, maxGenera
 /** Server-determined UI/E2E percentage. `undefined` = mixed PR or unknown. */
 precomputedUIPct?: number, 
 /** Whether the diff contains frontend files (true ↔ mixed PR when precomputedUIPct is undefined). */
-hasFrontendChanges?: boolean): string;
+hasFrontendChanges?: boolean, 
+/**
+ * PR-mode: whether the diff classified at least one new/modified/removed endpoint.
+ * When false on the backend branch (precomputedUIPct === 0), the Budget Plan
+ * defaults to 0 total with a conditional ceiling instead of a fixed mandate —
+ * SKYR-3820: a config-only PR must not be pushed to fill the budget with
+ * baseline tests for unchanged endpoints. Defaults to true so existing callers
+ * keep the unconditional fixed-budget rendering.
+ */
+hasClassifiedApiChanges?: boolean): string;

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

@@ -155,7 +155,9 @@ export function isFrontendFile(filePath, { hasFlutterSdkDep = false } = {}) {
 export function isTestFile(filePath) {
     return (/(?:_test|_smoke|_contract|_fuzz|_integration|_load|_e2e|_ui)\.[^/]+$/.test(filePath) ||
         /scenario_[^/]+\.json$/.test(filePath) ||
-        /\.(spec|test)\.(tsx?|jsx?)$/.test(filePath) ||
+        // Include the `.e2e.` dot form so Playwright/Cypress specs discovery treats as UI tests
+        // (UI_TEST_EXT matches `.(test|spec|e2e).`) are recognized here too — e.g. `login.e2e.ts`.
+        /\.(spec|test|e2e)\.(tsx?|jsx?)$/.test(filePath) ||
         /(?:^|\/)__tests__\//.test(filePath));
 }
 // ── LLM scope assessment ──────────────────────────────────────────────────────
@@ -174,9 +176,32 @@ export function buildScopeAssessmentSection(maxTotal = MAX_RECOMMENDATIONS, maxG
 /** Server-determined UI/E2E percentage. `undefined` = mixed PR or unknown. */
 precomputedUIPct, 
 /** Whether the diff contains frontend files (true ↔ mixed PR when precomputedUIPct is undefined). */
-hasFrontendChanges) {
+hasFrontendChanges, 
+/**
+ * PR-mode: whether the diff classified at least one new/modified/removed endpoint.
+ * When false on the backend branch (precomputedUIPct === 0), the Budget Plan
+ * defaults to 0 total with a conditional ceiling instead of a fixed mandate —
+ * SKYR-3820: a config-only PR must not be pushed to fill the budget with
+ * baseline tests for unchanged endpoints. Defaults to true so existing callers
+ * keep the unconditional fixed-budget rendering.
+ */
+hasClassifiedApiChanges = true) {
     const effectiveGenerate = Math.min(maxGenerate, maxTotal);
     const additional = Math.max(0, maxTotal - effectiveGenerate);
+    // Backend-only diff with zero classified endpoint changes (SKYR-3820): the
+    // budget defaults to 0 so the tool output agrees with the testbot prompt's
+    // zero-test report path, instead of mandating a fixed total the diff cannot
+    // justify. The ceiling stays claimable because a zero-classified diff can be
+    // a classification miss on a real behavior change (e.g. a DTO/serializer
+    // change the endpoint scanner cannot attribute — SKYR-3855's immich case).
+    if (precomputedUIPct === 0 && !hasClassifiedApiChanges) {
+        return `### PR Scope Assessment
+Budget Plan: 0 total — no new, modified, or removed endpoints were classified from this diff, and no frontend files changed.
+
+With a 0-total Budget Plan: generate zero tests, recommend zero tests, and follow the zero-test report path. Do NOT draft baseline or generic tests for unchanged endpoints to fill a budget — an empty diff surface is a valid, expected outcome.
+
+**Exception — claim the ceiling only with evidence:** if your code review of the changed files shows an observable API behavior change the classifier missed (e.g. a DTO/serializer/service change that alters a response shape, or a deployment/config change that newly exposes or removes endpoints), raise your Budget Plan to cover exactly those affected endpoints, up to ${maxTotal} total (${effectiveGenerate} generate + ${additional} additional), 0% UI/E2E. Every test must name the changed file that justifies it. State your raised plan now in the canonical format — \`Budget Plan: <total> total (<generate> generate + <additional> additional), 0% UI/E2E\` — and use those exact numbers throughout the rest of the prompt; the raised generate count is your committed generate count.`;
+    }
     // Unambiguous backend-only or UI-only: emit a single Budget Plan line — no LLM counting needed.
     if (precomputedUIPct !== undefined) {
         return `### PR Scope Assessment

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

@@ -204,6 +204,9 @@ describe("isTestFile", () => {
         expect(isTestFile("src/components/Button.test.tsx")).toBe(true);
         expect(isTestFile("e2e/login.spec.js")).toBe(true);
         expect(isTestFile("packages/foo/Bar.test.jsx")).toBe(true);
+        // `.e2e.` dot form (Playwright/Cypress) — discovery's UI_TEST_EXT treats it as a UI test.
+        expect(isTestFile("e2e/login.e2e.ts")).toBe(true);
+        expect(isTestFile("packages/foo/Members.e2e.tsx")).toBe(true);
     });
     it("matches files under __tests__/ directories", () => {
         expect(isTestFile("src/__tests__/utils.ts")).toBe(true);
@@ -280,6 +283,38 @@ describe("buildScopeAssessmentSection", () => {
         expect(section).not.toContain("Step C");
         expect(section).not.toContain("Step D");
     });
+    // ---------------------------------------------------------------------------
+    // SKYR-3820 — zero-classified backend diff: budget defaults to 0
+    // ---------------------------------------------------------------------------
+    it("defaults the Budget Plan to 0 total when precomputedUIPct=0 and hasClassifiedApiChanges=false (SKYR-3820)", () => {
+        const section = buildScopeAssessmentSection(20, 3, false, 0, false, false);
+        expect(section).toContain("Budget Plan: 0 total");
+        // The fixed budget mandate must NOT be asserted
+        expect(section).not.toContain("Budget Plan: 20 total (3 generate + 17 additional)");
+        expect(section).not.toContain("Use these exact numbers throughout the rest of the prompt.");
+        // The conditional ceiling names the numbers the agent may claim after code review
+        expect(section).toContain("up to 20 total (3 generate + 17 additional)");
+    });
+    it("keeps the fixed budget line when hasClassifiedApiChanges is omitted (back-compat default true)", () => {
+        const withDefault = buildScopeAssessmentSection(10, 3, false, 0, false);
+        const explicitTrue = buildScopeAssessmentSection(10, 3, false, 0, false, true);
+        expect(withDefault).toBe(explicitTrue);
+        expect(withDefault).toContain("Budget Plan: 10 total (3 generate + 7 additional), 0% UI/E2E");
+        expect(withDefault).not.toContain("Budget Plan: 0 total");
+    });
+    it("does not apply the zero-classified override to UI-only PRs (precomputedUIPct=100)", () => {
+        // UI-only PRs have hasApiChanges=false by construction — the override must be
+        // gated on the backend branch (precomputedUIPct === 0) only.
+        const section = buildScopeAssessmentSection(10, 3, true, 100, false, false);
+        expect(section).toContain("Budget Plan: 10 total (3 generate + 7 additional), 100% UI/E2E");
+        expect(section).not.toContain("Budget Plan: 0 total");
+    });
+    it("does not apply the zero-classified override to the mixed-PR branch", () => {
+        const section = buildScopeAssessmentSection(10, 3, false, undefined, true, false);
+        expect(section).toContain("Budget Plan (total already determined)");
+        expect(section).toContain("Cosmetic-only override");
+        expect(section).not.toContain("Budget Plan: 0 total");
+    });
     it("emits a single Budget Plan line for UI-only PR (precomputedUIPct=100)", () => {
         const section = buildScopeAssessmentSection(10, 3, true, 100, false);
         expect(section).toContain("Budget Plan: 10 total (3 generate + 7 additional), 100% UI/E2E");

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

@@ -342,7 +342,11 @@ ${detailBlocks}
         if (externalCoverage.size > 0) {
             logger.info(`External test coverage keys: ${[...externalCoverage].join(", ")}`);
         }
-        mainSection = buildExecutionPlan(scored, maxGen, topN, analysis.apiEndpoints.baseUrl, authHeaderValue, authSchemeSnippet, authTypeValue, seed, endpointCount, isUIOnlyPR, hasFrontendChanges, hasTraces, externalCoverage, analysis.existingTests.relevantExternalTestPaths ?? []);
+        mainSection = buildExecutionPlan(scored, maxGen, topN, analysis.apiEndpoints.baseUrl, authHeaderValue, authSchemeSnippet, authTypeValue, seed, endpointCount, isUIOnlyPR, hasFrontendChanges, hasTraces, externalCoverage, analysis.existingTests.relevantExternalTestPaths ?? [], 
+        // Zero-classified gating (SKYR-3820) requires an actual diff that classified
+        // nothing — a missing diffContext is absence of evidence, not an empty
+        // change surface, so it keeps the legacy fixed-budget rendering.
+        diffContext ? hasApiChanges : true);
     }
     else {
         // Full-repo scope with no scored items — rare fallback

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

@@ -685,6 +685,67 @@ describe("buildRecommendationPrompt — LLM scope assessment for UI/E2E split",
     });
 });
 // ---------------------------------------------------------------------------
+// Tests — zero-classified diff: budget defaults to 0 (SKYR-3820)
+// ---------------------------------------------------------------------------
+describe("buildRecommendationPrompt — zero-classified diff (SKYR-3820)", () => {
+    function zeroClassifiedAnalysis(changedFiles) {
+        return minimalAnalysis({
+            businessContext: { mainPurpose: "Test", userFlows: [], dataFlows: [], integrationPatterns: [], draftedScenarios: [] },
+            branchDiffContext: {
+                baseBranch: "main",
+                currentBranch: "skyramp/testbot-setup",
+                changedFiles,
+                newEndpoints: [],
+                modifiedEndpoints: [],
+                affectedServices: [],
+            },
+        });
+    }
+    it("config-only PR (netbox shape): Budget Plan defaults to 0 total, fixed budget mandate absent", () => {
+        const prompt = buildRecommendationPrompt(zeroClassifiedAnalysis([
+            ".github/workflows/skyramp-testbot.yml",
+            "deployment-testbot/Dockerfile",
+            "deployment-testbot/configuration.py",
+            "deployment-testbot/setup.sh",
+        ]), AnalysisScope.CurrentBranchDiff, 20, undefined, undefined, undefined, undefined, 3);
+        expect(prompt).toContain("Budget Plan: 0 total");
+        expect(prompt).not.toContain("Budget Plan: 20 total (3 generate + 17 additional)");
+        expect(prompt).not.toContain("Use these exact numbers throughout the rest of the prompt.");
+        // The "draft your own" pressure valves must not fire on a zero-classified diff
+        expect(prompt).not.toContain("draft your own based on endpoint analysis");
+        expect(prompt).not.toContain("If your Budget Plan total exceeds the pre-ranked items listed above");
+    });
+    it("backend source change with 0 classified endpoints keeps the conditional ceiling (SKYR-3855 guard)", () => {
+        // immich user.dto.ts shape — classification blind to a real behavior change.
+        // The agent must still be able to claim the budget from its own code review.
+        const prompt = buildRecommendationPrompt(zeroClassifiedAnalysis(["server/src/dtos/user.dto.ts"]), AnalysisScope.CurrentBranchDiff, 20, undefined, undefined, undefined, undefined, 3);
+        expect(prompt).toContain("Budget Plan: 0 total");
+        expect(prompt).toContain("up to 20 total (3 generate + 17 additional)");
+    });
+    it("classified backend PR is unchanged: fixed budget line still rendered", () => {
+        const analysis = minimalAnalysis({
+            businessContext: { mainPurpose: "Test", userFlows: [], dataFlows: [], integrationPatterns: [], draftedScenarios: [] },
+            branchDiffContext: {
+                baseBranch: "main",
+                currentBranch: "feature/test",
+                changedFiles: ["backend/routes.py"],
+                newEndpoints: [{ path: "/api/items", methods: [{ method: "POST", sourceFile: "routes.py", interactionCount: 0 }] }],
+                modifiedEndpoints: [],
+                affectedServices: [],
+            },
+        });
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 20, undefined, undefined, undefined, undefined, 3);
+        expect(prompt).toContain("Budget Plan: 20 total (3 generate + 17 additional), 0% UI/E2E");
+        expect(prompt).toContain("Use these exact numbers throughout the rest of the prompt.");
+        expect(prompt).not.toContain("Budget Plan: 0 total");
+    });
+    it("buildExecutionPlan omitting hasApiChanges renders the fixed budget (back-compat)", () => {
+        const plan = buildExecutionPlan([], 3, 20, "http://localhost:3000", "", "", "", "seed", 100, false, false);
+        expect(plan).toContain("Budget Plan: 20 total (3 generate + 17 additional), 0% UI/E2E");
+        expect(plan).not.toContain("Budget Plan: 0 total");
+    });
+});
+// ---------------------------------------------------------------------------
 // Tests — GENERATE slot allocation (UI vs backend slots)
 // ---------------------------------------------------------------------------
 describe("buildRecommendationPrompt — GENERATE slot allocation", () => {