@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/prompts/local-dev/local-dev-plan.js

@@ -25,6 +25,7 @@ export const localDevPlan = new PromptPlan()
 })
     .step("ANALYZE_DIFF", "Analyze branch diff", (ctx) => `Call \`skyramp_analyze_changes\` with:
 - \`repositoryPath\`: "${ctx.repositoryPath}"
+- \`repository\`: "${ctx.repository}"
 - \`scope\`: "branch_diff"
 - \`baseBranch\`: "${ctx.baseCommit}"
 - \`includeUncommitted\`: true
@@ -64,7 +65,7 @@ service_name:
   interactions: [method, path, request shape, response shape]
 \`\`\`
 
-Downstream dependency handling must be explicit: HTTP/REST, gRPC, and Kafka dependencies can be mocked by Skyramp when selected for mocking. For unselected first-party/local services and infrastructure, use the real local service and document why it is real. For Kafka selected for mocking, call \`skyramp_mock_generation\` with \`protocol: "kafka"\`, \`endpointURL\` as broker \`host:port\`, and \`kafkaTopic\` as the topic name. The \`skyramp_execute_test\` tool handles execution and integration mock deployment from enriched test files.
+Downstream dependency handling must be explicit: HTTP/REST, gRPC, and Kafka dependencies can be mocked by Skyramp when selected for mocking. For unselected first-party/local services and infrastructure, use the real local service and document why it is real. For Kafka selected for mocking, call \`skyramp_mock_generation\` with \`protocol: "kafka"\`, \`endpointURL\` as broker \`host:port\`, and \`kafkaTopic\` as the topic name. An enriched test file applies its selected mocks when \`skyramp_execute_test\` runs it.
 
 **Auth discovery (do this NOW, not later):**
 - Read the endpoint's auth middleware/filters to understand the token format (e.g., Base64 of "client_id:secret", JWT, API key)
@@ -297,7 +298,7 @@ This injects import statements from the generated mock files — no data duplica
 - \`testType\`: "integration", "contract", or "ui" (match the scenario table)
 - \`enhanceType\`: "generation"
 
-The tool returns instructions — it does NOT edit the file automatically. Apply every returned instruction yourself: read the test file and add the suggested assertions. For assertions on server-generated IDs (e.g., account IDs, order IDs), prefer a domain prefix check (e.g., \`.startswith("acc_")\`) over \`is not None\` when the application uses a known ID format.`)
+The tool returns instructions — it does NOT edit the file automatically. Apply every returned instruction yourself: read the test file and add the suggested assertions.`)
     .step("CROSS_REFERENCE", "Cross-reference scenarios vs test files", (_ctx) => `Compare the scenario table from Phase 2 against the generated test files:
 
 1. For each generated scenario, verify a corresponding test file exists with the correct SCENARIO_NAME or generated test name.
