@skyramp/mcp 0.3.6-rc.2.ac20 → 0.3.7

package/build/adapters/jestAdapter.js

@@ -1,4 +1,3 @@
-import * as path from "path";
 /**
  * Shared jest + vitest adapter for skyramp_run_existing_tests. vitest's json
  * reporter is jest-compatible, so both use ONE parser; only the reporter flag
@@ -41,7 +40,6 @@ export function parseJestJson(report, opts) {
             results.push({
                 testId: `${name} › (file failed to run)`,
                 file: name,
-                ...(path.isAbsolute(name) ? { absoluteFile: name } : {}),
                 status: "error",
                 message: stripVTControlCharacters(raw).trim() || undefined,
                 durationMs: 0,
@@ -57,7 +55,6 @@ export function parseJestJson(report, opts) {
             results.push({
                 testId: `${name} › ${titlePath}`,
                 file: name,
-                ...(path.isAbsolute(name) ? { absoluteFile: name } : {}),
                 status,
                 message,
                 durationMs: Math.round(a.duration ?? 0),

package/build/adapters/mochaAdapter.js

@@ -1,4 +1,3 @@
-import * as path from "path";
 /**
  * Mocha adapter for skyramp_run_existing_tests. Normalizes `mocha --reporter
  * json` (emitted to stdout) into the neutral shape. Mocha does not tag
@@ -30,7 +29,6 @@ function toResult(t, status) {
     return {
         testId: `${file} › ${full}`,
         file,
-        ...(path.isAbsolute(file) ? { absoluteFile: file } : {}),
         status,
         message: status === "fail" || status === "error" ? messageOf(t) : undefined,
         durationMs: Math.round(t.duration ?? 0),

package/build/adapters/playwrightAdapter.js

@@ -12,7 +12,6 @@
  * builds the flags appended to the suite's `testRunCommand`. The IO shell that
  * actually spawns the run lives in `runExistingTestsTool`.
  */
-import * as path from "path";
 import { stripVTControlCharacters } from "util";
 /**
  * A Playwright project (or spec file) is "infra" when it exists to bring up /
@@ -68,7 +67,6 @@ function messageOf(test) {
 }
 export function parsePlaywrightJson(report, opts) {
     const rep = (report ?? {});
-    const rootDir = rep.config?.rootDir;
     const collected = [];
     for (const fileSuite of rep.suites ?? []) {
         collectSpecs(fileSuite, fileSuite.file ?? "", [], collected);
@@ -120,7 +118,6 @@ export function parsePlaywrightJson(report, opts) {
             results.push({
                 testId,
                 file,
-                ...(rootDir ? { absoluteFile: path.resolve(rootDir, file) } : {}),
                 status,
                 message: status === "fail" || status === "error" ? messageOf(test) : undefined,
                 durationMs,

package/build/adapters/pytestAdapter.js

@@ -1,4 +1,3 @@
-import * as path from "path";
 /**
  * pytest adapter for skyramp_run_existing_tests. Normalizes the
  * `pytest-json-report` (`--json-report`) output into the neutral result shape.
@@ -40,8 +39,6 @@ function durationMsOf(test) {
 export function parsePytestJson(report, opts) {
     const rep = (report ?? {});
     const tests = rep.tests ?? [];
-    const root = rep.root;
-    const abs = (f) => (root ? { absoluteFile: path.resolve(root, f) } : {});
     // Real test outcomes.
     const testResults = tests.map((t) => {
         const status = mapOutcome(t.outcome);
@@ -49,7 +46,6 @@ export function parsePytestJson(report, opts) {
         return {
             testId: nodeid,
             file: fileOf(nodeid),
-            ...abs(fileOf(nodeid)),
             status,
             message: status === "fail" || status === "error" ? messageOf(t) : undefined,
             durationMs: durationMsOf(t),
@@ -65,7 +61,6 @@ export function parsePytestJson(report, opts) {
         return {
             testId: `${nodeid} › (collection error)`,
             file: fileOf(nodeid),
-            ...abs(fileOf(nodeid)),
             status: "error",
             message: lastLine(c.longrepr),
             durationMs: 0,
@@ -77,13 +72,6 @@ export function parsePytestJson(report, opts) {
     // When collection failed AND no real test ran, the suite as a whole could not be
     // collected — environmental (a wall of red), not PR signal. When some real tests
     // DID run, the collection errors above stand as ordinary PR-signal error results.
-    // NOTE: a collection error names the file that failed to import, but says nothing
-    // about WHY. A missing settings module, a database that is down or any shared
-    // dependency failure surfaces per-module, landing on exactly the files the run
-    // selected — indistinguishable here from a file the PR itself broke. So a run that
-    // collected nothing stays unhealthy even when scoped, and the file keeps its
-    // Unknown baseline. Treating it as PR signal would let an environment outage be
-    // reported as a test the change broke, and then repaired.
     if (collectionErrors.length > 0 && testResults.length === 0) {
         environmentHealthy = false;
         const first = collectionErrors[0];

package/build/prompts/code-reuse.js

@@ -55,7 +55,7 @@ export async function uploadFileToRFI(page, fileName, tabName) {
 These ARE near-duplicates. Same primitive sequence; the only material difference is the \`.first()\` qualifier on the locator. \`tabName\` is unused in the body — recorder noise, drop it. Correct merge:
 
 \`\`\`ts
-export async function uploadFileViaChooser(page, fileName) {
+export async function uploadFileViaChooser(page: Page, fileName: string) {
     await page.waitForTimeout(1500);
     const responsePromise = page.waitForResponse("**/api/files/upload**");
     const fileUploadPromise = page.waitForEvent("filechooser");
