@skyramp/mcp 0.3.8 → 0.4.0-rc.1

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

@@ -1,12 +1,24 @@
 import { isContractConsumerModeEnabled } from "../../utils/featureFlags.js";
+import { sectionBody } from "../promptAssets.js";
+import { readPromptAsset } from "../promptAssets.js";
+import { fillPlaceholders } from "../../recommendation/verifierContracts.js";
 import { resolveServiceDetailsRef } from "../../utils/utils.js";
-import { WorkspaceAuthType, getAuthScheme, isAuthorizationHeaderName } from "../../utils/workspaceAuth.js";
+import { getAuthScheme, isAuthorizationHeaderName } from "../../utils/workspaceAuth.js";
 // Cached at module-load — flags are process-wide and cannot change per call.
 const CONSUMER_MODE_ENABLED = isContractConsumerModeEnabled();
 const SERVICE_REFS = resolveServiceDetailsRef();
-export const MAX_TESTS_TO_GENERATE = 3;
-export const MAX_RECOMMENDATIONS = 20;
-export const MAX_CRITICAL_TESTS = 3;
+// The instruction text lives in `plugin/prompts/generate-tests/`; this file reads
+// it back.
+// One read at module load: the files ship with the package and cannot change
+// under a running server.
+const GENERATION_MD = readPromptAsset("generate-tests/generation.md");
+// One sentence the run chooses between — the workspace auth shape, the contract
+// modes this build ships. Each half is its own section rather than a ternary
+// inside the sentence, so the whole instruction stays readable in the markdown.
+const TOOL_WORKFLOW_VARIANTS_MD = readPromptAsset("generate-tests/tool-workflow-variants.md");
+function variant(heading, values) {
+    return fillPlaceholders(sectionBody(TOOL_WORKFLOW_VARIANTS_MD, heading), values);
+}
 /**
  * Error string emitted by skyramp_integration_test_generation when both
  * an explicit authHeader and a workspace api.authType are passed simultaneously.
@@ -15,51 +27,24 @@ export const MAX_CRITICAL_TESTS = 3;
  */
 export const AUTH_CONFLICT_ERROR_MSG = "Auth header and auth type cannot be supported at the same time.";
 export function buildArchitectPreamble(isDiffScope) {
-    if (isDiffScope) {
-        return `You are acting as a Skyramp Integration Architect. You will receive a branch diff — changed endpoints, source code interactions, and existing tests. Your responsibility is to map test intent to the Skyramp generation spec with precision. No guessing — derive all parameters from the codebase, workspace config, and provided context only.
-
-Your task:
-1. **Recommend AND generate tests for this PR's changes** — prioritize tests most likely to catch real production bugs (state machine violations, cross-resource data integrity, computed field errors, security boundary bypasses) over trivial coverage
-2. **Immediately generate the top-priority tests** by calling Skyramp MCP generation tools — only these types: **integration, contract, E2E, UI**. Never smoke. Never fuzz.
-3. **Avoid duplicate coverage** — if an existing test already covers an endpoint + test type, choose a different angle instead
-
-Every tool parameter must trace to a concrete source: repository analysis, source code, or OpenAPI spec. Do not invent field names, request shapes, base URLs, or auth values. If a required value is unknown, read the relevant source file before calling the tool.`;
-    }
-    return `You are acting as a Skyramp Integration Architect. You will receive a full repository analysis — all endpoints, source code interactions, and existing tests. Your responsibility is to map test intent to the Skyramp generation spec with precision. No guessing — derive all parameters from the codebase, workspace config, and provided context only.
-
-Your task:
-1. **Produce a comprehensive test recommendation catalog** grouped by test type (E2E → UI → Integration → Contract), ranked by production risk within each type
-2. **Present each recommendation with a complete, ready-to-use Skyramp tool call** — fill in all field names, endpoint URLs, request shapes, and auth parameters from source code so the catalog is immediately actionable
-3. **Do not call any generation tools** — your output is the catalog itself; it is executed on demand
-
-Replace every \`<…from source>\` placeholder with actual values before presenting. Do not invent values — read the source file if a value is unclear.`;
+    // One preamble with two filled-in values, rather than a near-identical copy
+    // per scope: only the input it describes and the first task line differ.
+    return fillPlaceholders(sectionBody(GENERATION_MD, "## Architect preamble"), {
+        scopeInput: isDiffScope
+            ? "a branch diff — changed endpoints, source code interactions, and existing tests"
+            : "a full repository analysis — all endpoints, source code interactions, and existing tests",
+        scopeTask: isDiffScope
+            ? "Recommend AND generate tests for this PR's changes"
+            : "Decide which tests this repository is missing",
+    });
 }
 export function buildContextFetchingGuidance(sessionId) {
     if (!sessionId)
         return "";
-    return `<context_fetching_protocol>
-## Execution Plan Context
-Before calling any tool, replace every \`<from source>\` placeholder in the tool call parameters with actual values read from the relevant source file (handler, schema, or model). Do not proceed with placeholders still present — every parameter must trace to a concrete source.
-</context_fetching_protocol>`;
+    return readPromptAsset("generate-tests/context-fetching.md").trim();
 }
 export function buildReasoningProtocol() {
-    return `<reasoning_protocol>
-## Parameter Grounding Rule
-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\`
-- **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. Do NOT hardcode a timestamp/uuid suffix. Instead, for create fields that carry a UNIQUE constraint (e.g. \`name\`, \`slug\`, \`email\` — confirm from the source schema: \`unique=True\`, SQL \`UNIQUE\`, DTO), list their field paths in the step's \`uniqueFields\` (gjson notation) — the generator injects a run-unique value so re-runs don't 409.
-
-## Ranking Rule
-For each GENERATE item, include one sentence in your output (before the tool calls) stating the specific bug or failure it targets — derived from \`bugCatchingTarget\` or your source-code reading. Example: "Targets: order total miscalculation — total_amount = sum(item.price × item.quantity) should recompute when items array changes."
-
-If \`bugCatchingTarget\` is empty for a GENERATE item, derive it from source code before including the item. A GENERATE slot without a specific bug target belongs in ADDITIONAL.
-
-If a value cannot be sourced, read the relevant source file before calling the tool. Do not proceed with invented values.
-</reasoning_protocol>`;
+    return readPromptAsset("generate-tests/reasoning-protocol.md").trim();
 }
 function serializeAuthCallParams(params) {
     const parts = [`authHeader: "${params.authHeader}"`];
@@ -71,177 +56,26 @@ function serializeAuthCallParams(params) {
     }
     return parts.join(", ");
 }
