@skyramp/mcp 0.2.4 → 0.2.5-rc.1

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

@@ -2,37 +2,46 @@
  * Modular section builders for the Drift Analysis prompt,
  * mirroring the recommendationSections.ts pattern.
  */
-export function buildActionDecisionMatrix() {
+import { AUTH_MIDDLEWARE_PATTERNS_STR } from "../../utils/workspaceAuth.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.
+// This reduces LLM variability in action assignment for the same diff.
+export function buildActionDecisionTree() {
     return `<decision_rules>
-## Action Decision Tree
+**Before the numbered checks, apply the scope gate:** can this test's service or interface boundary actually reach the changed code? If the answer is clearly no — the test targets a definitively different service, a read-only replica, a completely separate microservice, or a different protocol — assign IGNORE and skip the remaining checks for this test. When reachability is uncertain (shared output layer, inherited base models, conditional field exposure), use VERIFY instead of IGNORE.
 
-For each existing test, work through these checks in order — the first match wins:
+**Before working through any individual check, do a single pass over the entire diff** to record all diff lines that directly change observable API behavior (route paths, response fields, status codes, auth gates, validation logic). For each matched diff line write one line: \`{pattern type} — "{diff line}" — affects {endpoint/test}\`. Build this detection list first — it is your working artifact for all tests. An action with no entry in this list is unsupported.
 
-1. **All endpoints the test covers were removed** → **DELETE**
-2. **Some endpoints removed, some renamed** → **UPDATE**
-3. **New response field added to a covered endpoint** → **UPDATE** — the test needs a new assertion even if existing assertions still pass
-4. **Shape change breaks assertions (field-level: ≤2 fields changed, renamed, or type-swapped)** → **UPDATE**
-   **Shape change restructures the root response (flat→nested, new wrapper object, root key renamed, ≥50% of test assertions broken)** → **REGENERATE**
-5. **Auth added or auth method changed** → **UPDATE**
-   **Auth removed** → **VERIFY**
-6. **No breaking changes detected** → **IGNORE** or **VERIFY** for minor drift
+Diff lines that change observable API behavior — look for these in the pre-scan:
+- Route removed or renamed: \`- @app.route\`, \`- router.get\`, \`- @GetMapping\`, or paired \`-\`/\`+\` on a route decorator
+- Field type/removal: \`- field: int\`/\`+ field: string\`, \`- "responseField":\`
+- Status/enum change: \`- return 200\`/\`+ return 201\`, \`- status: "active"\`/\`+ status: "enabled"\`
+- Root wrapper change: \`- return Response({...})\`/\`+ return Response({"data":{...},"meta":{...}})\`
+- New field in output layer (DTO, response schema, view, output formatter, \`res.json\`): \`+ "newField":\` or \`+ newField =\` inside the response-building code
+- New field in model/migration only (no output layer change): \`+ newField = Column(...)\`
+- Auth added/removed/changed: \`+ @require_auth\`, \`- @require_auth\`, token-type change
+- Scope narrowed: \`+ requireRole\`, \`+ raise PermissionError\`, \`+ if not is_owner\`, \`+ [x for x in xs if x.owner == caller_id]\`
+- Behavioral: \`+ raise ValidationError\`/\`+ HTTPException(409)\` on new \`if\`, \`+ VALID_TRANSITIONS\`, sync→async (\`- return 200\`/\`+ return 202\`), formula change (\`- total = a - b\`/\`+ total = a + tax - b\`)
+
+Then, for each test where the changed code *is* reachable, work through the individual checks below using your pre-built detection list. Collect **all** matching signals, then assign the single highest-severity action across all matches. Severity order (highest first): **DELETE > REGENERATE > UPDATE > VERIFY > IGNORE**. **Before assigning UPDATE, REGENERATE, or DELETE, quote the specific diff line(s) that triggered it in the rationale. If you cannot point to a diff line this test's endpoint can observe, the action is IGNORE or VERIFY, not UPDATE.**
 
 Rules:
-- DELETE when all covered endpoints no longer exist; REGENERATE when they still exist but changed drastically.
-- REGENERATE means: the top-level response shape changed (flat→nested, new wrapper object added, root key renamed), OR ≥50% of the test's assertions reference fields that were removed or restructured. In all other cases, prefer UPDATE.
-- Prefer UPDATE over REGENERATE when changes are field-level (≤2 fields added, removed, renamed, or type-swapped).
-- Prefer IGNORE over VERIFY when all changed files are unrelated to the test's endpoint.
+- Collect all signals; assign the highest-severity action across them. Include all matched signals in the rationale and all matching \`updateInstructions\` — a diff that renames a path AND adds a field requires both a URL patch and a new assertion.
+- DELETE when all covered endpoints no longer exist; REGENERATE when they still exist but the root response wrapper changed and essentially every assertion is now invalid. In all other cases, prefer UPDATE.
+- REGENERATE when the root response wrapper changed (flat→nested, new envelope object, root key renamed) and essentially every assertion is invalid — if you can describe the fix as patching N specific paths, it is UPDATE regardless of how many paths there are.
+- Prefer IGNORE over VERIFY when all changed files are unrelated to the test's endpoint. Exception: if the diff touches a shared output layer, base model, or response formatter that the test's endpoint uses, prefer VERIFY even if no route file changed.
 - ADD actions belong in the next step — complete this assessment with IGNORE / VERIFY / UPDATE / REGENERATE / DELETE only.
 
 <examples>
 <example>
-Diff adds one field to a response object and renames a URL path segment:
+Diff adds one field to the response output and renames a URL path segment:
 \`\`\`
 - @app.route("/users/<id>/orders")
 + @app.route("/users/<id>/purchases")
-+ "total_items": len(order.items)
++ "total_items": len(order.items)  # inside the response-building code this test hits
 \`\`\`
-→ **UPDATE**: path rename + one new field — both are field-level changes. Patch the URL and add an assertion for \`total_items\`.
+→ **UPDATE**: output layer signal confirmed in diff (total_items added to the response builder) + path rename. Patch the URL and add an assertion for \`total_items\`.
 </example>
 <example>
 Diff wraps the entire response in a new envelope object:
@@ -40,184 +49,214 @@ Diff wraps the entire response in a new envelope object:
 - return Response({"id": ..., "status": ..., "items": [...]})
 + return Response({"data": {"id": ..., "status": ..., "items": [...]}, "meta": {"page": 1}})
 \`\`\`
-→ **REGENERATE**: root shape changed from a flat object to \`{data, meta}\`. Every existing assertion (e.g. \`response["id"]\`, \`response["status"]\`) is broken — rewrite the test from scratch.
+→ **REGENERATE**: root wrapper changed — every existing assertion (e.g. \`response["id"]\`) is broken. Rewrite from scratch.
+</example>
+<example>
+Diff adds a field to a model/migration only — project has an explicit output layer (DTO, response schema, field allowlist) controlling what gets exposed:
+\`\`\`
++ sort_order = Column(Integer, nullable=True)  # in models.py
+\`\`\`
+No output layer file changed.
+→ **VERIFY**: cannot confirm from the diff alone whether sort_order is included in the response — the output layer may exclude it.
+</example>
+<example>
+Diff adds a field to a model/migration only — project has no explicit output layer (model fields are passed through directly to the response):
+\`\`\`
++ sort_order: {type: 'integer', nullable: true}  # in db/schema.js
+\`\`\`
+No output layer file changed. No field allowlist or exclusion exists for this resource.
+→ **UPDATE**: model fields are auto-exposed in responses. Augment the test to assert the new field is present and round-trips correctly.
+</example>
+<example>
+Diff changes a status code in the handler:
+\`\`\`
+- res.status(200).json(...)
++ res.status(201).json(...)
+\`\`\`
+→ **UPDATE**: the test asserts \`toBe(200)\` which now fails. Patch the status assertion.
+</example>
+<example>
+Diff adds a role gate to a route the test covers:
+\`\`\`
++ if (user.role !== "owner") {
++   return res.status(403).json({ error: "forbidden_role" });
++ }
+\`\`\`
+→ **UPDATE**: the test's existing token now gets 403. Send a token with sufficient role and add a 403 negative assertion for the restricted role. (Authorization scope narrowed — not an auth-mechanism change; the Auth/AuthZ and Behavioral Contract checks cover this.)
+</example>
+<example>
+Diff adds a state-transition guard:
+\`\`\`
++ const VALID_TRANSITIONS = { draft: ["review"], review: ["published"] };
++ if (!VALID_TRANSITIONS[currentStatus]?.includes(newStatus)) {
++   throw new HTTPException(409, "invalid_transition");
++ }
+\`\`\`
+→ **UPDATE**: an integration test that previously posted \`draft→published\` directly now gets 409. Chain through the valid states (draft→review→published) and add a 409 assertion for the direct skip.
 </example>
 </examples>
 </decision_rules>`;
 }
+// Retained for backwards compatibility — no longer rendered in the prompt.
+// Diff signals are now inlined into each individual check function.
+/** @deprecated use the individual check functions; this function is no longer part of the prompt */
 export function buildBreakingChangePatterns() {
-    return `## Breaking Change Patterns to Detect
-
-Scan the diff lines for these high-signal patterns:
-
-### Endpoint-level breaking changes
-- \`-  @app.route("/old-path")\` / \`+  @app.route("/new-path")\` — renamed endpoint
-- \`-  router.get("/old")\` / \`+  router.get("/new")\` — renamed route
-- \`-  @GetMapping("/old")\` / \`+  @GetMapping("/new")\` — Spring rename
-- Lines removing a route decorator entirely (endpoint removed)
-
-### Request/response shape changes
-- Field type changes: \`- field: int\` → \`+ field: string\`
-- Required field added: \`+ required: [..., "newField"]\`
-- Response field removed: \`- "responseField":\`
-- Enum value changes: \`- status: "active"\` → \`+ status: "enabled"\`
-
-### Auth changes
-- \`+ @require_auth\`, \`+ @login_required\`, \`+ middleware(authMiddleware)\`
-- \`- @require_auth\` (auth removed)
-- Token type changed: Bearer → Cookie
-
-### Status code changes
-- \`- return 200\` → \`+ return 201\`
-- \`- status_code=200\` → \`+ status_code=204\`
-- \`- res.status(201)\` → \`+ res.status(200)\`
-
-### Additive response field changes (non-breaking but coverage gap)
-These do NOT break existing assertions but leave the new field untested. Always flag as UPDATE for covered endpoints.
-- \`+ "newField": queryset.filter(...).count()\` added inside a \`Response({...})\` or \`res.json({...})\`
-- \`+ newField = serializers.XXXField()\` added to a serializer used by a tested endpoint
-- \`+ "newField":\` added to a response body dict returned by the endpoint
-- New key added inside an existing dict/object returned by the endpoint`;
+    return "";
 }
-export function buildTestAssessmentGuidelines() {
-    return `## Per-Test Assessment (4 Checks)
-
-For each existing test file, run these checks:
-
-### Check A: Endpoint existence
-Does the endpoint the test targets still exist in the codebase?
-- If ALL endpoints the test covers were removed → action: DELETE (the entire test file is obsolete)
-- If SOME methods were removed but others remain → action: UPDATE (remove the test functions for deleted methods, keep the rest)
-- If the endpoint was renamed → action: UPDATE (path substitution)
-
-### Check B: Request/response shape (breaking changes)
-Has the request body or response structure changed in a way that breaks the test?
-- Compare test's expected fields against current schema/model definitions
-- Type changes (string→int, int→string) on individual fields → action: UPDATE
-- Type change restructures the root object or makes the entire request body invalid → action: REGENERATE
-- New required fields the test doesn't send → action: UPDATE
-- Response fields the test asserts on have been removed → action: UPDATE
-- ≥50% of the test's assertions reference fields that were removed or restructured → action: REGENERATE
-
-**UPDATE vs REGENERATE:** choose UPDATE when changes are field-level (≤2 fields added, removed, renamed, or type-swapped). Choose REGENERATE only when the root response shape changed (flat→nested, new wrapper object, root key renamed) or ≥50% of assertions are broken.
-
-### Check B2: Additive response field changes (coverage gaps)
-**Even if existing assertions still pass**, does the diff add a new field to the response of an endpoint this test already covers?
-- Look at the diff for lines like \`+ "newField":\` or \`+ newField =\` inside a view/serializer this test hits
-- If YES → action: UPDATE
-- This applies even when the test only checks status codes — the test should be extended to cover the new field
-- A new response field on a covered endpoint always triggers UPDATE — even when existing assertions still pass.
-
-### Check C: Auth changes
-Has the authentication mechanism for this endpoint changed?
-- Auth added where none existed → action: UPDATE
-- Auth method changed (bearer→cookie) → action: UPDATE
-- Auth removed → action: VERIFY
-
-### Check D: Assign action
-Based on the above, choose the action (IGNORE / VERIFY / UPDATE / REGENERATE / DELETE) and provide a 1-2 sentence rationale.
-- If Check B2 flagged an additive field → action must be UPDATE, even if Checks B/C found no breaking changes.`;
+export function buildCheckEndpointExistence() {
+    return `Does the endpoint the test targets still exist in the codebase?
+
+Diff signals to look for:
+- Route removed: \`- @app.route("/path")\`, \`- router.get("/path")\`, \`- @GetMapping("/path")\`
+- Route renamed: paired \`-\` and \`+\` on a route decorator with a different path
+- Redirect added for old path: \`res.setHeader("Location", ...)\` + \`res.status(301)\` or \`res.status(308)\` in middleware or a handler for the old path
+
+Actions:
+- ALL endpoints the test covers were removed → DELETE (the entire test file is obsolete)
+- SOME methods removed but others remain → UPDATE (remove test functions for deleted methods, keep the rest)
+- Endpoint renamed with **no redirect** (route decorator changed, no \`setHeader("Location")\` signal in the diff) → UPDATE (path substitution to the new path; supply \`renamedEndpoints\`)
+- Endpoint renamed with **redirect kept** (\`setHeader("Location")\` + 301/308 signal present for the old path) → UPDATE: assert the redirect status AND \`Location\` header on the old path. Do NOT just substitute the URL — the old-path test must verify the redirect contract, not the canonical response.`;
 }
-export function buildAddRecommendationGuidelines() {
-    return `## ADD — New Tests for New Endpoints
-
-**ADD applies only when:**
-- The diff introduces a brand-new route that has **no existing test coverage at all**, OR
-- The diff introduces a new auth path, error branch, or fundamentally separate scenario that no existing test covers.
+export function buildCheckResponseShape() {
+    return `Has the request body or response structure changed in a way that breaks the test?
 
-**Use UPDATE instead of ADD when:**
-- The resource already has existing tests and the diff only adds a new HTTP method — add the new method's test cases to the existing file.
-- The endpoint existed before this diff but lacks tests — log it in \`additionalRecommendations\` and skip it; pre-existing coverage gaps are out of scope for ADD.
-
-**Test type priority by HTTP method:**
-| Method | Recommended test types |
-|--------|----------------------|
-| POST / PUT / PATCH | integration, contract |
-| GET | contract, smoke |
-| DELETE | integration, smoke |
-
-Use a unique descriptive filename for every new test file. For a resource with existing tests, update the existing file — always prefer UPDATE over creating a new file.`;
+Diff signals to look for:
+- Field type change: \`- field: int\` / \`+ field: string\`
+- Required request body field added: \`+ required: [..., "newField"]\`
+- Required query param added with no default
+- Response field removed: \`- "responseField":\`
+- Enum value changed: \`- status: "active"\` / \`+ status: "enabled"\`
+- Status code changed: \`- return 200\` / \`+ return 201\`
+- Root wrapper added: \`- return Response({...})\` / \`+ return Response({"data": {...}, "meta": {...}})\`
+
+Actions:
+- Type changes, new required fields, removed asserted fields, status/enum changes → UPDATE
+- Root response wrapper changed and essentially every assertion is now invalid → REGENERATE
+
+**UPDATE vs REGENERATE — the deciding question is whether the root response wrapper changed:**
+- **REGENERATE** only when a new top-level envelope object wraps the entire payload or the root key is renamed so that essentially every existing assertion must change.
+- **UPDATE** for everything else. If you can describe the fix as "patch these N assertion paths", it is UPDATE regardless of how many paths there are.
+- When every assertion in the file is invalid, it is REGENERATE. When you can still patch individual paths, it is UPDATE.`;
 }
-export function buildUpdateExecutionRules() {
-    return `<execution_rules>
-## Update Execution Rules
+export function buildCheckAuthAndAuthorization() {
+    return `Has the authentication or authorization for this endpoint changed?
 
-When applying UPDATE actions to existing test files, follow these rules in addition to the drift-detected changes:
+**Authentication mechanism**
 
-### Test file ordering
-Place mutation test functions (PATCH, PUT, POST) **before** any DELETE test function targeting the same resource. DELETE removes the resource — any mutation call after it will 404. When inserting a new mutation test, place it above the DELETE function and above the DELETE call in the \`if __name__ == "__main__"\` block (or equivalent runner entrypoint).
+Diff signals to look for: ${AUTH_MIDDLEWARE_PATTERNS_STR}. Also: \`@requiresRole\`/\`@Protected\`, \`validateToken\`/\`checkPermission\`/\`verifyHMAC\`, imports from auth/security packages, \`- @require_auth\` (removal), token type change (Bearer → Cookie).
 
-### Happy path first
-When adding a new HTTP method (PUT, PATCH, POST) to an existing test file, always include a 2xx success assertion first. Error-path tests (404, 422) may follow, but the happy path case is required.
+Actions:
+- Auth added where none existed → UPDATE (test would 401/403 on every request without the new credential)
+- Auth method changed (e.g. bearer→cookie) → UPDATE (test sends the wrong credential type)
+- Auth removed and test asserts a 401/403 response that will no longer fire → UPDATE
+- Auth removed and test does not assert on auth responses → VERIFY (endpoint may now be intentionally public)
 
-### All test files for a resource
-When a diff adds a new HTTP method to a resource, UPDATE covers **all** existing test files for that resource — contract, integration, and UI. Apply UPDATE to every file the analyze tool reported for that resource path; do not stop after updating the first one.
+**Authorization scope** (same credential, narrower access)
 
-### PATCH/PUT with child collections
-Child collection arrays (e.g. \`items\`, \`products\`, \`line_items\`) drive computed totals — a test that omits them cannot catch the most common mutation bugs. When the request/response includes a child collection:
-1. Include the child array with at least one item containing the FK field (e.g. \`product_id\`) and a \`quantity\` field.
-2. Assert each item's FK field and \`quantity\` match the sent values.
-3. Assert the top-level computed total (e.g. \`total_amount\`) equals the expected math from the items.
+Diff signals to look for: \`+ requireRole\`, \`+ requireCreateX\`/\`requireDeleteX\`, \`+ assert_*_scope\`, \`+ ALLOWED_ROLES.includes\`/\`ASSIGNABLE_ROLES\`, \`+ if not is_owner\`, \`+ raise PermissionError\`/\`HTTPException(403)\`, \`+ [x for x in xs if x.owner == caller_id]\`, new role-carrying request header (e.g. \`X-Workspace-Role\`).
 
-### REGENERATE
-Call the appropriate generation tool to replace the existing test from scratch. Use the same filename so it overwrites the old file.
+Actions:
+- Role or ownership gate added → UPDATE (test's existing token may now get 403; send a sufficient-role token and add a 403 negative assertion)
+- Caller-identity filtering added → UPDATE (test's token now returns a subset; adjust expectations or use an admin-scope token)
+
+Do NOT assign IGNORE just because the auth *mechanism* is unchanged — scope narrowing breaks a token-valid test.`;
+}
+export function buildCheckBehavioralContract() {
+    return `Has the endpoint's BEHAVIOR changed while its response shape stayed the same? A test can break even when no field was added or removed.
+
+Diff signals and actions:
+- **Validation tightened**: \`+ raise ValidationError\`/\`+ throw new ValidationError\` gated on field value, \`+ Field(pattern=...)\`/\`ge=\`/\`le=\`/\`max_length=\` on an existing field → UPDATE (fix the payload to satisfy the new constraint; add the 4xx negative case)
+- **New conditional rejection / state guard**: \`+ raise HTTPException(status_code=409)\`/\`+ res.status(409)\` inside a new \`if\`, \`+ VALID_TRANSITIONS\`, \`+ allowed_states = ...\` → UPDATE (chain through valid states; assert the rejection status for the now-illegal path)
+- **Sync → async**: \`- return 200 result\` / \`+ return 202 {job_id}\` → UPDATE (assert \`202\` and the job/id field; remove old result-field assertions from the immediate response)
+- **Computed-field formula changed**: \`- total = a - b\` / \`+ total = a + tax - b\` on an existing asserted field → UPDATE; describe the new formula in \`updateInstructions\` and provide the recomputed expected value where inputs are known from the diff
+- **Behavior gated on a request header**: old shape returned only when a version header is sent; new shape is now the default → UPDATE (migrate assertions to the new default shape, or pin the old shape by sending the version header)
+- **Redirect added to existing path** (e.g. \`res.setHeader("Location", ...)\` + \`res.status(301)\` or \`res.status(308)\`): the endpoint now redirects instead of serving a response → UPDATE: assert the redirect status code AND the \`Location\` header value. Do not just update the URL in the test to the new canonical path — that loses the redirect contract.
+
+**Reachability for behavioral changes:** The service/interface scope gate still applies — if the test targets a completely different service or protocol, IGNORE. However, do NOT use the absence of a route or output layer file in the diff as grounds for IGNORE. Behavioral changes (new error branches, new validation, status-code changes) are observable from any test calling the same endpoint, even when the logic lives in an internal handler, middleware, or utility file rather than the route file itself.`;
+}
+export function buildCheckAssignAction() {
+    return `Based on the above checks, choose the action (IGNORE / VERIFY / UPDATE / REGENERATE / DELETE) and provide a 1-2 sentence rationale.
+
+**Every action requires a specific rationale — including IGNORE:**
+- UPDATE / REGENERATE / DELETE: quote the specific diff line that triggered it.
+- VERIFY: name the uncertain element (e.g. "model-only change, cannot confirm field is exposed without checking the output layer").
+- IGNORE: name the specific reason the changed code cannot reach this test's endpoint (e.g. "diff only touches \`auth/session-service.js\` — this test targets \`/api/v1/orders\` which has no session dependency"). Generic "unrelated endpoint" or "service boundary" without a diff reference is not sufficient.
+
+- 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.
+- **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.
+- **Pre-commit verification — confirm all three before finalizing UPDATE/REGENERATE/DELETE:**
+  1. You can quote a specific diff line this test's endpoint observes that triggered the action.
+  2. The changed code is reachable through this test's service and base URL.
+  3. For REGENERATE: every assertion in the file is invalid, not just some — if you can patch N paths, it is UPDATE.
+  If any check fails, downgrade to VERIFY or IGNORE.
+- **For user-written (external) tests** marked \`[external]\` in the test list:
+  - UPDATE is permitted — targeted edits only (fix renamed URL, add assertion for new field, add a new test case for a new scenario). Match the style of the existing file: use the same test framework, assertion helpers, and request pattern already present.
+  - REGENERATE and DELETE are **not permitted** — assign those actions in your recommendations but \`skyramp_actions\` will surface them as report-only findings for the developer to act on. Do NOT attempt to rewrite or delete a user-authored test file.`;
+}
+export function buildCheckAdditiveFields() {
+    return `Even if existing assertions still pass, new response fields on a covered endpoint need a new assertion. A field being optional or nullable does not make it IGNORE — it still needs to be covered.
 
-### DELETE
-Remove the test file when ALL endpoints it covers were removed from the codebase. If only SOME methods were removed, use UPDATE instead — remove the test functions for deleted methods and keep the rest.
+Diff signals to look for:
+- \`+ "newField": ...\` or \`+ newField =\` inside response-building code (DTO, response schema, view, output formatter, \`res.json\`, \`return {...}\`) → output layer signal confirmed
+- \`+ newField = Column(...)\` or \`+ newField:\` in a model/migration only, with no output layer change → model-only signal
 
-### Test data isolation
-Never use hardcoded resource IDs (e.g. \`order_id=1\`) in any test step, including GET or DELETE steps. Always create required resources via prior POST steps and chain IDs dynamically. Use timestamp-based unique names for created resources (e.g. \`"Product-\${int(time.time())}"\`) to prevent collisions across test runs.
+Actions:
+- Output layer signal confirmed → UPDATE (assert the new field in the existing test: its value on create, its round-trip on read, and its default when omitted)
+- Model-only signal, **project has an explicit output layer** (a separate DTO, response schema, field allowlist, or \`fields =\` definition controls what gets exposed) → VERIFY (cannot confirm from diff alone whether the field is included in the response)
+- Model-only signal, **project has no explicit output layer** (model fields are passed through directly to the response) → UPDATE (field is auto-exposed in responses; augment the test)
 
-### Enhance assertions after UPDATE
-Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the test file you just updated, \`enhanceType: "maintenance"\`, and the matching \`testType\` based on the file you are editing:
-- **Integration test file** (multi-step chained requests): call with \`testType: "integration"\`
-- **Contract-provider test file** (single endpoint with \`beforeAll\`/\`afterAll\` setup, provider mode): call with \`testType: "contract"\`. Skip for consumer-mode contract tests.
-- **UI test file** (imports \`@playwright/test\`, uses \`page.\` calls): call with \`testType: "ui"\`
+To determine which applies: look at whether an explicit output layer (DTO, serializer, \`response_model\`, field allowlist) is visible in the diff context — either as a changed file or as an import in a changed file. If yes and it was not changed in this diff → VERIFY (cannot confirm the new field is included without reading it). If no explicit output layer is visible in the diff context → UPDATE (model fields are passed through directly).
 
-Then apply every instruction returned by the tool to the test file.
-</execution_rules>`;
+**Do not assign IGNORE because the field is optional or nullable** — "won't break existing assertions" is not the bar. The bar is "does the test now cover this endpoint's full contract?" A new field, even optional, means the contract changed and the test is incomplete.`;
 }
-export function buildDriftOutputChecklist(existingTestCount, newEndpointCount, inlineMode = false, stateFile) {
-    const finalStep = inlineMode
-        ? `### Final step
-Apply all maintenance actions (UPDATE / REGENERATE / DELETE) directly by editing the test files. Apply IGNORE, VERIFY, UPDATE, REGENERATE, or DELETE only — ADD is handled in the next task.`
-        : `### Final step
-After completing all assessments above, call \`skyramp_actions\` with \`stateFile: "${stateFile ?? "<stateFile>"}"\` and a \`recommendations\` entry for every test assessed. For each entry include: \`testFile\` (absolute path as reported by the analysis tools), \`action\`, \`rationale\`, \`updateInstructions\` (free-form summary of what this test must change — new fields to assert, constraint details, auth changes, new request params, or any other drift specifics; \`skyramp_actions\` passes this directly to the downstream LLM editing the file), and \`renamedEndpoints\` (for path-rename updates).
-
-Call \`skyramp_actions\` as the sole final action — skip all other file writes.`;
-    const existingTestHeader = inlineMode
-        ? "### Existing tests (reported by skyramp_analyze_changes)"
-        : `### Existing tests (${existingTestCount} total)`;
-    const existingTestSection = `${existingTestHeader}
-For each existing test:
-- **IGNORE/VERIFY tests**: one line each: \`{testFile} — IGNORE\` or \`{testFile} — VERIFY\`. Rationale omitted for brevity.
-- **UPDATE/REGENERATE/DELETE tests**: output the full block:
+export function buildDriftOutputChecklist(stateFile, existingTests) {
+    const finalStep = `Call \`skyramp_actions\` with \`stateFile: "${stateFile ?? "<stateFile>"}"\` and a \`recommendations\` entry for every test assessed.`;
+    const hasTests = (existingTests?.length ?? 0) > 0;
+    const testList = hasTests
+        ? existingTests.map((t) => {
+            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`
+        : "";
+    const existingTestSection = `**Existing tests (${existingTests?.length ?? 0} total) — assess ALL of the following:**
+${testList}
+${noTestsNote}
+**UPDATE scope notes:**
+- UPDATE is an in-place edit — do not recommend creating a new file for an already-tested endpoint.
+- If a new HTTP method is added to a resource, emit a separate UPDATE entry for every existing test file that covers that resource (contract, integration, UI).
+
+For each test above, output one entry:
+- **IGNORE**: \`{testFile} — IGNORE: {reason the diff cannot reach this test's endpoint}\`
+- **VERIFY**: \`{testFile} — VERIFY: {uncertain element}\` — include in \`recommendations[]\` so it appears in the report for developer review
+- **UPDATE**:
+\`\`\`
+Test: {testFile}
+Action: UPDATE
+Rationale: UPDATE because {quoted diff signal}; affects {assertion/path}
+UpdateInstructions: {what must change in the existing file — specific fields, paths, status codes}
+\`\`\`
+- **REGENERATE**:
 \`\`\`
 Test: {testFile}
-Action: {UPDATE | REGENERATE | DELETE}
-Rationale: {1-2 sentence explanation}
-\`\`\`
-Focus your analysis on tests that need action — keep reasoning for unchanged tests to a single line.`;
-    const newEndpointSection = inlineMode
-        ? ""
-        : newEndpointCount > 0
-            ? `### New endpoints (${newEndpointCount} detected)
-For EACH new endpoint, output:
-\`\`\`
-Endpoint: {METHOD} {path}
-Action: ADD
-Test types: {contract | integration | smoke | ...}
-Rationale: {1 sentence}
-\`\`\``
-            : `### New endpoints
-No new endpoints detected in this diff.`;
-    const sections = [existingTestSection, newEndpointSection, finalStep].filter(s => s.length > 0);
+Action: REGENERATE
+Rationale: REGENERATE because {quoted diff signal}; every assertion is now invalid
+\`\`\`
+- **DELETE**:
+\`\`\`
+Test: {testFile}
+Action: DELETE
+Rationale: DELETE because {quoted diff signal}; all covered endpoints removed
+\`\`\`
+Include ALL actions — IGNORE, VERIFY, UPDATE, REGENERATE, DELETE — in the \`recommendations[]\` passed to \`skyramp_actions\`. For \`[external]\` tests: \`skyramp_actions\` will apply UPDATE edits and surface REGENERATE/DELETE as report-only findings.
+Be concise — one line per IGNORE/VERIFY entry.`;
+    const sections = [existingTestSection, finalStep];
     return `<output_format>
-## Output Checklist
-
 Complete ALL of the following:
 
 ${sections.join("\n\n")}
-Be brief. Decide the action for each test and apply edits immediately. Limit reasoning for IGNORE'd tests to a single line.
 </output_format>`;
 }

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

@@ -285,7 +285,7 @@ The ranked test recommendation catalog is pre-built and shown below (after the s
 2. Output the completed catalog **exactly as formatted — grouped by test type (### E2E / ### UI / ### Integration / ### Contract)**. Do NOT restructure, reorder, rename sections, or generate a new format.
 3. Do NOT call any Skyramp generation tools. The catalog shows ready-to-use tool calls that can be executed on demand.
 
-**If** Steps 1–2 revealed additional scenarios the catalog does not cover (e.g. a computed formula or FK relationship that was missed), you may optionally call \`skyramp_recommend_tests\` with \`stateFile: "${p.stateFile ?? p.sessionId}"\` and \`enrichedScenarios\` to regenerate a more complete catalog — but only after presenting the current one.`;
+**If** Steps 1–2 revealed additional scenarios the catalog does not cover (e.g. a computed formula or foreign-key relationship that was missed), you may optionally call \`skyramp_recommend_tests\` with \`stateFile: "${p.stateFile ?? p.sessionId}"\` and \`enrichedScenarios\` to regenerate a more complete catalog — but only after presenting the current one.`;
         const hasJavaFiles = p.candidateRouteFiles?.some((f) => /\.(java|kt)$/.test(f)) ?? false;
         const routeFilesSection = p.candidateRouteFiles && p.candidateRouteFiles.length > 0
             ? `\nRoute/controller files found by static scan (read these to discover endpoints — the regex-based catalog below may be incomplete for your framework):\n${p.candidateRouteFiles.map((f) => `- ${f}`).join("\n")}\n`

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

@@ -29,6 +29,7 @@ function _execCoverageBody(ctx) {
   5. **Unrelated endpoint coverage (last resort)**: Tests for endpoints with no connection to the PR diff, only when ALL options above have been exhausted.
   **Avoid backfilling with a test for a completely unrelated resource (e.g. \`POST /reviews\` when the PR only changes \`/orders\`) if any PR-endpoint edge-case integration test is feasible.**
 - **Contract tests (\`[skyramp]\`)**: If an existing \`[skyramp]\` contract test already covers that resource path → UPDATE the existing test file instead of creating a new one. A new test case is a new test even if the file already exists — count it toward \`newTestsCreated\`.
+- **\`[removed]\` endpoints**: If a GENERATE item targets an endpoint marked \`[removed]\` — the route was deleted in this PR, not renamed — generate a single contract test that asserts \`404 Not Found\`. Do not generate success-path (2xx) tests for removed endpoints. The purpose is a regression guard that catches the endpoint being accidentally re-added.
 - **Integration/scenario tests**: Always generate as a new file via the scenario pipeline, even if an existing integration test covers the same resource. A new multi-step scenario is a distinct test. Count it toward \`newTestsCreated\`.
 - **UI tests**: Always generate as a new file. Count toward \`newTestsCreated\`.`;
 }
@@ -72,7 +73,7 @@ If these conditions are not met, add it to ADDITIONAL only — do NOT displace a
 When a qualifying candidate is inserted: place it HIGH before MEDIUM before LOW; within the same priority, source-code-derived candidates go BEFORE structural ones. Re-number ranks after insertion. The top ${ctx.maxGen} ranked items become GENERATE candidates.
 
 **Source-code validation gates:**
-- **Cascade vs referential integrity**: If both a cascade-delete and a delete-blocked scenario appear for the same resource pair, keep only the one matching the source FK delete policy (ON DELETE CASCADE / cascade=True / onDelete: 'CASCADE' → keep cascade-delete; RESTRICT/PROTECT/no annotation → keep delete-blocked). Remove the inapplicable variant.
+- **Cascade vs referential integrity**: If both a cascade-delete and a delete-blocked scenario appear for the same resource pair, keep only the one matching the source foreign-key delete policy (ON DELETE CASCADE / cascade=True / onDelete: 'CASCADE' → keep cascade-delete; RESTRICT/PROTECT/no annotation → keep delete-blocked). Remove the inapplicable variant.
 - **Unique constraints**: Unique-constraint scenarios (duplicate POST → 409) are pre-drafted for all resources. Confirm enforcement before keeping: SQL UNIQUE index, Mongoose unique: true, Prisma @unique, or explicit duplicate-check code. If the backend is Redis, schema-less, or has no explicit constraint in the changed files, move to ADDITIONAL with a note — do NOT generate.`;
 }
 function _execDiversityBody(_ctx) {
@@ -94,7 +95,7 @@ For each pair of GENERATE items, ask: same HTTP method + path + step sequence +
 Same step sequence with only payload differences (e.g. 10% vs 5% discount both returning 200) = same code path = duplicate. Different scenario names do not make duplicate tests distinct.`;
 }
 function _execExecuteBody(ctx) {
-    return `Replace any scenario that pairs unrelated resources with one reflecting actual FK relationships in the codebase.
+    return `Replace any scenario that pairs unrelated resources with one reflecting actual foreign-key relationships in the codebase.
 Use the field names and values from the \`<source_evidence>\` blocks you quoted in Step ${EXEC_STEP_ENRICH} to fill all tool call parameters. Prefer reusing Step ${EXEC_STEP_ENRICH} evidence when it already resolves a placeholder, but if a placeholder cannot be replaced with concrete values from files already read, you may read the specific schema, model, or handler file needed to resolve it. Assert response field values, not just status codes.
 
 ${buildTestQualityCriteria()}
@@ -299,7 +300,7 @@ export function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValu
                 ? `authHeader: "${authHeaderValue}"${authSchemeSnippet}`
                 : "authHeader: <resolve from workspace or OpenAPI securitySchemes>; authScheme: <if Authorization>";
             const prereqNote = s.category === "new_endpoint"
-                ? `\n**Prerequisite discovery**: Check for FK fields (product_id, user_id, order_id) in the endpoint's request body. If found, prepend a step to create that prerequisite resource first, then chain its primary key field into the dependent step using template variable syntax. Check the actual field name from the response body (\`id\`, \`uuid\`, \`_id\`, etc.), response header (\`Location\`), or cookie — do not assume \`id\`.`
+                ? `\n**Prerequisite discovery**: Check for foreign-key fields (product_id, user_id, order_id) in the endpoint's request body. If found, prepend a step to create that prerequisite resource first, then chain its primary key field into the dependent step using template variable syntax. Check the actual field name from the response body (\`id\`, \`uuid\`, \`_id\`, etc.), response header (\`Location\`), or cookie — do not assume \`id\`.`
                 : "";
             const bugLine = s.bugCatchingTarget
                 ? `**Bug to catch**: ${s.bugCatchingTarget}\n`

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

@@ -50,7 +50,7 @@ Before each GENERATE tool call, confirm WHERE each key value comes from:
 - **requestBody / responseBody fields** → source code schema (Zod, Pydantic, DTO), enriched scenario, or OpenAPI spec. **The generation tool rejects empty \`{}\` request bodies for POST/PUT/PATCH** — read the source schema first if the fields are unknown.
 - **endpointURL** → workspace \`baseUrl\` + endpoint path (both required — never path alone)
 - **authHeader / authScheme** → workspace config or OpenAPI \`securitySchemes\`
-- **FK path params** → chained from a prior step's response (check the actual field name — it may be \`id\`, \`uuid\`, \`_id\`, or a resource-specific \`*_id\` field). The chaining source can be a response body (POST or GET), a response header (e.g. \`Location\`), or a cookie — not hardcoded
+- **Foreign-key path params** → chained from a prior step's response — never invented or hardcoded. Common field names: \`id\`, \`uuid\`, \`_id\`, \`*_id\`; use whatever identifier field the server returns for this resource. The chaining source can be a response body (POST or GET), a response header (e.g. \`Location\`), or a cookie.
 - **Names / string values** → realistic; append timestamp suffix to avoid re-run conflicts
 
 ## Ranking Rule
@@ -112,11 +112,11 @@ export function buildTestPatternGuidelines() {
 - **Middleware chains**: If auth/rate-limit/logging middleware exists, test the chain (e.g., rate limit hit → auth still checked → correct error returned)
 - **N+1 query risk**: If list endpoints join related data (e.g., orders with products), test with large datasets
 - **State machines**: If resources have status transitions (draft→published→archived), test invalid transitions (e.g., archived→draft should fail)
-- **Cascade deletes**: Only recommend after reading source code to confirm which resource holds the FK. The resource with the FK is the child; the one it points to is the parent. Example: if orders.product_id references products, then products is the parent — deleting a product tests whether orders are protected or cascade-deleted. Getting this backwards (treating the child as the parent) produces a nonsensical test.
+- **Cascade deletes**: Only recommend after reading source code to confirm which resource holds the foreign key. The resource with the foreign key is the child; the one it points to is the parent. Example: if orders.product_id references products, then products is the parent — deleting a product tests whether orders are protected or cascade-deleted. Getting this backwards (treating the child as the parent) produces a nonsensical test.
 - **Race conditions**: If concurrent writes are possible (inventory deduction, counter increment), test concurrent requests
 - **Computed fields**: If response contains derived values (total, average, count), verify computation with known inputs (e.g., total_cost = compute_seconds * rate + memory_mb * rate + external_cost)
 - **Mutation with collection modification**: If PUT/PATCH endpoints accept arrays of child items (e.g., order line items, cart products, invoice entries), test adding/removing items and verify that derived totals (e.g., total_amount, subtotal, item_count) are recalculated correctly. This is the most common source of user-reported bugs — always prioritize it for GENERATE over simple field-update tests.
-    The PATCH/PUT request body should include the child collection array field(s) defined for that endpoint (e.g., "items" with FK references like "product_id" and a quantity field) chained from prior POST responses. A PATCH that only sends metadata fields (e.g., discount_type, status, notes) without modifying the child collection is NOT a valid mutation-recalc test — it will pass even when the item/total logic is broken. Before writing assertions, inspect the source code or OpenAPI spec to identify (1) the actual child collection field name and its FK/quantity/price sub-fields, and (2) how derived totals are calculated (including any discounts, taxes, or fees). Then assert: the child FK fields match chained IDs, quantities match sent values, and totals match the computation from the source code
+    The PATCH/PUT request body should include the child collection array field(s) defined for that endpoint (e.g., "items" with foreign-key references like "product_id" and a quantity field) chained from prior POST responses. A PATCH that only sends metadata fields (e.g., discount_type, status, notes) without modifying the child collection is NOT a valid mutation-recalc test — it will pass even when the item/total logic is broken. Before writing assertions, inspect the source code or OpenAPI spec to identify (1) the actual child collection field name and its foreign-key/quantity/price sub-fields, and (2) how derived totals are calculated (including any discounts, taxes, or fees). Then assert: the child foreign-key fields match chained IDs, quantities match sent values, and totals match the computation from the source code
 - **Webhook/event side effects**: If endpoints trigger async operations, test that side effects occur (e.g., POST /orders triggers notification)
 - **Cross-user isolation**: If resources are owned by users, test that user B cannot access/modify user A's resources (GET /users/{other_id}/data → 403 Forbidden)
 - **Range/boundary invariants**: If business rules cap values (max retries, min balance, discount ≤ subtotal), test the boundary (e.g., set retries to max+1 → expect rejection)
@@ -130,7 +130,7 @@ that step B depends on (e.g., create product → create order referencing that p
 verify order contains correct product). Single-resource CRUD alone is not an integration test.
 Use actual field names and values from the source code schema or OpenAPI schema (not \`{}\` or invented field names); verify response data, not just status codes.
 When a PUT/PATCH updates a resource with child collections (e.g., order items), the request body
-MUST include the child array with FK references chained from prior steps — and assertions MUST
+MUST include the child array with foreign-key references chained from prior steps — and assertions MUST
 verify the actual child items in the response (product_id, quantity, unit_price), not just
 top-level metadata like discount or status.
 
@@ -184,7 +184,7 @@ Before finalizing your output, verify:
 6. **Real request shapes**: requestBody for POST/PUT/PATCH uses actual field names from source (not \`{}\`). GET search/filter uses \`queryParams\`, not \`requestBody\`.
 7. **scenarioFile**: \`skyramp_integration_test_generation\` uses the exact \`filePath\` returned by \`skyramp_batch_scenario_test_generation\` — not a guessed or hardcoded filename.
 8. **bugCatchingTarget**: Every GENERATE integration test that targets a business rule, formula, or constraint has a non-empty \`bugCatchingTarget\`.
-9. **FK chaining**: In multi-step integration tests, path params sourced from a prior step's response (e.g. \`order_id\` from step 1) use \`chainsFrom\` — not hardcoded IDs.
+9. **Foreign-key chaining**: In multi-step integration tests, path params sourced from a prior step's response (e.g. \`order_id\` from step 1) use \`chainsFrom\` — not hardcoded IDs.
 10. **Concrete scenario names**: No GENERATE item uses a placeholder name ending in a numeric suffix (e.g. \`ui-test-for-changed-component-1\`, \`ui-test-from-trace-2\`). Derive the name from the actual changed component or flow: if the diff touches \`LinkCard.tsx\`, the scenario name should be \`link-card-pin-toggle\` or \`link-card-edit-description\`, not \`ui-test-for-changed-component-1\`. The changed file list is available above — use it.
 11. **Issue coverage**: If \`<bug_found>\` blocks exist from Step ${codeReviewStepLabel} (Code Review), verify that the highest-severity flaw (HIGH or CRITICAL) has at least one GENERATE item directly targeting it (its pass/fail outcome depends on whether that bug exists). At most one promotion per run. If the promoted flaw lacks a dedicated GENERATE item, promote or create one before proceeding. Additional HIGH/CRITICAL flaws beyond the first should appear in ADDITIONAL at highest priority.
 12. **Code Review completeness**: Did you produce a \`<function_review>\` block for EVERY changed function/handler in Step ${codeReviewStepLabel}? If any function is missing a review, you skipped the correctness analysis for it. Go back and complete it before finalizing.
@@ -197,7 +197,7 @@ export function buildFewShotExamples() {
 **Parameter grounding**:
 - baseURL: "http://localhost:8000" (workspace api.baseUrl)
 - steps[0].requestBody fields "name", "price": ProductCreate schema fields (src/models/product.py)
-- steps[1].requestBody "product_id": FK to products — chained from step 0 response id
+- steps[1].requestBody "product_id": foreign key to products — chained from step 0 response id
 - steps[1].requestBody "quantity": OrderCreate schema field (src/models/order.py)
 - responseBody "total_amount": 89.97 = 29.99 × 3 — from order total formula (src/services/order_service.py: total = sum(item.price * item.quantity))
 - authHeader/authScheme: workspace config (Authorization / Bearer)

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

@@ -180,9 +180,11 @@ Use these exact numbers throughout the rest of the prompt.`;
 
 Budget Plan (total already determined): **${maxTotal} total (${effectiveGenerate} generate + ${additional} additional)**
 
+**Cosmetic-only override:** If, after code review, the entire diff is cosmetic with no observable rendering or interaction change (e.g. a \`.css\`/\`.scss\` reformat — property reordering, comment/whitespace edits, \`0px\`→\`0\`), the total above does NOT apply — set your Budget Plan to **0 total**, abstain (recommend and generate zero tests), and skip Step D below. A frontend file appearing in the diff is not, by itself, a behavior change. (Style changes that alter visibility, layout, or state are NOT cosmetic — keep the budget for those.)
+
 **Step D — Determine UI vs backend split for the budget above:**
 - Non-UI slots are backend tests; start from file-count ratio for UI%, then apply judgment:
-  - Pure CSS/style changes inflate the frontend file count without adding test value → reduce UI%
+  - Cosmetic CSS/style changes alongside real changes inflate the frontend file count without adding test value → reduce UI% (a whole-diff-cosmetic PR already abstained via the override above, so this only applies to the mixed-PR case)
   - Frontend logic bugs (state management, calculation errors, form validation) in the diff → increase UI% even if few frontend files
   - Frontend component calls a changed backend API → an E2E test covers both sides → count toward UI%
   - Frontend files only in \`__tests__/\` or \`.stories.\` → exclude from the ratio

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

@@ -299,6 +299,19 @@ describe("buildScopeAssessmentSection", () => {
         expect(section).not.toContain("Step B");
         expect(section).not.toContain("Step C");
     });
+    it("offers a cosmetic-only abstention override in the mixed-PR branch", () => {
+        // Regression: a CSS-only diff classifies as frontend (hasFrontendChanges=true),
+        // which previously handed the agent a fixed total with no path to zero tests,
+        // tanking d1 coverage to 0 (eval 14-cart-css-cleanup).
+        const section = buildScopeAssessmentSection(10, 3, false, undefined, true);
+        expect(section).toContain("Cosmetic-only override");
+        expect(section).toContain("0 total");
+        // The override is self-contained: it must NOT depend on a "Task 3" that
+        // doesn't exist in standalone (non-testbot) render contexts, and it must
+        // tell the agent to skip the now-irrelevant UI% step.
+        expect(section).not.toContain("Task 3");
+        expect(section).toContain("skip Step D");
+    });
     it("clamps additional to 0 when maxGenerate equals maxTotal (precomputed path)", () => {
         // maxGenerate=5, maxTotal=5 → additional must be 0, not negative
         const section = buildScopeAssessmentSection(5, 5, false, 0, false);