@@ -69,6 +69,15 @@ export async function uploadFileViaChooser(page, fileName) {
 
 Both test files import and call \`uploadFileViaChooser(page, fileName)\`.`;
 }
+/** Every step that authors an import of the shared module states this: STEP 4b
+ *  merges, STEP 5b seeds, STEP 5c rewires a sibling — and a run with no siblings
+ *  jumps straight to 5b, so a rule living in one step only is skippable. The
+ *  verifier is deterministic, so a skipped rule is a failed run. */
+const pyImportRule = (fileName) => {
+    const stem = fileName.replace(/\.[^.]+$/, "");
+    return `**Import form (Python)**: if the test's directory contains \`__init__.py\`, a bare \`from ${stem} import …\` will NOT resolve when the customer runs pytest from their repo root — the test dies at collection. Write the fallback pair, which works there AND in the Skyramp executor: \`try:\` / \`    from .${stem} import …\` / \`except ImportError:\` / \`    from ${stem} import …\` — with \`…\` the names this test actually uses, unchanged between the two arms. Without \`__init__.py\` the bare form alone is correct — do not add the fallback.`;
+};
+const pyImportRuleLine = (fileName) => `- ${pyImportRule(fileName)}`;
 export function getCodeReusePrompt(testFile, language, framework, scopedPoms, testType) {
     const lang = language.toLowerCase();
     if (isPomAwareTarget(lang, framework, testType)) {
@@ -111,6 +120,8 @@ export function getCodeReusePrompt(testFile, language, framework, scopedPoms, te
 
 skyramp_modularization already ran on ${testFile} and extracted its steps into named helper functions. Those helpers belong in the shared \`${fileName}\` so later tests import them instead of re-defining them.
 
+${pyImportRuleLine(fileName)}
+
 For each helper function still defined locally in ${testFile} (i.e. not already merged by STEP 4b):
 1. **CREATE** \`${fileName}\` if it does not exist, with the standard header:
    \`\`\`${ext}
@@ -148,6 +159,8 @@ This step MOVES helpers that skyramp_modularization already created — it does
 
 **Run this step EVEN IF STEP 3 already satisfied ${testFile} and STEPS 4–5b did nothing.** ${inlineRequestRule}
 
+${pyImportRuleLine(fileName)} (this applies to the import you add to the SIBLING file too — its directory is what decides the form.)
+
 1. Grep for the other Skyramp-generated test files exactly as in STEP 4 (codegen marker \`${codegenMarker}\`, excluding ${testFile} and \`${fileName}\`).
 2. In each, find every inline request block whose method+path matches a helper now defined in \`${fileName}\`.
 3. For each match: import the helper into that file and replace the block with the call, passing the block's literals (or expressions) as arguments; lift a literal the helper lacks to a defaulted parameter in \`${fileName}\`. Change NOTHING else in that file — its other steps, assertions and order stay verbatim.
@@ -286,7 +299,8 @@ 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.
-- **Preserve typing style**: if originals used \`page: any\` (or untyped \`page\`), keep that convention.
+${pyImportRuleLine(fileName)}
+- **Typed parameters (TypeScript)**: the merged helper types every parameter (\`page: Page\`, values by their type); add \`import type { Page } from '@playwright/test'\` to the utils file if it is missing. Never \`page: any\` or an untyped \`page\` — that fails a repo that type-checks its tests under \`noImplicitAny\`.
 - **Don't merge with helpers already in \`${fileName}\`**: those are STEP 3's territory. STEP 4b is strictly cross-test merge between sibling Skyramp-generated test files.
 
 ---
@@ -336,6 +350,7 @@ ${seedStepBlock}${siblingCallSitesStep}## STEP 6: VERIFY AND VALIDATE
 8. **REMOVE** any helper functions that are not being used after refactoring
 9. **NEVER** refactor, reorganize, or restructure existing source test files beyond moving helpers${inlineRequestRule ? " — and, in this flow, replacing an inline request block with a call to the shared helper it duplicates (STEP 3 / STEP 5c)" : ""}
 10. **RUN TESTS** to ensure functionality is preserved after refactoring
+11. **NEVER** drop an assertion or a cross-cutting guard (\`page.on('pageerror'...)\`, error collectors and their final \`expect\`) while moving code — the verify step compares the assertion count against the modularization hand-out and fails on a loss
 
 **FINAL REMINDER: DO NOT CREATE HELPER FUNCTIONS FROM SCRATCH**
 ${finalReminderScope}

package/build/prompts/enhance-assertions/sharedAssertionRules.js

@@ -206,7 +206,7 @@ Before editing the given file, you must output a \`<thinking>\` block. The aim o
 1. Scan the given test file and expected responses based on the test recommendations for the code change tested.
 2. Classify each response first by its response status type and then assign the applicable assertion rules to the response.
    1. Success with body (2xx with a response body): all assertion rules below may apply — echo-back of request fields, computed response fields, array / items validation, and chained values across steps.
-   2. Success with no body (204, or 202 with empty body): assert the status code only. Also apply chained-values rules if a follow-up step uses this response's ID.
+   2. Success with no body (200/202/204 with an empty body — e.g. logout/cancel/submit action endpoints): assert the status code only. Also apply chained-values rules if a follow-up step uses this response's ID.
    3. Error response (4xx/5xx with a body): assert every error body field with its exact value plus array / items validation on the \`errors[]\` array (exact length + per-item fields + next index undefined). Status code alone is never sufficient when a body is present — for example, also assert \`errors.0.extensions.code == 'INVALID_PAYLOAD'\` and that \`errors.1\` is undefined.
 3. For each in-scope response, output one JSON object using the template below. The output is an array — one object per in-scope response.
    - \`step\`: the HTTP method, path, and response variable name for this request (e.g. \`POST /products → products_POST_response\`).

package/build/prompts/initialize-workspace/initializeWorkspacePrompt.js

@@ -91,6 +91,7 @@ Create one service entry per deployable unit. You MUST include every backend/API
    - Single service: set testDirectory to tests/skyramp.
    - Multiple services or monorepos: set testDirectory to tests/skyramp/<serviceDirName>, where <serviceDirName> is the service directory name with path separators and whitespace replaced by hyphens.
    Framework config takes precedence. Use the Skyramp deterministic fallback only when no framework-configured test directory is available.
+   NEVER set testDirectory to \`.skyramp\`, to any path inside it, or to \`.\` or the repo root, whatever the framework config or existing test files say. \`.skyramp\` is the executor's own working area: it holds the run videos and executor artefacts. skyramp_init_workspace rejects all of these, and the generation tools refuse to write there.
 </basic_fields>
 
 ### API fields
@@ -160,7 +161,7 @@ Before calling skyramp_init_workspace, confirm all of the following:
 4. Every service has api.baseUrl set to a valid, discoverable URL. Use localhost for local services or the actual deployment URL for cloud or external services. Never fabricate a URL.
 5. Every service with authType apiKey has authHeader explicitly set to the actual custom header name (such as "X-API-Key" or "X-Admin-Key"). If you cannot find the header name in the source code, env vars, or README, do NOT use authType apiKey. Use authType none instead and add a YAML comment explaining auth is unresolved.
 6. framework matches language (python uses pytest or robot, typescript or javascript uses playwright, java uses junit).
-7. testDirectory follows the stable resolution rules above: framework config file when present (Playwright testDir in playwright.config.ts, pytest testpaths in pytest.ini or pyproject.toml, JUnit test source dir in pom.xml or build.gradle); otherwise the deterministic default (tests/skyramp for a single service, tests/skyramp/<serviceDirName> for multiple services).
+7. testDirectory follows the stable resolution rules above: framework config file when present (Playwright testDir in playwright.config.ts, pytest testpaths in pytest.ini or pyproject.toml, JUnit test source dir in pom.xml or build.gradle); otherwise the deterministic default (tests/skyramp for a single service, tests/skyramp/<serviceDirName> for multiple services). No service uses \`.skyramp\`, \`.\` or the repo root.
 8. If serverStartCommand is provided, it matches the runtime. If serverStopCommand is provided, runtime is "docker" and the command is a Docker command.
 9. For services in docker-compose.yml: runtime MUST be "docker" and the command MUST be a docker command such as "docker compose up -d --build <service-name>" when the service has a build context. Always include it since it is derivable from the service name.
 10. NEVER use application-level commands (uvicorn, npm, node, python, java, etc.) with runtime "docker".

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

@@ -41,13 +41,13 @@ ${p.utilsReuse ? "6" : "5"}. **SKIP to Step ${_plan.labels.VERIFY}** for verific
 - Examples: "create product", "fill form", "verify result"
 - Must be cohesive - related operations that achieve one goal${p.utilsReuse
     ? `
-- This project consolidates test helpers into a shared utils file, so EVERY logical section that performs a user action (open a form, fill and submit it, add or remove an item, apply an option) becomes a named helper — the section does NOT need to repeat. Another scenario's test will call the same helper with its own values.`
+- This project consolidates test helpers into a shared utils file. Extract a user-action section as a helper when another scenario's test would perform it AS-IS with its own values — sign in, open an entity's form or dialog, add or remove an item, apply a filter or option, dismiss a banner — even if it appears once here. Do NOT extract a section that exists only in this scenario's narrative (a specific multi-step data entry, a check sequence over this test's own values) just because the utils file exists: a single-use helper adds code and hides this scenario's locators behind a name, and the shared file then carries it for every later run.`
     : ""}
 
 **Don't extract:**
 - Code less than 5 lines (unless highly repetitive${p.utilsReuse
-    ? ", or a cohesive user-action section — those become helpers regardless of length, per B above"
-    : ""})
+    ? ", or a cross-test user action per B above — those become helpers regardless of length"
+    : ""})${p.utilsReuse ? "\n- A section only this scenario performs AND that appears once in this file — keep it inline (see B above; if it repeats 2+ times in this file, scenario A still applies and it is extracted)" : ""}
 - Navigation sequences (\`navbar-\` clicks, \`page.goto\`)`)
     .step("EXTRACT", "EXTRACT INTO HELPERS", (p) => `**GOLDEN RULE: Copy the original code exactly, only add parameters for values that differ**
 
@@ -123,8 +123,10 @@ async function createOrderWithItems(...) { }
 
 **RIGHT - Good practices:**
 \`\`\`typescript
+import type { Page } from '@playwright/test';
+
 // CORRECT - Extract with parameter, no new logic
-async function addItem(page, name: string) {
+async function addItem(page: Page, name: string) {
   await page.fill("#name", name);  // Replace literal with parameter
 }
 
@@ -136,8 +138,8 @@ 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:**
-- [ ] **NO TYPE ANNOTATIONS FOR \`page\` IN FUNCTION SIGNATURES** - Parameters must be untyped (e.g., \`page\`, not \`page: Page\`)
-- [ ] **NO RETURN TYPES** - Do not add \`: Promise<void>\` or any return type 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\`. 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)
 - [ ] **No nested helpers** - Helpers don't call other helpers unnecessarily
@@ -150,6 +152,7 @@ ${p.utilsReuse
 - [ ] Every helper name is a canonical intent (\`openEditOrderForm\`, \`applyDiscount\`) with no scenario value or adjective in it
 - [ ] No helper contains a value assertion (${BROWSER_VALUE_ASSERTIONS}) — each sits in the test body, right after the helper call it verifies
 - [ ] Every selector inside a helper is byte-identical to the original test
+- [ ] The assertion COUNT is unchanged: every \`expect(\` from the original is still in this file or inside a helper it calls, and the \`page.on('pageerror'...)\` guard and its final \`expect\` over the collected errors are still here — cross-cutting guards are never removed (the verify step counts both)
 `
     : ""}
 **DATA INTEGRITY:**

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