@@ -366,39 +367,23 @@ To regenerate a single missing Kafka mock, call \`skyramp_mock_generation\` with
     headerLevel: "##",
     stepFormat: "hash",
 })
-    .step("EXECUTE_TESTS", "Execute tests via skyramp_execute_test MCP tool", (ctx) => `**You MUST use the \`skyramp_execute_test\` MCP tool for every test file.**
+    .step("EXECUTE_TESTS", "Execute tests via skyramp_execute_test MCP tool", () => `**Run every test file through the \`skyramp_execute_test\` MCP tool.** Give it the command that runs that one test file. The server records the run, and a run it did not record cannot appear in the report.
 
-**NEVER use any of these alternatives:**
-- \`skyramp execute test\` CLI command
-- Direct language runtimes (\`python3\`, \`pytest\`, \`node\`, \`npx jest\`, etc.)
-- Any shell command to run tests
-
-**If \`skyramp_execute_test\` is unavailable** (tool not found, MCP disconnected, or context compaction removed it): do NOT fall back to any direct runtime. Stop execution immediately, list the test files that could not be executed, and tell the user: "The skyramp_execute_test tool is unavailable. Please reconnect the Skyramp MCP server and re-run. Do not use pytest or any direct runtime — doing so bypasses mock deployment and Skyramp telemetry."
-
-The \`skyramp_execute_test\` MCP tool handles execution. For enriched integration tests, it runs the test in a container; the test's generated helper reads \`MOCK_SERVICES\`, clears stale mocks, and applies selected mocks before requests execute. Contract tests run without \`MOCK_SERVICES\`.
+\`skyramp_execute_test\` runs the command on this machine. The test reaches the SUT and the Skyramp worker through their published ports on \`localhost\`. For enriched integration tests, the test's generated helper reads \`MOCK_SERVICES\`, clears stale mocks, and applies selected mocks before requests execute. Contract tests run without \`MOCK_SERVICES\`.
 
 **Pre-execution gate:** Before every integration test execution, inspect the test file. If it does not contain \`MOCK_SERVICES\` and the language-specific apply helper (\`apply_all_mocks(client)\` for Python or \`applyAllMocks(client)\` for TypeScript/JavaScript/Java), or if it contains an empty \`MOCK_SERVICES\` collection for a scenario with downstream mocks, do NOT execute it. Call \`skyramp_enrich_test_with_mocks\` first and re-check the file. If \`MOCK_SERVICES\` is non-empty, execution is invalid until every real service selected for mocking is stopped.
 
 **No-hollow-pass gate:** Before executing any generated test, inspect it for unresolved placeholders or stub-only behavior. Do NOT execute or report PASS for files containing \`TODO\`, a standalone \`pass\` statement in a test body, \`NotImplemented\`, "replace with real consumer code", or executable consumer-contract code that calls the mocked endpoint directly without invoking application/consumer code. Skipped or strict xfail direct-mock reference stubs may remain only when a separate executable real consumer/SUT test exists; the skipped or strict xfail stub never counts as PASS. Strict xfail must fail the run on XPASS (for pytest, \`@pytest.mark.xfail(strict=True)\`). Fix the test or report the scenario as blocked.
 
-**Execution — one call per test file:**
-\`\`\`
-skyramp_execute_test({
-  testFile: "${ctx.repositoryPath}/tests/skyramp/<scenario>_test.py",
-  language: "<from workspace config>",
-  testType: "<'integration' or 'contract' — match the scenario table>",
-  workspacePath: "${ctx.repositoryPath}",
-  token: "",
-})
-\`\`\`
+**Execution — one \`skyramp_execute_test\` call per test file.**
 
-That's it. Pass \`token: ""\` so the executor injects \`SKYRAMP_TEST_TOKEN\` from the environment when auth is configured. For provider contract tests, omit \`contractMode\` or pass \`contractMode: "provider"\` so \`SKYRAMP_TEST_BASE_URL\` is injected. For consumer contract tests with inline mocks, pass \`contractMode: "consumer"\`. For integration tests, mock deployment is automatic because the enriched test helper reads \`MOCK_SERVICES\`, clears stale mocks, and applies them before exercising the service. Provider contract tests hit the service under test directly; consumer contract tests use any inline mocks generated in the contract test itself.
+For integration tests, mock deployment is automatic because the enriched test helper reads \`MOCK_SERVICES\`, clears stale mocks, and applies them before exercising the service. Provider contract tests hit the service under test directly; consumer contract tests use any inline mocks generated in the contract test itself.
 
 **On failure:**
 1. Read the error output to diagnose the root cause.
 2. "401 Unauthorized" → auth token missing or wrong. Do not hardcode a token into the test; pass the correct token through \`skyramp_execute_test.token\` or set \`SKYRAMP_TEST_TOKEN\` in the MCP execution environment, then retry once.
 3. "HTTP 500 / Internal Server Error" → the SUT is running but the API endpoint is not ready yet. This commonly happens with frameworks that compile routes lazily (Next.js, Vite) — the root page serves while new API routes added by the diff are still compiling. Do NOT immediately try a different test file — the same issue will affect all tests. Instead, wait 30 seconds, re-run the readiness gate against the API endpoint, and retry the SAME test. If HTTP 500 persists after 2 retries, check \`docker compose <composeFilePrefix> logs <sut-service>\` for startup errors.
-4. "Connection refused" → Skyramp worker not running or network mismatch. Run \`docker compose <composeFilePrefix> ps\` to verify the worker and SUT are running. If a stale port-forward or unrelated process holds the port, kill it and retry.
+4. "Connection refused" → the SUT or the Skyramp worker does not answer on its published port on \`localhost\`. Verify that the skyramp worker and the system under test are running and publishing their ports before retrying.
 5. Syntax/import error → fix the test file and retry **once**.
 6. Mock deployment error / "failed to get containers in network" → the Docker network does not exist or docker-compose did not start correctly. Re-run \`docker compose <composeFilePrefix> up -d\` and check \`docker compose <composeFilePrefix> logs\` for containers that crashed on startup. Do NOT delete mock imports, empty \`MOCK_SERVICES\`, or switch selected mocked downstreams to live Compose stubs just to get a green test. If the retry still fails, record \`status: "Fail"\` or blocked with the exact mock deployment error.
 7. **Timeout / no response** → if \`skyramp_execute_test\` does not return within the tool's timeout window, record \`status: "Timeout"\` with the test file path and do not retry automatically. Report to the user: the test may still be running or the worker may be unresponsive. Do not infer pass or fail from a timeout.

package/build/prompts/local-dev/local-dev-prompts.d.ts

@@ -1,4 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type Service } from "../../workspace/workspace.js";
-export declare function getLocalDevPrompt(baseCommit: string, repositoryPath: string, sandboxWorkerUrl?: string, maxRecommendations?: number, maxGenerate?: number, services?: Service[], stateOutputFile?: string, servicesToMock?: string[], realServices?: string[], mockProtocols?: string[], proxyKubeconfig?: string, proxyNamespace?: string): string;
+export declare function getLocalDevPrompt(baseCommit: string, repositoryPath: string, repository: string, sandboxWorkerUrl?: string, maxRecommendations?: number, maxGenerate?: number, services?: Service[], stateOutputFile?: string, servicesToMock?: string[], realServices?: string[], mockProtocols?: string[], proxyKubeconfig?: string, proxyNamespace?: string): string;
 export declare function registerLocalDevPrompt(server: McpServer): void;

package/build/prompts/local-dev/local-dev-prompts.js

@@ -3,7 +3,9 @@ import * as path from "path";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { buildServiceContext, escapeXml, readWorkspaceServices, } from "../prompt-utils.js";
-import { localDevPlan, GRPC_SERVICE_NAME_GUIDANCE, ASSERTION_API_GUIDANCE } from "./local-dev-plan.js";
+import { localDevPlan, GRPC_SERVICE_NAME_GUIDANCE, ASSERTION_API_GUIDANCE, } from "./local-dev-plan.js";
+import { tryRepositorySlug } from "../../utils/repositorySlug.js";
+import { setPrimaryRepository } from "../../utils/AnalysisStateManager.js";
 const LOCAL_DEV_MAX_RECOMMENDATIONS = 8;
 const LOCAL_DEV_MAX_TESTS_TO_GENERATE = 5;
 /**
@@ -37,7 +39,7 @@ function buildServiceRoutingBlock(servicesToMock, realServices, mockProtocols) {
     lines.push("</SERVICE_ROUTING>");
     return lines.join("\n");
 }
-export function getLocalDevPrompt(baseCommit, repositoryPath, sandboxWorkerUrl, maxRecommendations = LOCAL_DEV_MAX_RECOMMENDATIONS, maxGenerate = LOCAL_DEV_MAX_TESTS_TO_GENERATE, services, stateOutputFile, servicesToMock, realServices, mockProtocols, proxyKubeconfig, proxyNamespace) {
+export function getLocalDevPrompt(baseCommit, repositoryPath, repository, sandboxWorkerUrl, maxRecommendations = LOCAL_DEV_MAX_RECOMMENDATIONS, maxGenerate = LOCAL_DEV_MAX_TESTS_TO_GENERATE, services, stateOutputFile, servicesToMock, realServices, mockProtocols, proxyKubeconfig, proxyNamespace) {
     maxGenerate = Math.min(Math.max(maxGenerate, 0), maxRecommendations);
     const serviceContext = services?.length ? buildServiceContext(services) : "";
     // Proxy access lets the workflow query a running Skyramp worker proxy for real
@@ -85,7 +87,7 @@ ${sandboxWorkerBlock ? sandboxWorkerBlock + "\n" : ""}${serviceContext ? service
 - **Mock URL format** — the \`endpointURL\` in \`skyramp_mock_generation\` MUST use the original Docker service hostname (e.g., \`http://identity-service:4000\`, \`http://profile-service:50052\`). The Skyramp executor uses DNS alias hijacking — it takes over the service's DNS name on the Docker network so the service under test's requests are intercepted transparently. NEVER use \`localhost\`, \`127.0.0.1\`, \`0.0.0.0\`, \`host.docker.internal\`, or the worker address as the mock URL. For REST mocks, \`skyramp_preflight_mock_check\` returns blocking \`REST_LOOPBACK_URL\` when a deployable mock uses these hosts.
 - **REST mock routing** — Generated REST mock files may contain a fallback \`URL\` value such as \`http://localhost:8080\`; do not manually edit those files. The enrichment tool uses the mock generation \`# Command\` target to set each REST mock's \`mock.url\` back to the original Docker service origin before \`apply_mock()\`. If the command target is loopback, regenerate the mock with the original service hostname.
 - **gRPC mock routing** — gRPC mocks may target the real downstream service port (e.g., \`partner-accounts:50051\`). Apply gRPC mocks before the SUT starts or restart the SUT after applying them, and verify the Skyramp worker has the original endpoint host alias from \`endpointURL\` (\`partner-accounts\`, not the protobuf service name like \`PartnerAccountsService\`).
-- **Execution** — ALWAYS use \`skyramp_execute_test\` MCP tool to run tests. NEVER use direct language runtimes (\`python3\`, \`pytest\`, \`node\`, \`npx jest\`, etc.) or Skyramp CLI commands.
+- **Execution** — prefer \`skyramp_execute_test\` over running the repository's test runner yourself: the server records the run, and a run it did not record cannot appear in the report. Give it the command for one test file.
 - **Generated test hardening** — before execution, make generated tests rerunnable and assertion-rich: use \`int(os.getenv("SKYRAMP_WORKER_PORT", "35142"))\` instead of a hardcoded worker port, keep auth token lookup environment-only (\`os.getenv("SKYRAMP_TEST_TOKEN")\`) with no literal fallback token in test source; pass the discovered token via \`skyramp_execute_test.token\` or the MCP server \`SKYRAMP_TEST_TOKEN\` environment before execution, use \`json.dumps({...})\` for JSON request bodies instead of f-string triple-quoted strings, use unique data for persistent DBs (UUID-suffixed emails/names), access \`ResponseV2\` via \`.status_code\` for status — ${ASSERTION_API_GUIDANCE}. Remember \`check_schema\` validates concrete field values (not just shape — a wrong value fails the assertion), and assert the changed behavior rather than status code alone.
 - **Outbound validation** — when a scenario's value depends on what the SUT sends to a downstream service, keeping that downstream real produces the most reliable test (see the Recommend Scenarios phase for details). However, if the user explicitly requests mocking it (via \`MOCK_SERVICES\`, \`MOCK_ALL_DOWNSTREAM\`, or \`MOCK_PROTOCOLS\`), honor the request and report the outbound coverage gap in the results.
 - **No hollow green tests** — unresolved placeholders (\`TODO\`, a standalone \`pass\` statement in a test body, \`NotImplemented\`, or "replace with real consumer code") and executable consumer-contract stubs that call only the mock are blocking defects. Skipped or strict xfail direct-mock reference stubs are allowed only when paired with a separate executable real consumer/SUT test. Implement the missing application/consumer call or report the scenario blocked; do not execute or report it as PASS.
@@ -101,6 +103,7 @@ ${sandboxWorkerBlock ? sandboxWorkerBlock + "\n" : ""}${serviceContext ? service
     // ── Render the plan phases ────────────────────────────────────────────────
     const ctx = {
         repositoryPath,
+        repository,
         baseCommit,
         maxRecommendations,
         maxGenerate,
@@ -167,13 +170,37 @@ export function registerLocalDevPrompt(server) {
         },
     }, async (args) => {
         const services = await readWorkspaceServices(args.repositoryPath);
+        // skyramp_analyze_changes and skyramp_execute_test both name their repository
+        // on every call. This is a local checkout, so read it off the origin remote.
+        const repository = await tryRepositorySlug(args.repositoryPath);
+        if (!repository) {
+            return {
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: `Cannot read owner/repo from the origin remote of ${args.repositoryPath}. The Skyramp tools name the repository on every call, so add an origin remote to this checkout and retry.`,
+                        },
+                    },
+                ],
+            };
+        }
+        // Rendering the prompt is where this run declares its primary checkout, the
+        // same as the testbot entry point. Set, not set-if-unset: one server can
+        // render a second run for a different checkout, and keeping the first would
+        // route the second one as a related repository of it.
+        setPrimaryRepository({
+            repositoryPath: args.repositoryPath,
+            repo: repository,
+        });
         const parseCsv = (v) => v
             ? v
                 .split(",")
                 .map((s) => s.trim())
                 .filter(Boolean)
             : undefined;
-        const prompt = getLocalDevPrompt(args.baseCommit, args.repositoryPath, args.sandboxWorkerUrl, args.maxRecommendations, args.maxGenerate, services.length ? services : undefined, args.stateOutputFile, parseCsv(args.servicesToMock), parseCsv(args.realServices), parseCsv(args.mockProtocols), args.proxyKubeconfig, args.proxyNamespace);
+        const prompt = getLocalDevPrompt(args.baseCommit, args.repositoryPath, repository, args.sandboxWorkerUrl, args.maxRecommendations, args.maxGenerate, services.length ? services : undefined, args.stateOutputFile, parseCsv(args.servicesToMock), parseCsv(args.realServices), parseCsv(args.mockProtocols), args.proxyKubeconfig, args.proxyNamespace);
         AnalyticsService.pushMCPToolEvent("skyramp_local_dev_prompt", undefined, {}).catch(() => { });
         return {
             messages: [

package/build/prompts/modularization/integration-test-modularization.js

@@ -49,13 +49,16 @@ expect(response1.status).toBe(200);
 const response2 = await fetch("/api/users/2");
 expect(response2.status).toBe(200);
 
-// Correct helper (EXACT copy + parameters${p.utilsReuse ? "; the expected status is a defaulted parameter per HELPER SHAPE" : ""}):
+// Correct helper (EXACT copy + parameters${p.utilsReuse ? "; the expected status is a parameter with NO default per HELPER SHAPE — each call passes it, and the test body does not assert it again" : ""}):
 ${p.utilsReuse
-    ? `async function getUser(userId: number, expectedStatus = 200) {
+    ? `async function getUser(userId: number, expectedStatus: number) {
   const response = await fetch(\`/api/users/\${userId}\`);
   expect(response.status).toBe(expectedStatus);
   return response;
-}`
+}
+// Call sites: the status each one expects, stated once, here.
+const response1 = await getUser(1, 200);
+const response2 = await getUser(2, 200);`
     : `async function getUser(userId: number) {
   const response = await fetch(\`/api/users/\${userId}\`);
   expect(response.status).toBe(200);
@@ -101,12 +104,16 @@ If ANY answer is "no", DO NOT submit - fix the modularization first.`)
 function sharedHelperShape(p) {
     return `**HELPER SHAPE (one helper per request step from Step ${_plan.labels.IDENTIFY}):**
 - ${API_HELPERS.namingRule}
-- **PARAMETERS**: pass in the client/session object, plus every value the step reads from a previous step's response (IDs used in paths or bodies), plus every body value this scenario varies or its assertions reference (names, prices, quantities, percentages). Values that never vary and that no assertion reads may stay hardcoded — do not invent parameters nothing passes differently.
-- **SCENARIO VALUES GO THROUGH \`data_override\`, NOT THE BODY STRING**: apply each parameterized body value via the request's \`data_override\` map (that is what it is for) and leave the raw body string as generated. A scenario literal edited into the body string makes this helper unmergeable with the same step from another test.
+- **PARAMETERS**: pass in the client/session object, plus every value the step reads from a previous step's response (IDs used in paths or bodies), plus every body value this scenario varies or its assertions reference (names, prices, quantities, percentages). Values that never vary and that no assertion reads may stay hardcoded — do not invent parameters nothing passes differently. The body is the one exception: it is reachable from the signature whether or not this scenario varies it (see the body rule below).
+- **SCENARIO VALUES GO THROUGH \`data_override\`, NOT THE BODY STRING**: apply each parameterized body value via the request's \`data_override\` map (that is what it is for) and leave the raw body string as generated. A scenario literal edited into the body string makes this helper unmergeable with the same step from another test. The generated body is this helper's STARTING POINT, not a fixed value — the body rule below says what must be able to change about it.
 - **RETURN** the response object so later steps can chain and assert from it.
 - ${API_HELPERS.assertionRule} ${ASSERTION_BOUNDARY_RULE_EXTRACT}
 - Helpers are module-level named functions in ${p.filePath}; the test body becomes a sequence of helper calls plus this scenario's assertions, in the original order.
-- Keep everything else EXACTLY the same.`;
+- Keep everything else EXACTLY the same.
+
+${API_HELPERS.bodyShapeRule}
+
+${API_HELPERS.optionsShapeRule}`;
 }
 function repetitionParameterRules() {
     return `**PARAMETER CONVERSION RULES:**

package/build/prompts/modularization/ui-test-modularization.js

@@ -138,7 +138,7 @@ await addItem(page, "item3");
 \`\`\``)
     .step("USE", "CALL HELPERS WITH EXACT SAME VALUES", () => `Use the EXACT same values from the original test when calling helpers.`)
     .step("VERIFY", "VERIFY - CRITICAL CHECKS", (p) => `**BUGS TO AVOID:**
-- [ ] **EVERY PARAMETER IS TYPED (TypeScript)** - \`page: Page\` with \`import type { Page } from '@playwright/test'\` once at the top of the file; other parameters by their value type (\`name: string\`, \`quantity: number\`). An untyped parameter fails a repo that type-checks its tests under \`noImplicitAny\`. JavaScript files carry no annotations.
+- [ ] **EVERY PARAMETER IS TYPED (TypeScript)** - \`page: Page\` with \`import type { Page } from '@playwright/test'\` once at the top of the file; other parameters by their value type (\`name: string\`, \`quantity: number\`). An untyped parameter fails a repo that type-checks its tests under \`noImplicitAny\`; a parameter typed \`unknown\` fails at its first use under every setting, and \`any\` checks nothing — use the real type. JavaScript files carry no annotations.
 - [ ] **Return types are optional** - inferred returns are fine under strict mode; if you write one, it is the real type, never \`any\`
 - [ ] **ALL field mappings verified** - EVERY \`.fill()\` uses the correct parameter. Check field gets quantity parameter, NOT hardcoded
 - [ ] **No duplicate helpers** - Consolidate similar helpers (e.g., one createOrder vs createSimpleOrder + createOrderWithItems)

package/build/prompts/personas.js

@@ -20,5 +20,5 @@ export const SKYRAMP_QA_PERSONA = `You are acting as a Skyramp QA Automation Eng
  * avoid duplicating it in every tool description.
  */
 export function getPersonaPrefix() {
-    return isTestbotEnabled() ? '' : `${SKYRAMP_QA_PERSONA}\n\n`;
+    return isTestbotEnabled() ? "" : `${SKYRAMP_QA_PERSONA}\n\n`;
 }

package/build/prompts/pom-aware-code-reuse.js

@@ -1,12 +1,16 @@
 import { generateSkyrampHeader, SKYRAMP_UTILS_HEADER } from "../utils/utils.js";
 import { resolvePomCatalogPath } from "../utils/pom-catalog.js";
+import { UTILS_LANGUAGE_SPECS } from "../utils/utils-verify/language-spec.js";
+import { SELECTOR_OWNING_MODULE_RULE } from "./shared-helper-policy.js";
 export function getPomAwareCodeReusePrompt(testFile, language = "typescript", scopedPoms) {
     // Resolved here, not left to the agent: the catalog only survives to the next
     // run if it lands where delivery stages it (SKYR-4141).
     const catalogPath = resolvePomCatalogPath(testFile);
     const isJs = language.toLowerCase() === "javascript";
     const ext = isJs ? "js" : "ts";
-    const utilsFile = isJs ? "skyrampUtils.js" : "skyrampUtils.ts";
+    // Same one declaration the standard path reads, so the two prompts and the verify
+    // pass cannot name three different files.
+    const utilsFile = UTILS_LANGUAGE_SPECS[isJs ? "javascript" : "typescript"].fileName;
     const codegenMarker = "// Generated by Skyramp v";
     const headerLang = isJs ? "javascript" : "typescript";
     const scopedActive = scopedPoms && scopedPoms.tier1.length + scopedPoms.tier2.length > 0;
@@ -44,13 +48,7 @@ Use the Glob tool to search for POM files starting from the directory containing
 - Pattern 7: \`**/{test,tests,e2e,playwright}/**/{lib,utils,helpers,support}/**/*.{ts,js}\`
 - Pattern 8: \`**/{testUtils,test-utils,testHelpers,test-helpers}.{ts,js}\`
 
-**A reuse target does not have to be a class.** Patterns 7–8 catch selector-owning helper
-libraries — modules exporting free functions like \`bookFirstEvent(page)\` whose bodies contain
-the selector literals. A helper module qualifies only if its functions OWN selectors; a module
-whose functions take selectors as parameters (generic interaction utilities) owns nothing and is
-not a reuse target. Playwright fixture factories wired into the repo's own \`test\` object
-(\`test.extend\`-style) are NOT substitutable either — using them requires replacing the Skyramp
-runtime imports, which rule 3a forbids.
+${SELECTOR_OWNING_MODULE_RULE} (See rule 3a below.) Patterns 7–8 are what catch such libraries.
 
 Exclude test/spec files by **basename only** — never match on the directory path. POM layers commonly live under a \`tests/\` directory (e.g. \`tests/ui-testing/pages/\`), and path-matching would wrongly drop every POM. A file is excluded only if its **basename** ends in \`.spec.ts\`, \`.spec.js\`, \`.test.ts\`, or \`.test.js\`. Do NOT exclude on the bare substrings \`test\` or \`spec\`: they falsely match legitimate POMs (e.g. \`searchJobInspectorPage.js\` contains "spec") and directory names (\`tests/\`).
 Also exclude \`node_modules\`.
@@ -559,7 +557,7 @@ For each helper defined locally in ${testFile}:
 
 - **Conservative bias**: a wrong merge breaks both tests; a missed merge leaves a duplicate. When in doubt, do NOT merge.
 - **No "cleanup"**: the merged body must mirror the original primitive sequence — same waits, same correlation patterns, same order. This is not refactoring.
-- **Typed parameters (TypeScript)**: the merged helper types every parameter (\`page: Page\`, values by their type); add \`import type { Page } from '@playwright/test'\` if the file lacks it. Never \`page: any\` or an untyped \`page\`.
+- **Typed parameters (TypeScript)**: the merged helper types every parameter (\`page: Page\`, values by their type); add \`import type { Page } from '@playwright/test'\` if the file lacks it. Never \`page: any\`, \`page: unknown\`, or an untyped \`page\`.
 - **Don't merge with helpers already in \`${utilsFile}\`**: those are STEP 3's territory. STEP 4b is strictly cross-test merge between sibling Skyramp-generated test files.
 
 ---

package/build/prompts/reuse-hand-off.d.ts

@@ -0,0 +1,64 @@
+import { TestType } from "../types/TestTypes.js";
+import { type UtilsLanguage } from "../utils/utils-verify/index.js";
+/**
+ * The generation-call clause that asks for codeReuse, language-conditional in
+ * words, as the testbot prompt appends it to its integration generation step
+ * when utils reuse is on.
+ *
+ * States the RULE, not one exception. Naming Java as the only language left out
+ * is false — code reuse covers three languages and discovery records seventeen —
+ * and an agent in a Go repository reads "unset for Java", concludes Go is not
+ * excepted, and asks for a reuse pass that can move no helpers for Go.
+ */
+export declare const CODE_REUSE_GENERATION_CLAUSE: string;
+/**
+ * Whether the maintenance step can actually rewrite a test of this type. Its
+ * REGENERATE strategy names the integration and contract generators only and
+ * forbids skyramp_ui_test_generation, which needs a recorded trace this tool does
+ * not have. A browser test's REGENERATE is therefore advice to the developer: no
+ * call here rewrites the file, so nothing may be armed against it — a hand-off
+ * would refuse the execution of a file the plan never told anyone to rewrite.
+ */
+export declare function isMaintenanceRegenerable(testType: TestType): boolean;
+/**
+ * What the regenerate instruction asks of the generation call, as words for the
+ * summary (`clause`) and as the arguments the structured plan carries (`args`),
+ * from one decision. Undefined when the call must not ask for code reuse: utils
+ * reuse off, or a test type that is not a modularize-first target — contract, for
+ * one, whose generator accepts neither `codeReuse` nor `modularizeCode`. For a
+ * modularize-first type: the resolved clause and arguments for a language with a
+ * utils spec; the leave-unset clause and no arguments for Java; the generic clause
+ * and no arguments when the language is not cataloged.
+ */
+export declare function regenerateCodeReuse(testType: TestType, 
+/** Optional because the discovery catalog does not always carry one: an
+ *  uncataloged but real test file is accepted deliberately, and its language is
+ *  unknown. The clause is omitted in that case. */
+language: string | undefined): {
+    clause: string;
+    args?: {
+        codeReuse: true;
+        modularizeCode: false;
+    };
+} | undefined;
+/**
+ * Whether a test of this type and language owes the modularize → reuse pair.
+ * Routing (isModularizeFirstTarget) says which flows modularize first; the utils
+ * spec says which languages have a payable reuse half — recordReuseHandOff writes
+ * nothing for a language without one (Java), so instructing the pair there would
+ * be a debt nothing tracks.
+ */
+export declare function isModularizeFirstHandOffTarget(testType: TestType, 
+/** Optional because generation's own `language` param is: the predicate is the
+ *  thing that decides an absent or unsupported language owes nothing. */
+language: string | undefined): language is UtilsLanguage;
+/** The argument clause of the skyramp_reuse_code call the agent is told to make. */
+export declare function reuseCodeArgsClause(language: string | undefined, testType: TestType, framework: string): string;
+export declare function buildModularizeFirstNextSteps(params: {
+    testType: TestType;
+    /** Narrowed by isModularizeFirstHandOffTarget, which both callers apply
+     *  first: a language with no utils spec never reaches these steps. */
+    language: UtilsLanguage;
+    framework: string;
+    enhanceFirst: boolean;
+}): string;

package/build/prompts/reuse-hand-off.js

@@ -0,0 +1,130 @@
+/**
+ * The modularize → reuse hand-off, shared by the two places that arm the chain:
+ * generation (TestGenerationService, for the files a codeReuse call wrote) and
+ * maintenance (skyramp_actions, for a test it updates or regenerates). One
+ * predicate decides whether a file owes the pair, and one builder produces the
+ * next-steps text, so the two callers cannot drift on either.
+ */
+import { isUtilsReuseEnabled } from "../utils/featureFlags.js";
+import { fillPlaceholders } from "../recommendation/verifierContracts.js";
+import { readPromptAsset, sectionBody } from "./promptAssets.js";
+import { isBrowserTestType, isModularizeFirstTarget, } from "../utils/reuseRouting.js";
+import { utilsSpecFor, } from "../utils/utils-verify/index.js";
+import { enhanceAssertionsCall } from "../skills/enhanceAssertionsSkill.js";
+/** Why Java generation never asks for codeReuse. */
+const CODE_REUSE_JAVA_REASON = "cross-file helpers do not compile in the test executor";
+/** Why every other unsupported language is left out. Java has its own reason
+ *  above; a language the shared-helper verifier does not cover is left out
+ *  because nothing can check the module it would write. Naming Java's reason for
+ *  a Go or Ruby test would be a false statement about that file. */
+function codeReuseUnverifiableReason(language) {
+    return `the shared-helper verifier has no rules for ${language}`;
+}
+/**
+ * The generation-call clause that asks for codeReuse, language-conditional in
+ * words, as the testbot prompt appends it to its integration generation step
+ * when utils reuse is on.
+ *
+ * States the RULE, not one exception. Naming Java as the only language left out
+ * is false — code reuse covers three languages and discovery records seventeen —
+ * and an agent in a Go repository reads "unset for Java", concludes Go is not
+ * excepted, and asks for a reuse pass that can move no helpers for Go.
+ */
+export const CODE_REUSE_GENERATION_CLAUSE = `, setting \`modularizeCode: false\` and \`codeReuse: true\` for TypeScript, JavaScript and Python, and leaving \`codeReuse\` unset for any other language (for Java, ${CODE_REUSE_JAVA_REASON}; for the rest, ${codeReuseUnverifiableReason("them")})`;
+/**
+ * Whether the maintenance step can actually rewrite a test of this type. Its
+ * REGENERATE strategy names the integration and contract generators only and
+ * forbids skyramp_ui_test_generation, which needs a recorded trace this tool does
+ * not have. A browser test's REGENERATE is therefore advice to the developer: no
+ * call here rewrites the file, so nothing may be armed against it — a hand-off
+ * would refuse the execution of a file the plan never told anyone to rewrite.
+ */
+export function isMaintenanceRegenerable(testType) {
+    return !isBrowserTestType(testType);
+}
+/**
+ * What the regenerate instruction asks of the generation call, as words for the
+ * summary (`clause`) and as the arguments the structured plan carries (`args`),
+ * from one decision. Undefined when the call must not ask for code reuse: utils
+ * reuse off, or a test type that is not a modularize-first target — contract, for
+ * one, whose generator accepts neither `codeReuse` nor `modularizeCode`. For a
+ * modularize-first type: the resolved clause and arguments for a language with a
+ * utils spec; the leave-unset clause and no arguments for Java; the generic clause
+ * and no arguments when the language is not cataloged.
+ */
+export function regenerateCodeReuse(testType, 
+/** Optional because the discovery catalog does not always carry one: an
+ *  uncataloged but real test file is accepted deliberately, and its language is
+ *  unknown. The clause is omitted in that case. */
+language) {
+    if (!isUtilsReuseEnabled())
+        return undefined;
+    if (!isMaintenanceRegenerable(testType))
+        return undefined;
+    if (!isModularizeFirstTarget(testType, language))
+        return undefined;
+    // No cataloged language: nothing records a hand-off for the file and no
+    // arguments are emitted for it, so a clause asking the agent to set
+    // codeReuse: true would ask for a call the structured plan does not — the very
+    // split that carrying the options on the entry closed. Say nothing instead.
+    if (!language)
+        return undefined;
+    return utilsSpecFor(language)
+        ? {
+            clause: ", setting `modularizeCode: false` and `codeReuse: true`",
+            args: { codeReuse: true, modularizeCode: false },
+        }
+        : {
+            clause: `, and leave \`codeReuse\` unset (${language.toLowerCase() === "java" ? CODE_REUSE_JAVA_REASON : codeReuseUnverifiableReason(language)}),`,
+        };
+}
+/**
+ * Whether a test of this type and language owes the modularize → reuse pair.
+ * Routing (isModularizeFirstTarget) says which flows modularize first; the utils
+ * spec says which languages have a payable reuse half — recordReuseHandOff writes
+ * nothing for a language without one (Java), so instructing the pair there would
+ * be a debt nothing tracks.
+ */
+export function isModularizeFirstHandOffTarget(testType, 
+/** Optional because generation's own `language` param is: the predicate is the
+ *  thing that decides an absent or unsupported language owes nothing. */
+language) {
+    return (isModularizeFirstTarget(testType, language) && !!utilsSpecFor(language));
+}
+/** The argument clause of the skyramp_reuse_code call the agent is told to make. */
+export function reuseCodeArgsClause(language, testType, framework) {
+    return `\`testFile\` set to the absolute path of the generated test file, \`language: "${language}"\`, \`testType: "${testType}"\`${framework ? `, and \`framework: "${framework}"\`` : ""}`;
+}
+/**
+ * The CRITICAL NEXT STEPS block: modularize, then reuse (whose returned steps end
+ * in the verify call). `enhanceFirst` prepends the assertion enhancer — browser
+ * tests generated with enhanceAssertions run it on the raw file, before the
+ * selectors move into the utils file. Maintenance never sets it: the update
+ * strategy calls the enhancer after the edit, and the block says the pair runs
+ * before it.
+ */
+const HAND_OFF_MD = readPromptAsset("code-reuse/hand-off.md");
+/** One section of the hand-off markdown, by heading, with its placeholders
+ *  filled. The markdown is the single source of this instruction text. */
+function handOffStep(heading, values) {
+    return fillPlaceholders(sectionBody(HAND_OFF_MD, `## ${heading}`), values);
+}
+export function buildModularizeFirstNextSteps(params) {
+    const { testType, language, framework, enhanceFirst } = params;
+    const enhanceCall = enhanceAssertionsCall(testType, "generated test file");
+    const values = {
+        testType,
+        reuseArgs: reuseCodeArgsClause(language, testType, framework),
+        enhanceCall: enhanceCall.charAt(0).toUpperCase() + enhanceCall.slice(1),
+    };
+    const steps = [
+        ...(enhanceFirst ? [handOffStep("Enhance first", values)] : []),
+        handOffStep("Modularize", values),
+        handOffStep("Reuse", values),
+    ];
+    const ordering = handOffStep(enhanceFirst
+        ? "Ordering with the enhancer"
+        : "Ordering without the enhancer", values);
+    return `⏭️**CRITICAL NEXT STEPS — ${ordering}**:
+${steps.map((text, i) => `${String.fromCharCode(97 + i)}. ${text}`).join("\n")}`;
+}

package/build/prompts/shared-helper-policy.d.ts

@@ -1,6 +1,70 @@
+/**
+ * Where a test states the status it expects: ONCE, as the argument of the helper
+ * call. The helper asserts it (that is the shared invariant), so the policy has to
+ * say what the spec contains after that — left unsaid, the agent left the status
+ * behind a defaulted parameter the call omitted, or asserted it a second time on the
+ * response the helper returned. Quoted by the prompt and by the two verify findings
+ * (`status-default`, `status-restated`) that enforce it, so the sentence the agent
+ * reads is the sentence the gate returns.
+ */
+export declare const STATUS_ONCE_RULE: {
+    /** Written as the ACTION to take and the helpers it applies to. A first version
+     *  said the parameter "carries NO default" in the present tense; quoted beside a
+     *  finding that showed `expected_status=201`, it read as a description that was
+     *  false about the very line it quoted, and the advisory was acted on 0 of 9 times. */
+    readonly noDefault: "Give every helper THIS RUN WRITES its expected status as a required parameter: no default value, not optional. A call site that can omit the status hides the expectation, so every call site passes the status it expects. A helper that already exists at HEAD keeps the signature it has, default included — never remove an incumbent's default, since callers this run cannot see rely on it; a call site this run writes still passes the status explicitly, whether or not the helper would default it. A helper whose status NEVER varies may assert the literal instead of taking a parameter at all: what this rule forbids is a DEFAULT, which lets a call site silently inherit an expectation it never stated, and a pinned literal no caller can vary hides nothing. Give it a parameter the moment a second call site needs a different status. Declare the expected-status parameter BEFORE any parameter that carries a default: Python refuses `def create_product(client, headers, body=DEFAULT_BODY, expected_status)` with `SyntaxError: non-default argument follows default argument`, and a module that does not import takes every test in the file with it at collection.";
+    readonly notRestated: "the test body does not assert the status again on the response the helper returns — the helper asserted it, and the call's status argument is the one statement of it";
+};
 /** Why the assertion rule exists — quoted wherever the rule is stated. */
 export declare const SHARED_HELPER_WHY = "A scenario-specific assertion inside a helper carries one scenario's data into a shared function and fails the next scenario that calls it \u2014 the helper is shared, the claims are not.";
-export declare const BROWSER_STRUCTURAL_WAITS = "`waitForResponse`, `waitForLoadState`, `waitFor({ state: \"visible\" })`, and `toBeVisible` on a STRUCTURAL locator (a test id, or a role + name of a control) \u2014 a check that an element rendered, not what it says";
+/**
+ * What a shared helper of one family may assert — the ONE declaration.
+ *
+ * Every statement of the rule is rendered from here: the prompt sentence the agent
+ * reads, the per-language predicate the verify pass runs, and the violation message
+ * the gate returns. They disagreed before — the prompt permitted one matcher, the
+ * gate accepted eight, and the message repeated the gate's reading — so a value
+ * assertion could sit in a delivered helper, pass the gate and reach the customer
+ * with nothing reported. Widening or narrowing a family is an edit to one array.
+ *
+ * The api family's permitted assertion is not a matcher list (it is a status-code
+ * comparison whose RECEIVER decides: `expect(res.status)` yes, `expect(res.body.status)`
+ * no), so `permittedMatchers` is empty for it and its predicate stays hand-written.
+ * Stating its list here is what SKYR-4318 does; it edits this table, and the gate
+ * reads the table, so no second mechanism is needed for it.
+ */
+export interface HelperAssertionPolicy {
+    /** Matcher names permitted inside a shared helper, in the camelCase spelling.
+     *  Empty when the family's rule is not expressible as a matcher list. */
+    permittedMatchers: readonly string[];
+    /** Matchers the family refuses. Named rather than implied: the boundary reads as
+     *  a rule the agent can apply, not as a list it must invert. */
+    refusedMatchers: readonly string[];
+    /** The sentence that states the boundary, quoted VERBATIM by the prompt and by the
+     *  gate's violation message. One string, so a reader who follows the message and a
+     *  reader who follows the prompt are told the same thing. */
+    boundary: string;
+}
+/**
+ * ARIA roles whose accessible name is the page's own CONTENT rather than a control's
+ * label. A locator built from one of these plus a name selects by what the page SAYS,
+ * which is the scenario's data: `getByRole("heading", { name: "Your cart is empty!" })`
+ * is the scenario's outcome wearing a structural locator.
+ *
+ * A DENY-list, not an allow-list. The rule blocks a customer's run, so a role nobody
+ * has listed has to pass — an allow-list refused `getByRole("dialog", { name })`, which
+ * is an ordinary wait for a named modal and is permitted everywhere else.
+ */
+export declare const CONTENT_ROLES: readonly ["heading", "paragraph", "cell", "gridcell", "columnheader", "rowheader", "row", "listitem", "definition", "term", "img", "figure", "article", "note", "tooltip", "alert", "log", "marquee", "timer", "blockquote", "caption", "option", "menuitem", "menuitemcheckbox", "menuitemradio", "treeitem"];
+/** Spoken once, quoted everywhere. */
+export declare const BROWSER_ASSERTION_BOUNDARY: string;
+export declare const HELPER_ASSERTION_POLICIES: Record<"api" | "browser", HelperAssertionPolicy>;
+/** The WAIT FORMS a shared browser helper may use. It deliberately stops short of
+ *  what a structural locator is: the boundary states that, once, and this clause is
+ *  rendered beside it. A second summary of the locator rule was a second rule to keep
+ *  equal, and it fell behind the boundary the first time the boundary gained an
+ *  exception. */
+export declare const BROWSER_STRUCTURAL_WAITS: string;
 /**
  * Relocation never reorders execution. Two variants, because the two ends of the
  * chain may do different things with a helper whose value assertion sits BETWEEN
@@ -9,7 +73,13 @@ export declare const BROWSER_STRUCTURAL_WAITS = "`waitForResponse`, `waitForLoad
  */
 export declare const ASSERTION_BOUNDARY_RULE_EXTRACT = "Relocation must preserve the original order: an assertion that sits BETWEEN two actions is a HELPER BOUNDARY \u2014 end the helper before it and start the next helper after it (each named per the naming rule), so the assertion sits between the two calls in the test body exactly where it was. Never move an assertion across an action.";
 export declare const ASSERTION_BOUNDARY_RULE_MOVE = "Relocation must preserve the original order: only a TRAILING assertion (after the helper's last action) may move to the test body right after the call. A helper whose excluded assertion sits BETWEEN two actions is NOT moved and NOT split \u2014 leave it local in the test file; splitting is modularization's job, not this step's.";
-export declare const BROWSER_VALUE_ASSERTIONS = "any `expect` whose matcher OR locator carries scenario data: `toHaveText`, `toContainText`, `toHaveValue`, `toHaveCount`, `toHaveURL` with a literal, or ANY matcher \u2014 `toBeVisible` included \u2014 on a locator that embeds scenario text such as `getByText(\"Total: $899.98\")`";
+export declare const BROWSER_VALUE_ASSERTIONS: string;
+/**
+ * What qualifies as a browser reuse target — stated once, read by the page-object
+ * prompt and by the in-house search on the shared-module path, so the two cannot
+ * disagree about which of the customer's modules the run may call.
+ */
+export declare const SELECTOR_OWNING_MODULE_RULE = "**A reuse target does not have to be a class.** Selector-owning helper libraries qualify \u2014 modules exporting free functions like `bookFirstEvent(page)` whose bodies contain the selector literals. A helper module qualifies only if its functions OWN selectors; a module whose functions take selectors as parameters (generic interaction utilities) owns nothing and is not a reuse target. Playwright fixture factories wired into the repo's own `test` object (`test.extend`-style) are NOT substitutable either \u2014 using them requires replacing the Skyramp runtime imports, which is forbidden.";
 /**
  * A helper kept local must never share a name with a utils export — the import
  * and the local definition would then describe two different behaviours under
@@ -43,8 +113,60 @@ export interface HelperPolicy {
     namingExample: string;
     /** "One X = one helper" closing line for a utils file. */
     oneHelperRule: (fileName: string) => string;
+    /**
+     * What may carry a difference in WHAT THE STEP SENDS between two call sites of
+     * one operation — the request body for API helpers; for browser helpers, why
+     * the question does not arise. Stated once here because both ends of the
+     * modularize -> reuse chain decide it: modularization shapes the helper, reuse
+     * merges a second caller into it, and a helper shaped so it cannot carry the
+     * second caller sends that caller off to write its own copy.
+     */
+    bodyShapeRule: string;
+    /**
+     * How the request's options object is built in a language that types it — one
+     * literal at the call, optional fields inline. Empty when the kind issues no
+     * request (browser helpers). Rendered beside `bodyShapeRule` at both ends of
+     * the chain for the same reason it is.
+     */
+    optionsShapeRule: string;
     /** Kind-specific near-duplicate / merge section for STEP 4b of code reuse. */
     nearDupRules: (fileName: string) => string;
+    /**
+     * An inline copy of a step is a CALL SITE for the helper that already performs
+     * it, never a helper to author — stated in the kind's own terms (a request block
+     * against a route; an action sequence against an action key) and rendered where
+     * the reuse pass meets inline code: the current test (STEP 3) and the sibling
+     * pass (STEP 5c). Without it the pass moved helpers and left every inline copy
+     * where it was, naming the copy in its own report (measured three cohorts
+     * running on the browser side).
+     */
+    inlineCallSiteRule: string;
+    /** The words the reuse prompt needs to state that rule's steps without branching
+     *  on the kind: what an inline copy is called and how STEP 5c finds, replaces and
+     *  follows up one. */
+    inlineSite: {
+        /** Singular, lower case: `inline request block` / `inline action sequence`. */
+        noun: string;
+        /** Plural, sentence case, for a sentence or heading start. */
+        nouns: string;
+        /** The one-word unit a step refers back to: `block` / `sequence`. */
+        unit: string;
+        /** What STEP 3 says the rule applies to in the current test. */
+        stepNoun: string;
+        /** STEP 3's heading clause for a kind whose helpers may be extended in place;
+         *  empty when the merge rule beside it already says so. */
+        extendClause: string;
+        /** STEP 5c's match criterion for a sibling's copy. */
+        match: (fileName: string) => string;
+        /** What STEP 5c replaces a copy with, for its heading. */
+        target: (fileName: string) => string;
+        /** What happens to a literal the matched helper does not take. */
+        lift: (fileName: string) => string;
+        /** What the replacement leaves verbatim in the sibling. */
+        keeps: string;
+        /** Steps STEP 5c adds after the replacement; empty when none. */
+        afterSteps: string;
+    };
     /**
      * Replacement for the generic STEP 4b worked example when helpers are headed
      * to the shared file. Empty string → no example beyond the kind's own section.