-/**
- * Returns the authScheme snippet for a given authHeader + authType combination.
- *
- * Delegates scheme resolution to getAuthScheme() in workspaceAuth.ts — the single
- * source of truth — so this file no longer maintains its own slug→scheme table.
- */
-export function getAuthSnippets(authHeaderValue, authType, explicitScheme) {
-    if (!authHeaderValue) {
-        return { authSchemeSnippet: "", authTokenSnippet: "" };
-    }
-    // Only Authorization headers carry an authScheme prefix.
-    if (!isAuthorizationHeaderName(authHeaderValue)) {
-        return { authSchemeSnippet: "", authTokenSnippet: "" };
-    }
-    if (authType && authType !== WorkspaceAuthType.None) {
-        // Resolve via the canonical workspaceAuth mapping, passing explicit scheme if set.
-        const wsType = authType;
-        const scheme = getAuthScheme(wsType, explicitScheme);
-        // Use !== undefined so intentionally empty scheme ("" = raw token, no prefix) is preserved.
-        if (scheme !== undefined) {
-            return { authSchemeSnippet: `, authScheme: "${scheme}"`, authTokenSnippet: "" };
-        }
-    }
-    return { authSchemeSnippet: ', authScheme: "<scheme e.g. Bearer, Basic, Token or empty>"', authTokenSnippet: "" };
+/** Read whole, and by both callers: it is one instruction with no run fact in
+ *  it, so it has one home in the skill rather than a copy here. */
+export function buildPathParamGuidance() {
+    return readPromptAsset("generate-tests/path-parameters.md").trim();
 }
-export const PATH_PARAM_UUID_GUIDANCE = `**Path parameters:** keep the placeholder in \`endpointURL\` (e.g. \`/coupons/{coupon_id}\`). ` +
-    `Pass the value via \`pathParams\` (e.g. \`coupon_id=<random-uuid-v4>\`). ` +
-    `Use example values from the OpenAPI schema if available; otherwise generate a fresh random UUID v4 — not all-zeros or repeated-digit patterns.`;
 export function buildTestPatternGuidelines() {
-    return `### Test Pattern Guidelines
-
-#### Tier 1 — Base Patterns
-- CRUD lifecycle per resource group (Create → Read → Update → Delete)
-- Auth flow (Register → Login → Access protected → Token refresh → Logout)
-- Pagination & filtering (boundary values, empty results, large page sizes)
-- Error responses (400, 401, 403, 404, 409, 422 — each with a specific trigger)
-  **422 prerequisite:** Only recommend a 422 / missing-field test when you can confirm from source or schema that the field is **required**. In source, optional types such as \`Optional[str]\` or \`field?: T\` are not omission failures. In OpenAPI, omission is controlled solely by the parent schema's \`required\` list; \`nullable: true\` only permits an explicitly provided \`null\` value. Also verify the exact error body field name returned by the handler (e.g. \`detail\` in FastAPI, \`message\` in Express) before asserting a specific string like \`"missing"\` — the server may return a different key or value.
-
-#### Tier 2 — Code-Informed Patterns (higher value, look for these in source code)
-- **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 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 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)
-- **Breaking change migration**: If the diff renames a route, changes auth headers, or removes a required field, test both old path (should 404) and new path (should succeed)`;
+    return sectionBody(GENERATION_MD, "## Test pattern guidelines");
 }
 export function buildTestQualityCriteria() {
-    return `### What Makes a Good Test
-
-**Integration tests** should demonstrate cross-resource data flow — step A creates data
-that step B depends on (e.g., create product → create order referencing that product's ID →
-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 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.
-
-**Contract tests** (single-step) are the right choice for: error-handling scenarios on a single
-endpoint (e.g., PATCH/GET/DELETE a nonexistent resource → 404, POST with invalid payload → 422),
-validation boundary checks, and any test that exercises one endpoint's API contract in isolation.
-Do NOT add setup steps just to avoid hardcoding an ID — use a realistic hardcoded nonexistent ID
-(e.g., 99999 or a random UUID) and keep it a single-step contract test.
-
-**E2E tests** should follow realistic user journeys end-to-end: browse products → search →
-add to cart → checkout. Verify that frontend actions trigger the correct API calls and
-that the UI reflects backend state.
-
-**UI tests** should exercise component behavior and interaction flows: fill form → validate
-inputs → submit → see confirmation. Include visual state changes (loading, error, empty)
-and accessibility checks.`;
+    return sectionBody(GENERATION_MD, "## Test quality criteria");
 }
-export function buildGenerationRules(isUIOnlyPR) {
-    return `### Generation Guidelines
-
-**Available test types:** integration, contract, E2E, UI. **No smoke or fuzz tests.**
-Choose based on what adds the most value for this PR's changes.
-
-${CONSUMER_MODE_ENABLED ? `**Contract test mode — signal-based selection:**
-- **Consumer contract** (\`consumerMode: true\`): Look for outbound HTTP client code (fetch, axios, httpx, requests, http.Client), service client classes, or calls to external base URLs. If an endpoint's implementation makes downstream calls, that downstream boundary is a consumer contract test candidate.
-- **Provider contract** (\`providerMode: true\`): Look for new or modified endpoint handlers, route changes, or response shape modifications. If the diff adds/changes an endpoint this service owns, that is a provider contract test candidate.
-- **Both modes** (\`providerMode: true, consumerMode: true\`) — produces the same output as omitting both flags (generates provider and consumer contract tests). Use when the diff contains BOTH provider signals (new/modified endpoint handlers) AND consumer signals (outbound HTTP client calls to another service).` : `**Contract tests — provider-only:**
-Only provider-side contract tests are supported. Recommend a contract test (\`providerMode: true\`) when the diff adds or modifies an endpoint handler, route, or response shape that this service owns.`}
-
-**Scenario fidelity:** Every workflow scenario should reflect the actual resource
-relationships in the code. If the pre-drafted scenarios don't match the real data model,
-replace them with accurate ones.
-${isUIOnlyPR ? `
-**UI-only PR** — no backend changes. UI tests are most relevant.
-Use Playwright browser tools to auto-record traces and generate UI tests.
-` : `
-When no Playwright trace exists, use the Playwright browser tools (\`browser_navigate\`,
-\`browser_click\`, etc.) to record a trace, then export via \`skyramp_export_zip\` for UI tests.
-`}
-`;
+export function buildGenerationRules() {
+    return `${sectionBody(GENERATION_MD, "## Generation rules")}\n`;
 }
-export function buildVerificationChecklist(topN, maxGen, codeReviewStepLabel = "0") {
-    return `<verification>
-Before finalizing your output, verify:
-1. **Count**: Total recommendation count equals the total you stated in your Budget Plan (at most ${topN}). Your GENERATE + ADDITIONAL counts must match the split you committed to — neither fewer nor padded.
-2. **Distinct paths**: Each GENERATE item targets a distinct code path — no two share the same HTTP method + endpoint + expected status.
-3. **Auth parameters are consistent** across all tool calls (same authHeader and authScheme).
-4. Every endpointURL includes both the base URL and the path (not just the base, e.g. \`http://host/api/v1/orders/{id}\`).
-5. **All \`<from source>\` placeholders** you received have been replaced with actual values derived from source code — no \`<...>\` remain in your output.
-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. **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 every promoted flaw (HIGH or CRITICAL) has at least one GENERATE item directly targeting it (its pass/fail outcome depends on whether that bug exists). If a promoted flaw lacks a dedicated GENERATE item, promote or create one before proceeding. HIGH/CRITICAL flaws past the promotion bound Step ${codeReviewStepLabel} sets 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.
-13. **Requirement coverage**: If \`<requirement_conflict>\` blocks exist from Step ${codeReviewStepLabel} — a requirement the PR title/description (or a requirements file it references) states, which the implemented behavior contradicts — verify every promoted one has its OWN GENERATE item, category \`requirement_conflict\`, asserting the stated requirement and therefore failing on the current code. Requirement conflicts take the first slots of the promotion bound Step ${codeReviewStepLabel} sets, ahead of the \`<bug_found>\` flaws, so a run with one finding of each kind carries both tests. Where no such test is recordable, a VERIFY-style entry in \`additionalRecommendations\` ("the description and the implementation disagree — needs a developer decision, not a test edit") satisfies this instead. Every requirement conflict also has an \`issuesFound\` entry at severity \`high\` or above, attributed to its source. A conflict reported only as prose, with a passing test that asserts what the code does, fails this check.
-</verification>`;
+/** The checks on the test file itself, rendered at the moment it is written. */
+export function buildFinishChecks() {
+    return sectionBody(GENERATION_MD, "## Before you finish a test");
 }
-export function buildFewShotExamples() {
-    return `<examples>
-<example index="1" type="integration_recommendation">
-<thinking>
-**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": 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)
-</thinking>
-
-**#1 — GENERATE** | integration | business_rule | new
-Scenario: orders-create-with-product-total-calc (3 steps)
-  1. POST /api/v1/products → 201: Create product with known price
-  2. POST /api/v1/orders → 201: Create order referencing product_id from step 1, quantity=3
-  3. GET /api/v1/orders/{order_id} → 200: Verify total_amount = 29.99 × 3 = 89.97
-bugCatchingTarget: "total_amount = sum(item.price × item.quantity) — wrong if multiplication is skipped or items list is ignored"
-Tool calls:
-  skyramp_batch_scenario_test_generation({ scenarioName: "orders-create-with-product-total-calc", destination: "localhost", baseURL: "http://localhost:8000", authHeader: "Authorization", authScheme: "Bearer", steps: [
-    { method: "POST", path: "/api/v1/products", statusCode: 201, requestBody: "{\"name\": \"Widget-1713000000\", \"price\": 29.99}" },
-    { method: "POST", path: "/api/v1/orders", statusCode: 201, requestBody: "{\"product_id\": \"chained\", \"quantity\": 3}" },
-    { method: "GET", path: "/api/v1/orders/{order_id}", statusCode: 200, responseBody: "{\"id\": \"chained\", \"total_amount\": 89.97, \"items\": [{\"product_id\": \"chained\", \"quantity\": 3, \"unit_price\": 29.99}]}" }
-  ] })
-  skyramp_integration_test_generation({ scenarioFile: "<filePath returned by skyramp_batch_scenario_test_generation above>" })
-Reasoning: Catches a broken total calculation before it ships — the most common source of order-related bug reports.
-</example>
-
-<example index="2" type="contract_recommendation">
-<thinking>
-**Parameter grounding**:
-- endpointURL: "http://localhost:8000/api/v1/products/{product_id}" (workspace baseUrl + path from endpoint listing)
-- method: "DELETE" (route definition, uppercase)
-- pathParams "product_id=<random-uuid-v4>": hardcoded non-existent ID — no setup step needed for a 404 test; use a fresh UUID v4, not all-zeros
-- authHeader/authScheme: workspace config (Authorization / Bearer)
-- No requestData — DELETE carries no body
-</thinking>
-
-**#2 — GENERATE** | contract | error_handling | new
-DELETE /api/v1/products/{product_id} → 404
-Tool: skyramp_contract_test_generation({ endpointURL: "http://localhost:8000/api/v1/products/{product_id}", method: "DELETE", authHeader: "Authorization", authScheme: "Bearer", pathParams: "product_id=<random-uuid-v4>" })
-Reasoning: Catches a missing 404 guard on DELETE — verifies the handler returns 404 for non-existent resources rather than a 500 or silent no-op.
-</example>
-
-<example index="3" type="additional_recommendation">
-#5 [ADDITIONAL] | integration | security_boundary | existing
-  Scenario: orders-unauthorized-cross-user-access (POST /api/v1/orders → GET /api/v1/orders/{order_id} as different user → 403)
-  Validates: Cross-user isolation — user B cannot read user A's orders.
-</example>
-</examples>`;
+export function buildVerificationChecklist() {
+    return sectionBody(GENERATION_MD, "## Verification checklist");
 }
 export function buildToolWorkflows(authHeaderValue, authTypeValue = "", explicitScheme, enrichStepLabel = "2") {
     const isAuthorizationHeader = isAuthorizationHeaderName(authHeaderValue);
@@ -249,13 +83,7 @@ export function buildToolWorkflows(authHeaderValue, authTypeValue = "", explicit
     let authGuidance;
     let authParams;
     if (noAuth) {
-        authGuidance = `**Auth Verification Required:** The workspace config indicates no authentication, but you MUST verify this independently before omitting auth:
-1. **OpenAPI spec** \u2192 check \`securitySchemes\` / \`securityDefinitions\` for \`type: http\`, \`type: apiKey\`, or \`type: oauth2\`
-2. **Source code** \u2192 look for the auth middleware signals listed in Step ${enrichStepLabel} of the Execution Plan.
-3. **Route definitions** \u2192 check if routes have auth decorators or middleware applied
-4. **Still unknown** \u2192 proceed with \`authHeader: ""\` and note "auth pattern unrecognized" in your recommendation description.
-If you find auth requirements, pass the appropriate \`authHeader\` and \`authScheme\` to EVERY tool call. Only pass \`authHeader: ""\` if you confirm the API is truly unauthenticated.
-**NEVER invent auth header names.** Only use header names explicitly defined in route/middleware source code or derived from OpenAPI security schemes. For \`apiKey\` schemes with \`in: header\`, use the scheme's \`name\` value. For \`http\` bearer/basic schemes, use \`Authorization\`. Do not treat \`securitySchemes\` map keys as header names, and do not guess headers from naming conventions such as \`X-Admin-Key\`, \`X-API-Token\`, or \`X-Auth-Header\` unless that exact header is explicitly defined in source or schema.`;
+        authGuidance = variant("## Auth verification required", { enrichStep: enrichStepLabel });
         authParams = { authHeader: "" };
     }
     else if (isAuthorizationHeader) {
@@ -266,31 +94,18 @@ If you find auth requirements, pass the appropriate \`authHeader\` and \`authSch
             ? (getAuthScheme(wsType, explicitScheme) ?? "<scheme e.g. Bearer, Token or empty>")
             : "<scheme e.g. Bearer, Token or empty>";
         authParams = { authHeader: "Authorization", authScheme: resolvedScheme };
-        if (authTypeValue) {
-            authGuidance = `**Auth Scheme:** The workspace \`api.authType\` is \`"${authTypeValue}"\`.
-**Where to find the scheme** (check in order):
-1. **OpenAPI spec** \u2192 look at \`securitySchemes\` / \`securityDefinitions\` for \`type: http, scheme: bearer\` or \`type: apiKey\`
-2. **Source code** \u2192 the auth middleware signals listed in Step ${enrichStepLabel} of the Execution Plan
-3. **Workspace config** \u2192 use \`api.authType\` value as the scheme if source is inconclusive
-Pass the prefix as \`authScheme\` (e.g., \`"Bearer"\`, \`"Token"\`, \`"Basic"\`). If the API uses raw tokens with no prefix, pass \`authScheme: ""\`.
-**Do NOT guess the scheme.**
-To skip auth entirely, pass \`authHeader: ""\`.`;
-        }
-        else {
-            authGuidance = `**Auth Scheme:** No \`api.authType\` in workspace config.
-**Where to find the scheme** (check in order):
-1. **OpenAPI spec** \u2192 look at \`securitySchemes\` / \`securityDefinitions\` for \`type: http, scheme: bearer\` or \`type: apiKey\`
-2. **Source code** \u2192 the auth middleware signals listed in Step ${enrichStepLabel} of the Execution Plan
-3. **Fallback** \u2192 use \`"Bearer"\` only if the project clearly uses JWT or OAuth; otherwise pass \`authScheme: ""\`
-Pass the prefix as \`authScheme\` (e.g., \`"Bearer"\`, \`"Token"\`, \`"Basic"\`). If the API uses raw tokens with no prefix, pass \`authScheme: ""\`.
-**Do NOT guess the scheme.**
-To skip auth for unauthenticated endpoints, pass \`authHeader: ""\`.`;
-        }
+        // One ladder for both cases: only the first line differs, and step 3 states
+        // the workspace-type and no-workspace-type fallbacks side by side.
+        authGuidance = variant("## Auth scheme", {
+            enrichStep: enrichStepLabel,
+            authTypeLine: authTypeValue
+                ? `The workspace \`api.authType\` is \`"${authTypeValue}"\`.`
+                : "No `api.authType` in workspace config.",
+        });
     }
     else {
         authParams = { authHeader: authHeaderValue };
-        authGuidance = `**Auth Header:** \`${authHeaderValue}\` is a non-Authorization header — a placeholder token is auto-generated. Just pass \`authHeader\` — do NOT pass \`authScheme\` (it is only for Authorization headers and will be ignored).
-To skip auth for unauthenticated endpoints, pass \`authHeader: ""\`.`;
+        authGuidance = variant("## Auth header, not Authorization", { authHeader: authHeaderValue });
     }
     const hasWorkspaceAuthType = !!authTypeValue && authTypeValue !== "none";
     const authCallParams = serializeAuthCallParams(authParams);
@@ -298,79 +113,22 @@ To skip auth for unauthenticated endpoints, pass \`authHeader: ""\`.`;
     // has authType (workspace handles generation-time auth). Without authType, pass authHeader only.
     // NOTE: scenario generation always uses full authCallParams so auth is embedded in the test file
     // and the executor sends the correct Authorization header at run time.
-    const authHeaderOnlyParams = serializeAuthCallParams({ authHeader: authParams.authHeader });
     const integrationAuthNote = hasWorkspaceAuthType
-        ? `omit ALL auth params (passing auth alongside workspace authType causes "${AUTH_CONFLICT_ERROR_MSG}").`
-        : `pass \`${authHeaderOnlyParams}\` only (no \`authScheme\`, no \`authToken\`).`;
+        ? variant("## Integration auth, workspace handles it", { authConflictError: AUTH_CONFLICT_ERROR_MSG })
+        : variant("## Integration auth, header only", {
+            authHeaderOnlyParams: serializeAuthCallParams({ authHeader: authParams.authHeader }),
+        });
     const authHeaderLine = noAuth
-        ? `**No Auth (from workspace config):** Workspace indicates no authentication. **Verify independently** — if you find auth in the OpenAPI spec or source code, override with the correct \`authHeader\` and \`authScheme\`.`
-        : `**Auth params:** \`${authCallParams}\` — pass to EVERY tool call below.`;
-    return `## How to Generate Tests — Tool Workflows
-
-**Contract**: The following tool signatures are strict technical contracts. Every parameter should match the schema exactly. Omit optional parameters rather than guessing values. If a required field cannot be resolved, fetch context first.
-
-**Before every tool call**: Confirm WHERE each key value comes from — source code schema, enriched scenario, or OpenAPI spec. See Mandatory Reasoning Protocol above.
-
-${authHeaderLine}
-${authGuidance}
-
-**For multi-endpoint workflows (integration tests) — Batch Scenario → Integration pipeline:**
-1. Call \`skyramp_batch_scenario_test_generation\` with ALL steps in a single call: \`scenarioName\`, \`destination\`,
-   \`baseURL\`, \`${authCallParams}\`, and a \`steps\` array where each element has \`method\`, \`path\`, \`requestBody\` OR \`queryParams\`, \`responseBody\`, \`statusCode\`.
-   \`statusCode\` is optional for DELETE/GET/PUT/PATCH — defaults: DELETE→204 and GET/PUT/PATCH→200. For POST, always pass the confirmed \`statusCode\` explicitly after reading the handler, OpenAPI spec, existing test, or trace: resource-creation endpoints commonly return \`201\`, while action-style endpoints often return \`200\`.
-   **Action-style POST check:** Treat action verbs as path segments, not substrings. If the terminal path segment, or another clearly action-oriented segment, is a verb signalling an operation rather than resource creation (e.g. \`/run\`, \`/trigger\`, \`/execute\`, \`/deploy\`, \`/submit\`, \`/start\`, \`/stop\`, \`/cancel\`, \`/send\`, \`/publish\`, \`/process\`, \`/validate\`, \`/check\`, \`/apply\`, \`/retry\`), confirm the actual status code before setting \`statusCode\` — do NOT infer \`201\` from POST alone.
-   **OpenAPI spec is NOT required.** \`apiSchema\` is OPTIONAL — omit it if no spec exists.
-   **CRITICAL — Query params vs request body:**
-   - For **POST/PUT/PATCH**: use \`requestBody\` with realistic field values from source code schemas.
-   - For **GET/DELETE with search/filter/pagination**: use \`queryParams\`. Do not put query parameters in \`requestBody\` for GET requests — GET request bodies are non-standard and may be ignored or rejected.
-   - For **GET by ID**: no \`requestBody\` or \`queryParams\` needed — the ID is in the path.
-   \`responseBody\` should match the actual API response shape from source code (including all fields
-   returned by the controller — e.g., \`id\`, \`ownerId\`, \`createdAt\`, included relations like \`collection\`, \`tags\`).
-   Wrap in \`{"response": ...}\` if the API uses an envelope pattern. If omitted, a synthetic response is generated.
-   Inspect the source code to determine the correct request AND response body shapes — avoid sending \`{}\`.
-   **For PATCH/PUT mutation-recalc scenarios:** The request body should include the child
-   collection array (e.g. \`"items": [{"product_id": <chained from prior POST>, "quantity": 2}]\`).
-   Never send a PATCH that only modifies metadata (discount, status) without also including the
-   items/products collection — such a test will not catch collection-level or total-recalculation bugs.
-   For UNIQUE-constrained create fields, set the step's \`uniqueFields\` (gjson paths) rather than
-   hardcoding timestamp suffixes — the generator makes them run-unique so re-runs don't 409.
-   For every resource-creating step (POST/PUT), also add a matching DELETE step for the created
-   resource (path ID chained from the create response) so the scenario cleans up after itself.
-   For GET/PUT/DELETE with path IDs, use a placeholder — chaining resolves the real ID.
-2. Produces a \`scenario_<name>.json\` in the same \`outputDir\` as the test files (not \`.skyramp/\`).
-3. Call \`skyramp_integration_test_generation\` with \`scenarioFile\`: ${integrationAuthNote}
-   Do NOT pass \`chainingKey\` — defaults to \`response.id\`. After generation, the testbot
-   will verify and fix path param chaining in the generated test.
-
-**For single-endpoint tests (contract):**
-\`skyramp_{type}_test_generation\` with \`endpointURL\` (full URL incl. base + path), \`method\`,
-\`${authCallParams}\`, and \`requestData\` from source code schemas.
-If an OpenAPI spec exists, ALSO pass \`apiSchema\` — it enables schema-aware validation
-(contract tests verify response structure against the spec).
-Without a spec, \`endpointURL\` alone is sufficient.
-${PATH_PARAM_UUID_GUIDANCE}
-
-${CONSUMER_MODE_ENABLED ? `**Contract test mode selection — set based on this service's role at the boundary:**
-- \`providerMode: true\` — this service IS the API; validates the implementation matches the spec.
-  Use for new or modified endpoints this codebase owns.
-- \`consumerMode: true\` — this service CALLS another API; validates outbound requests conform to the downstream contract.
-  Use when the endpoint's implementation makes HTTP calls to external services (look for fetch/axios/httpx/http.Client/service clients).
-  A request-aware mock stands in for the real downstream service — no live dependency needed.
-- **Both modes** (\`providerMode: true, consumerMode: true\`) — same output as omitting both flags. Generates both consumer and provider contract tests. Use when the diff contains BOTH provider signals (new/modified endpoint handlers) AND consumer signals (outbound HTTP client calls to another service).` : `**Contract tests — provider-only:**
-Only provider-side contract tests are supported. Pass \`providerMode: true\` for new or modified endpoints this codebase owns.`}
-
-**For UI tests:**
-1. \`browser_navigate\` to the target URL (from workspace \`api.baseUrl\`)
-2. \`browser_snapshot\` to see the page (ARIA tree)
-3. Interact using \`browser_click\`, \`browser_type\`, \`browser_fill_form\`, etc.
-4. \`browser_snapshot\` after each interaction that changes the page
-5. \`skyramp_export_zip\` with an **absolute** output path: \`<repositoryPath>/.skyramp/<test_name>_trace.zip\`
-6. \`skyramp_ui_test_generation\` with \`playwrightInput\` = the **absolute** path of the exported zip, and \`outputDir\` = ${SERVICE_REFS.frontendTestDirRef} (e.g. \`frontend/tests\`). Do NOT use the backend service's testDirectory — UI tests must go in the frontend service's test directory.
-
-Tips: For custom dropdowns (Radix, MUI): click combobox → snapshot → click option (NOT \`browser_select_option\`).
-
-**For E2E tests (mixed PR — both backend and frontend changed):**
-Only generate when pre-existing backend trace \`.json\` AND Playwright \`.zip\` both exist in the repo.
-Use them directly with \`skyramp_e2e_test_generation\`.
-If traces are missing, skip E2E and add to \`additionalRecommendations\` with instructions to record them first.`;
+        ? variant("## Auth line, none configured", {})
+        : variant("## Auth line, configured", { authCallParams });
+    return fillPlaceholders(readPromptAsset("generate-tests/tool-workflows.md").trim(), {
+        authHeaderLine,
+        authGuidance,
+        authCallParams,
+        integrationAuthNote,
+        pathParamUuidGuidance: buildPathParamGuidance(),
+        frontendTestDir: SERVICE_REFS.frontendTestDirRef,
+        enrichStep: enrichStepLabel,
+        contractModeSelection: variant(CONSUMER_MODE_ENABLED ? "## Contract modes, consumer enabled" : "## Contract modes, provider only", {}),
+    });
 }

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

@@ -1,53 +1,25 @@
 /**
- * Shared dedup primitives used by both diff-mode (diffExecutionPlan.ts) and
- * full-repo mode (fullRepoCatalog.ts). Extracted here to avoid circular imports.
+ * Shared prompt primitives, kept out of the prompt modules that use them to
+ * avoid circular imports.
  */
-import { DraftedScenario } from "../../types/RepositoryAnalysis.js";
 /**
- * The one spelling of a coverage key, `METHOD::resource::testType`. Both
- * operands of the dedup comparison call it: a proposed test through
- * `externalDedupKeys`, and an existing test through `buildExternalCoverageSet`.
- * They used to build the same string in two places from two different inputs —
- * a typed step list on one side, regex-scraped prose on the other — so a fix to
- * one side left the other producing keys that could never match (SKYR-4214).
- */
-export declare function coverageKey(input: {
-    method: string;
-    path: string;
-    testType: string;
-}): string;
-/**
- * Method-aware coverage keys for external test dedup — one per recorded subject
- * endpoint. Method-aware so that an external test covering "GET /orders" does
- * not block a test for "PUT /orders", a different operation on the same
- * resource.
+ * Labels for a hand-written ordered list, taken from declaration order. Insert a
+ * key and every later label moves with it — and so does every reference built
+ * from the constant. A number counts up; a single letter walks the alphabet.
  *
- * A caller must remove a candidate ONLY when the coverage set holds EVERY key
- * returned here. Removing it on one match would discard the coverage of its
- * other endpoints. An empty list must never remove anything.
- */
-export declare function externalDedupKeys(scenario: DraftedScenario): string[];
-/**
- * Resource+type keys (no method) for the GENERATE/ADDITIONAL overlap filter —
- * one per recorded subject endpoint. Same rule as `externalDedupKeys`: remove
- * only on ALL keys, never on an empty list.
- */
-export declare function scenarioCoverageKeys(scenario: DraftedScenario): string[];
-export declare function isAttackSurfaceSecurityBoundary(scenario: DraftedScenario): boolean;
-export declare function isOrdinaryDirectAuthBoundary(scenario: DraftedScenario): boolean;
-/**
- * Build a set of coverage keys from external (non-Skyramp) tests.
- * Parses `testLocations` entries tagged with `[external]` to extract the
- * method-aware `METHOD::resource::testType` keys they cover.
+ * `PromptPlan` numbers the steps it also RENDERS. Use this for a list whose
+ * text is written by hand, where a plan's step headers would change the output.
  */
-export declare function buildExternalCoverageSet(testLocations: Record<string, string>): Set<string>;
-export declare const TASK_UI_PRESCAN = "0";
-export declare const TASK_ANALYZE_MAINTAIN = "1";
-export declare const TASK_GENERATE = "2";
-export declare const TASK_SUBMIT = "3";
-export declare const TESTBOT_TASK1_STEP_ANALYZE = "1";
-export declare const TESTBOT_TASK1_STEP_MAINTAIN = "2";
-export declare const TESTBOT_TASK1_STEP_CODE_REVIEW = "3";
-export declare const TESTBOT_TASK1_STEP_UI_GROUNDING = "4";
+export declare function orderedLabels<K extends string>(keys: readonly K[], start?: number | string): Record<K, string>;
+export declare const TASK_ANALYZE_MAINTAIN: string;
+export declare const TASK_GENERATE: string;
+export declare const TASK_SUBMIT: string;
+/** Top-level numbered steps of Task 1 ("Analyze & Maintain"). */
+export declare const TESTBOT_TASK1_STEP_LABELS: Record<"ANALYZE" | "MAINTAIN" | "CODE_REVIEW" | "UI_GROUNDING", string>;
+/** Lettered sub-steps of Task 1's "Maintain existing tests" step. */
+export declare const TESTBOT_TASK1_MAINTAIN_LABELS: Record<"CONFIRM_EXTERNAL" | "TEST_HEALTH" | "UPDATE_INSTRUCTIONS" | "BASELINE" | "APPLY_ACTIONS" | "VERIFY_EXTERNAL", string>;
+/** Lettered bullets of the multi-repo block inside Task 1's analyze step. */
+export declare const TESTBOT_TASK1_MULTIREPO_LABELS: Record<"REGISTER_SERVICES" | "ANALYZE_REPO" | "ON_FAILURE", string>;
 export declare const taskRef: (taskId: string) => string;
-export declare const taskStepRef: (taskId: string, stepId: string) => string;
+/** A lettered sub-step, spelled the way the prompt body spells it: `step 2(a)`. */
+export declare const stepSubRef: (stepId: string, subId: string) => string;