@@ -559,7 +559,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.
-- **Preserve typing style**: if originals used \`page: any\` (or untyped \`page\`), keep that convention.
+- **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\`.
 - **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/shared-helper-policy.js

@@ -45,11 +45,11 @@ export const API_HELPERS = {
     sameStep: "the SAME method+path",
     liftableLiterals: API_LIFTABLE,
     structuralNoise: "",
-    namingRule: "**NAME** each helper by method + resource ONLY: `create_product`, `update_order`, `get_order`, `get_orders_list`. Scenario adjectives in names are FORBIDDEN (`create_discount_test_product`, `update_order_50_discount`) — other tests define the same step, and a shared utils file can hold only one canonical name per step. Scenario data belongs in ARGUMENTS, never in the name.",
+    namingRule: "**NAME** each helper by method + resource ONLY, written in the naming convention of the language it is emitted in — Python `create_product`, `update_order`, `get_order`, `get_orders_list`; TypeScript/JavaScript `createProduct`, `updateOrder`, `getOrder`, `getOrdersList`. Match the surrounding test file: snake_case helpers in a camelCase TS suite read as foreign code the repo did not write. Scenario adjectives in names are FORBIDDEN (`create_discount_test_product`, `updateOrder50Discount`) — other tests define the same step, and a shared utils file can hold only one canonical name per step. Scenario data belongs in ARGUMENTS, never in the name.",
     assertionRule: `**THE ONLY ASSERTION INSIDE A SHARED HELPER IS THE STATUS CODE**, written in the test's own assertion syntax (Python \`assert response.status_code == expected_status\`; TypeScript/JavaScript \`expect(response.status).toBe(expectedStatus)\`), with the expected status a parameter defaulted to this scenario's expected code. EVERY response-body assertion (echo-backs, computed totals, field checks) stays in the test body, applied to the response the helper returns. ${SHARED_HELPER_WHY}`,
     relocationTarget: "the test body, applied to the response the helper returns",
     moveRule: "",
-    namingExample: "E.g. `update_order`, not `update_order_discount` or `update_order_50_discount`.",
+    namingExample: "E.g. `update_order` (Python) / `updateOrder` (TypeScript), not `update_order_discount` or `updateOrder50Discount`.",
     oneHelperRule: (fileName) => `One method+path = one helper in \`${fileName}\`.`,
     // The API section below carries its own worked example; the generic
     // Playwright one would teach intent-naming and locator merges to a Python prompt.
@@ -81,7 +81,7 @@ export const BROWSER_HELPERS = {
     kind: "browser",
     sameStep: "the SAME action sequence (same Playwright primitives in the same order, selectors identical)",
     liftableLiterals: BROWSER_LIFTABLE,
-    structuralNoise: "`waitForTimeout(...)` lines and the `getValue(playwrightRequestN, ...)` value wrapper around a fill are RECORDER NOISE, not structure — two bodies that differ only by them perform the same step; keep the utils version (it carries the waits) and import it",
+    structuralNoise: "`waitForTimeout(...)` lines and the `getValue(playwrightRequestN, ...)` value wrapper around a fill are RECORDER NOISE, not structure — two bodies that differ only by them perform the same step, so merge them; keep the body WITHOUT the `waitForTimeout` lines. A fixed sleep is not a structural wait: it is the one line of the pair that carries no meaning, and in a shared helper every importer pays it on every run. Where a step genuinely needs to wait, wait on the element the next line touches (`toBeVisible`, `toBeEnabled`)",
     namingRule: "**NAME** each helper by the user INTENT it performs, shared across tests: `openEditOrderForm`, `applyDiscount`, `submitProductForm`, `removeOrderItem`. Scenario values or adjectives in names are FORBIDDEN (`applyFiftyPercentDiscount`, `editOrder1Discount`, `createExpensiveProduct`) — another test performs the same action with different data, and a shared utils file holds ONE canonical name per action. Scenario data belongs in ARGUMENTS, never in the name.",
     assertionRule: `**A SHARED HELPER CONTAINS ACTIONS AND STRUCTURAL WAITS ONLY**: clicks, fills, selects, ${BROWSER_STRUCTURAL_WAITS}. EVERY VALUE ASSERTION (${BROWSER_VALUE_ASSERTIONS}) stays in the test body, placed immediately after the helper call it verifies, with its selector verbatim and its expected value unchanged. ${SHARED_HELPER_WHY}`,
     relocationTarget: "the test body, immediately after the helper call, selector verbatim",
@@ -100,7 +100,7 @@ export async function applyDiscount(page) {
 
 \`${testFile}\` (current) has:
 \`\`\`ts
-export async function applyTwentyPercentDiscount(page) {
+export async function applyTwentyPercentDiscount(page: Page) {
     await page.getByTestId("edit-order-input-discount").fill("20");
     await page.getByTestId("edit-order-submit-btn").click();
 }
@@ -109,7 +109,7 @@ export async function applyTwentyPercentDiscount(page) {
 These ARE near-duplicates: same primitive sequence, selectors byte-identical, the only difference is the fill literal. Correct merge (name = intent, the literal becomes a parameter passed exactly as it was written — no conversion or other logic added, selectors untouched):
 
 \`\`\`ts
-export async function applyDiscount(page, discountPercent) {
+export async function applyDiscount(page: Page, discountPercent: string) {
     await page.getByTestId("edit-order-input-discount").fill(discountPercent);
     await page.getByTestId("edit-order-submit-btn").click();
 }

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

@@ -212,7 +212,7 @@ ${maintenanceBeforeExecStep}
 
    e. Call \`skyramp_actions\` with \`stateFile\` (from \`skyramp_analyze_changes\` output) and apply the edits it returns.
 
-   f. Verify external-test fixes. **This step is not optional and it is the easiest one to forget — you have just edited files in step 2(e), so come back here before you move on to anything else.** It applies whenever step 2(a) reported a real pass/fail result for a file you then edited. It does NOT apply when step 2(a) returned \`skipped: true\` or \`ran: 0\` for every suite — there is no baseline to compare against, so say so in your report instead of re-running. When it applies: re-run those \`[external]\` files with \`skyramp_run_existing_tests\` (\`mode: "verify"\`, \`stateFile\`) — the server reads each file's result back as its \`afterStatus\`. Editing an \`[external]\` file that step 2(a) confirmed failing and NOT re-running it leaves your own fix unverified — you would be reporting a repair you never saw work. A still-failing verify is surfaced in the report — do not loop.
+   f. Verify external-test fixes. **This step is not optional and it is the easiest one to forget — you have just edited files in step 2(e), so come back here before you move on to anything else.** It applies whenever step 2(a) reported a real pass/fail result for a file you then edited. It does NOT apply when step 2(a) returned \`skipped: true\` or \`ran: 0\` for every suite — there is no baseline to compare against, so say so in your report instead of re-running. When it applies: re-run those \`[external]\` files with \`skyramp_run_existing_tests\` (\`mode: "verify"\`, \`stateFile\`) and record each file's result as its \`afterStatus\`. Editing an \`[external]\` file that step 2(a) confirmed failing and NOT re-running it leaves your own fix unverified — you would be reporting a repair you never saw work. A still-failing verify is surfaced in the report — do not loop.
 
 3. **Code review:** Find the logic bugs in the code that this change touches. Read the implementation of each changed endpoint: the route handler, and the functions that it calls to read or write data. For a changed screen, read the component and the functions that it calls. Read these files even when the diff does not contain them — a defect often sits in the code that the change depends on. Report each finding in \`issuesFound\` with a severity, and say which file and line holds it. Common patterns to flag:
    - Computed fields not recalculated after mutation (e.g. \`total_amount\` unchanged after items are added/removed)

package/build/services/TestGenerationService.js

@@ -7,12 +7,14 @@ import { extractPathname, resolveQueryParamsForPath, contributesNothing, } from
 import { getPathParameterValidationError, OUTPUT_DIR_FIELD_NAME, PATH_PARAMS_FIELD_NAME, QUERY_PARAMS_FIELD_NAME, FORM_PARAMS_FIELD_NAME, validateParams, validatePath, validateRequestData, } from "../utils/utils.js";
 import { getEntryPoint } from "../utils/telemetry.js";
 import { getLanguageSteps } from "../utils/language-helper.js";
-import { TestType } from "../types/TestTypes.js";
+import { ASSERTION_ENHANCEABLE_TEST_TYPES, TestType, MOCK_TYPE, } from "../types/TestTypes.js";
 import { logger } from "../utils/logger.js";
 import { normalizeLanguageParams } from "../utils/normalizeParams.js";
 import { stageGeneratedPaths, resolveOutputDir } from "../utils/gitStaging.js";
+import { isInsideExecutorWorkDir, executorWorkDirRefusal, generationTargets, } from "../utils/executorWorkDir.js";
 import { getTestsRepoDir } from "../utils/AnalysisStateManager.js";
 import { recordReuseHandOff } from "../tools/code-refactor/reuse-state.js";
+import { recordAssertionBaseline } from "../tools/code-refactor/assertion-state.js";
 import { isModularizeFirstTarget } from "../utils/reuseRouting.js";
 /**
  * Derive the framework actually used for generation from the (normalized)
@@ -73,6 +75,18 @@ export class TestGenerationService {
                 });
                 params.outputDir = resolved;
             }
+            // Every generation tool reaches the filesystem through this method, so one
+            // check here covers them all. Nothing written under `.skyramp` is delivered
+            // as a test — an observed run put 7 specs there because the only absolute
+            // path the prompt gave it was the trace-zip directory. The error names the
+            // field and the replacement so the agent can correct itself in one round trip.
+            const badTarget = generationTargets(params.outputDir, params.output).find(isInsideExecutorWorkDir);
+            if (badTarget) {
+                return {
+                    content: [{ type: "text", text: executorWorkDirRefusal(badTarget) }],
+                    isError: true,
+                };
+            }
             // Log prompt parameter using reusable utility
             logger.info("Generating test", {
                 prompt: params.prompt,
@@ -93,7 +107,20 @@ export class TestGenerationService {
             // The files this call wrote, as codegen reports them — the reuse hand-off is
             // recorded per FILE (SKYR-4220).
             const written = generatedFilesFrom(result);
+            // Seed the assertion-enhancement baseline SERVER-SIDE at generation time
+            // (same pattern as recordReuseHandOff below): the execute-time
+            // verification gate arms even if the agent never calls
+            // skyramp_enhance_assertions at all — the last prompt-mediated entry
+            // point. Best-effort; no run state means the gate stays open as before.
             const testType = this.getTestType();
+            if (params.enhanceAssertions &&
+                testType !== MOCK_TYPE &&
+                ASSERTION_ENHANCEABLE_TEST_TYPES.includes(testType) &&
+                (testType !== TestType.CONTRACT || params.providerMode !== false)) {
+                for (const file of written) {
+                    await recordAssertionBaseline(file, testType, "generation");
+                }
+            }
             const languageSteps = getLanguageSteps({
                 language: params.language || "",
                 testType: testType,

package/build/tools/code-refactor/assertion-state.d.ts

@@ -0,0 +1,91 @@
+import { type AssertionBaseline, type AssertionEnhanceType, type AssertionVerifyResult } from "../../utils/assertion-verify/index.js";
+import type { AssertionOutcome, AssertionRecord } from "../../types/AssertionOutcome.js";
+import type { TestType } from "../../types/TestTypes.js";
+import type { RepoCheckout } from "../../utils/reportVerification.js";
+/**
+ * Persistence for the assertion-enhancement verification loop, keyed by the
+ * spec's CANONICAL absolute path in `UnifiedAnalysisState.assertionOutcomes`.
+ * Path keying (not basename, unlike reuseOutcomes — nothing here needs to
+ * match report rows) removes the multi-repo basename-collision class outright,
+ * and canonicalization closes the alias bypass: `dir//x.spec.ts` and
+ * `dir/./x.spec.ts` must hit the same record as `dir/x.spec.ts`.
+ *
+ * Every write is best-effort: verification must never be able to fail an
+ * enhancement that otherwise succeeded, so a missing/unreadable state file
+ * degrades to stateless checks and open gates — always with a warning.
+ */
+/** Canonical identity of a test file — all keying and ownership comparisons
+ *  go through this so a non-normalized agent-supplied path cannot fork or
+ *  bypass a record. realpath also collapses symlinked directories; a path
+ *  that does not (yet) exist falls back to plain resolution. */
+export declare function canonicalTestPath(testFile: string): string;
+/** A record only counts for `testFile` when its stored path canonicalizes to
+ *  the same spec — the single home for the ownership invariant (previously
+ *  copied in baselineFrom, recordAssertionVerdict, and the enhance tool). */
+export declare function trustedRecord(record: AssertionRecord | undefined, testFile: string): AssertionRecord | undefined;
+/** One spec's record, or undefined when there is no run state / no record. */
+export declare function readAssertionRecord(testFile: string, explicitStateFile?: string): Promise<AssertionRecord | undefined>;
+/**
+ * Snapshot the file at instruction hand-out time — the baseline verify measures
+ * against. Keep-first rule: while no Passed verdict exists for the same file and
+ * enhanceType, a repeat hand-out does NOT re-baseline (re-calling the tool after
+ * half-editing must not shrink the required delta). A hand-out after a Passed
+ * verdict, or with a different enhanceType, starts a new enhancement round.
+ */
+export declare function recordAssertionBaseline(testFile: string, testType: TestType, enhanceType: AssertionEnhanceType, explicitStateFile?: string): Promise<void>;
+/** The baseline verify measures against, from a record; undefined when the
+ *  record carries no snapshot or belongs to a different canonical path. */
+export declare function baselineFrom(record: AssertionRecord | undefined, testFile: string): AssertionBaseline | undefined;
+/** Record what one verify pass established. The verdict is written to the
+ *  state file the record actually LIVES in (not blindly to the explicit path —
+ *  a mismatched `stateFile` would otherwise split verdict from baseline).
+ *  Never writes onto a record owned by a different canonical path, and never
+ *  fails silently. */
+export declare function recordAssertionVerdict(testFile: string, result: AssertionVerifyResult, explicitStateFile?: string): Promise<void>;
+/**
+ * Deterministic execute-time verification: skyramp_execute_test calls this
+ * itself, so the check runs whether or not the agent ever called `verify: true`
+ * — a prose instruction can be ignored, a server-side call cannot. Returns the
+ * feedback text when the assertions are insufficient (the caller returns it
+ * instead of executing), or undefined to proceed.
+ *
+ * Self-clearing: the checks run on the file's CURRENT content, so fixing the
+ * assertions and re-executing passes — no separate verify call is required.
+ * Skipped once a verdict has PASSED: sanctioned later rewrites (a `.raw.bak`
+ * restore during execution fix-up) would otherwise false-fail the differential
+ * gates. Modularization needs no special handling: the shared-helper policy
+ * keeps every value assertion in the test body, so the baseline comparison
+ * stays valid across it. Fails open on no baseline and unreadable state/file.
+ */
+export declare function assertionFeedbackForExecution(testFile: string, explicitStateFile?: string): Promise<string | undefined>;
+/**
+ * Count one execution of this spec (called by skyramp_execute_test after its
+ * gates pass, best-effort). Creates a minimal record when none exists so an
+ * executed-but-never-enhanced spec is still visible to the report cross-check.
+ */
+export declare function recordAssertionExecution(testFile: string, testType: TestType, explicitStateFile?: string): Promise<void>;
+/** A repo checkout as listRepoCheckouts returns it — the canonical type from
+ *  reportVerification, re-exported (a local re-declaration had drifted:
+ *  `root` weakened to optional, forcing a redundant guard at each use). */
+export type RepoCheckoutRef = RepoCheckout;
+/** The record for a report row, matched by the canonical-path keys' basenames
+ *  and then GUARDED: the record's testType must match the row's, and when the
+ *  run's checkouts are known, the record's path must live in the row's repo
+ *  (primary when the row names none). Without the guards, a basename shared
+ *  across repos published one spec's proof-of-work under another's name — and
+ *  the victim was exactly the never-enhanced spec the field exists to expose.
+ *  Ambiguity after filtering still fails open: wrong attribution is worse
+ *  than omission. */
+export declare function findAssertionRecordByFileName(outcomes: Record<string, AssertionRecord>, row: {
+    fileName: string;
+    testType?: string;
+    repository?: string;
+}, checkouts: RepoCheckoutRef[]): AssertionRecord | undefined;
+/**
+ * Report-facing proof-of-work summary re-derived from the spec as delivered
+ * NOW — final metrics come from the file, not from verify-time state, so
+ * post-verify edits cannot publish stale counts. Always returns the status
+ * fields (verification, declinedReason, executionCount — they come from the
+ * record); the metric fields are omitted when the file cannot supply them.
+ */
+export declare function rederiveAssertionOutcome(record: AssertionRecord): Promise<AssertionOutcome>;