@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/services/TestExecutionService.js

@@ -43,7 +43,11 @@ process.on("exit", () => {
 // resolving from the mounted repo. Node treats the empty shadow as a miss and
 // walks up to NODE_PATH's global install (both packages are global in the
 // executor image).
-const SHADOWED_NESTED_PACKAGES = ["@playwright/test", "playwright", "@skyramp/skyramp"];
+const SHADOWED_NESTED_PACKAGES = [
+    "@playwright/test",
+    "playwright",
+    "@skyramp/skyramp",
+];
 // Minimal Playwright config — shadows repo configs that may import dotenv or other
 // dependencies not available in the executor container.
 const MINIMAL_PLAYWRIGHT_CONFIG_PATH = path.join(os.tmpdir(), "skyramp-playwright.config.ts");
@@ -60,9 +64,7 @@ export const PLAYWRIGHT_CONFIG_FILES = [
 // IS mounted (see mountRepoTree) — but walking it would shadow every package's
 // own package.json with empty JSON via MOUNT_NULL_ITEMS, breaking resolution
 // for the whole tree.
-export const MOUNT_SCAN_SKIP_DIRS = [
-    "node_modules",
-];
+export const MOUNT_SCAN_SKIP_DIRS = ["node_modules"];
 // Reserved container subdir under /home/user where a cross-repo test repository
 // (testsRepoDir, SKYR-3819) is mounted. Must live INSIDE /home/user: the generated
 // Playwright config's testDir is anchored there, and a test path outside it is
@@ -94,8 +96,14 @@ export function isBrowserTest(testType) {
  * based on the test file path
  */
 export function getVideoSubdir(testFile) {
-    const basename = path.basename(testFile, path.extname(testFile)).replace(/[^A-Za-z0-9._-]/g, "-");
-    const hash = crypto.createHash("sha256").update(testFile).digest("hex").slice(0, 8);
+    const basename = path
+        .basename(testFile, path.extname(testFile))
+        .replace(/[^A-Za-z0-9._-]/g, "-");
+    const hash = crypto
+        .createHash("sha256")
+        .update(testFile)
+        .digest("hex")
+        .slice(0, 8);
     return `${basename}-${hash}`;
 }
 /**
@@ -359,7 +367,8 @@ export function detectSessionFiles(testFilePath) {
  */
 export function findExcludedPaths(dir, excludedItems) {
     const results = [];
-    const shouldSkipDir = (entry) => excludedItems.includes(entry.name) || MOUNT_SCAN_SKIP_DIRS.includes(entry.name);
+    const shouldSkipDir = (entry) => excludedItems.includes(entry.name) ||
+        MOUNT_SCAN_SKIP_DIRS.includes(entry.name);
     for (const [entry, fullPath] of walkDir(dir, { shouldSkipDir })) {
         // Only shadow files — mounting /dev/null to a directory target causes Docker errors
         if (excludedItems.includes(entry.name)) {
@@ -523,7 +532,9 @@ export class TestExecutionService {
         // include it and the relative-path computation would escape /home/user. Anchor
         // it under the reserved subdir instead; the test repo is mounted there below.
         const absTestFile = path.resolve(options.testFile);
-        const testRepoPath = options.testRepoPath ? path.resolve(options.testRepoPath) : undefined;
+        const testRepoPath = options.testRepoPath
+            ? path.resolve(options.testRepoPath)
+            : undefined;
         // A root-level test repo would bind-mount large portions of the host
         // (read-write, alongside the Docker socket) into the executor — reject it
         // explicitly rather than falling through to the generic path error below.
@@ -532,7 +543,9 @@ export class TestExecutionService {
             !isUnder(workspacePath, absTestFile)) {
             throw new Error(`testRepoPath must not be the filesystem root, got: ${options.testRepoPath}`);
         }
-        const crossRepoTestRoot = !isUnder(workspacePath, absTestFile) && testRepoPath && isUnder(testRepoPath, absTestFile)
+        const crossRepoTestRoot = !isUnder(workspacePath, absTestFile) &&
+            testRepoPath &&
+            isUnder(testRepoPath, absTestFile)
             ? testRepoPath
             : undefined;
         if (crossRepoTestRoot) {
@@ -555,7 +568,7 @@ export class TestExecutionService {
             testFilePath = path.resolve(containerMountPath, path.relative(workspacePath, absTestFile));
         }
         // Video recording setup for UI/E2E browser tests (no-op for API tests).
-        const { browserTest, videoHostDir, videoContainerDir, playwrightConfigPath, pytestConfigPath } = setupVideoCapture(options, workspacePath, containerMountPath);
+        const { browserTest, videoHostDir, videoContainerDir, playwrightConfigPath, pytestConfigPath, } = setupVideoCapture(options, workspacePath, containerMountPath);
         // Prepare Docker command
         const command = [
             "bash",
@@ -637,10 +650,15 @@ export class TestExecutionService {
             // copies that must not load from the repo.
             const entriesToMount = fs
                 .readdirSync(hostRoot)
-                .filter((file) => !MOUNT_NULL_ITEMS.includes(file) && !PLAYWRIGHT_CONFIG_FILES.includes(file));
+                .filter((file) => !MOUNT_NULL_ITEMS.includes(file) &&
+                !PLAYWRIGHT_CONFIG_FILES.includes(file));
             for (const file of entriesToMount) {
                 const source = path.join(hostRoot, file);
-                pushMount({ Type: "bind", Target: path.join(containerRoot, file), Source: source });
+                pushMount({
+                    Type: "bind",
+                    Target: path.join(containerRoot, file),
+                    Source: source,
+                });
                 if (mirrorToHost) {
                     pushMount({ Type: "bind", Target: source, Source: source });
                 }
@@ -648,8 +666,14 @@ export class TestExecutionService {
             // Shadow MOUNT_NULL_ITEMS (found recursively) with /dev/null (or empty JSON for .json files).
             for (const absolutePath of findExcludedPaths(hostRoot, MOUNT_NULL_ITEMS)) {
                 const rel = path.relative(hostRoot, absolutePath);
-                const source = absolutePath.endsWith(".json") ? EMPTY_JSON_PATH : "/dev/null";
-                pushMount({ Type: "bind", Source: source, Target: path.join(containerRoot, rel) });
+                const source = absolutePath.endsWith(".json")
+                    ? EMPTY_JSON_PATH
+                    : "/dev/null";
+                pushMount({
+                    Type: "bind",
+                    Source: source,
+                    Target: path.join(containerRoot, rel),
+                });
                 if (mirrorToHost) {
                     pushMount({ Type: "bind", Source: source, Target: absolutePath });
                 }
@@ -669,7 +693,12 @@ export class TestExecutionService {
                         ReadOnly: true,
                     });
                     if (mirrorToHost) {
-                        pushMount({ Type: "bind", Source: EMPTY_DIR_PATH, Target: pkgPath, ReadOnly: true });
+                        pushMount({
+                            Type: "bind",
+                            Source: EMPTY_DIR_PATH,
+                            Target: pkgPath,
+                            ReadOnly: true,
+                        });
                     }
                 }
             }
@@ -681,9 +710,17 @@ export class TestExecutionService {
             // `npx playwright test <file>` and read playwright.config.ts.
             for (const absolutePath of findExcludedPaths(hostRoot, PLAYWRIGHT_CONFIG_FILES)) {
                 const rel = path.relative(hostRoot, absolutePath);
-                pushMount({ Type: "bind", Source: playwrightConfigPath, Target: path.join(containerRoot, rel) });
+                pushMount({
+                    Type: "bind",
+                    Source: playwrightConfigPath,
+                    Target: path.join(containerRoot, rel),
+                });
                 if (mirrorToHost) {
-                    pushMount({ Type: "bind", Source: playwrightConfigPath, Target: absolutePath });
+                    pushMount({
+                        Type: "bind",
+                        Source: playwrightConfigPath,
+                        Target: absolutePath,
+                    });
                 }
             }
         };
@@ -692,7 +729,8 @@ export class TestExecutionService {
         // even if the repo has no config file. The pushMount dedup ensures later shadows
         // for the same target are dropped.
         if (browserTest) {
-            if (options.language === "typescript" || options.language === "javascript") {
+            if (options.language === "typescript" ||
+                options.language === "javascript") {
                 // Mount generated Playwright config at canonical container path
                 pushMount({
                     Type: "bind",
@@ -962,11 +1000,15 @@ export class TestExecutionService {
             const errors = this.parseErrors(cleanOutput);
             const warnings = this.parseWarnings(cleanOutput);
             // Collect the recorded video (browser tests only).
-            const videoPath = browserTest ? collectVideoPath(videoHostDir) : undefined;
+            const videoPath = browserTest
+                ? collectVideoPath(videoHostDir)
+                : undefined;
             const result = {
                 testFile: options.testFile,
-                status: statusCode === 0 ? TestExecutionStatus.Pass
-                    : statusCode !== 1 ? TestExecutionStatus.Error
+                status: statusCode === 0
+                    ? TestExecutionStatus.Pass
+                    : statusCode !== 1
+                        ? TestExecutionStatus.Error
                         : TestExecutionStatus.Fail,
                 executedAt,
                 duration,

package/build/services/TestGenerationService.d.ts

@@ -62,7 +62,7 @@ export declare abstract class TestGenerationService {
     protected abstract getTestType(): TestType | typeof MOCK_TYPE;
     /**
      * Whether this generation's codeReuse hand-off sequences skyramp_modularization
-     * before skyramp_reuse_code (routing: isModularizeFirstTarget). Subclasses that
+     * before skyramp_reuse_code (isModularizeFirstHandOffTarget). Subclasses that
      * add their own post-generation steps consult this so modularization is
      * instructed exactly once.
      */

package/build/services/TestGenerationService.js

@@ -15,7 +15,8 @@ import { isInsideExecutorWorkDir, executorWorkDirRefusal, generationTargets, } f
 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";
+import { persistGeneratedTest } from "../utils/generatedTestRecord.js";
+import { buildModularizeFirstNextSteps, isModularizeFirstHandOffTarget, reuseCodeArgsClause, } from "../prompts/reuse-hand-off.js";
 /**
  * Derive the framework actually used for generation from the (normalized)
  * language + framework params. A blank/whitespace-only framework is treated as
@@ -107,12 +108,24 @@ 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);
+            // Record the paths this call wrote, unconditionally. The generator is the
+            // only place they are known, and the report otherwise has to fall back to
+            // the agent's `fileName` — a basename, so two specs of one name in
+            // different directories answer for each other. Not folded into the
+            // assertion baseline below: that one is skipped for whole test types.
+            // A mock is not a test and is never executed, so it is not recorded.
+            const generatedType = this.getTestType();
+            if (generatedType !== MOCK_TYPE) {
+                for (const file of written) {
+                    await persistGeneratedTest(file, generatedType);
+                }
+            }
             // 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();
+            const testType = generatedType;
             if (params.enhanceAssertions &&
                 testType !== MOCK_TYPE &&
                 ASSERTION_ENHANCEABLE_TEST_TYPES.includes(testType) &&
@@ -128,25 +141,32 @@ export class TestGenerationService {
             });
             // Orchestrate code optimization workflow based on flags
             let postGenerationMessage = "";
-            if (params.codeReuse) {
+            // skyramp_mock_generation's schema carries no `codeReuse` field, so the mock
+            // pseudo-type cannot reach this branch. Narrowed here rather than widened in
+            // the shared hand-off module, which deals in TestType only.
+            const reuseTestType = testType === MOCK_TYPE ? undefined : testType;
+            if (params.codeReuse && reuseTestType) {
                 // Name the framework generation actually used, not the raw parameter:
                 // TS/JS derive to playwright when the caller omitted it, and
                 // skyramp_reuse_code requires framework to route correctly.
                 const effectiveFramework = deriveEffectiveFramework(params.language || "", params.framework);
-                const reuseArgs = `\`testFile\` set to the absolute path of the generated test file, \`language: "${params.language}"\`, \`testType: "${testType}"\`${effectiveFramework ? `, and \`framework: "${effectiveFramework}"\`` : ""}`;
+                const reuseArgs = reuseCodeArgsClause(params.language, reuseTestType, effectiveFramework);
                 // Modularize-first: fresh codegen carries no helper functions (each
                 // endpoint called once, each browser step inline), so modularization is
                 // what creates the named helpers that reuse then consolidates into the
                 // shared utils file. Emitted here, not in the testbot prompt, so the
                 // instruction exists only on runs that actually generated this test type
                 // and needs no hand-maintained step numbering.
-                if (this.emitsModularizeFirstHandOff(params)) {
+                // The predicate rather than emitsModularizeFirstHandOff: both mean the
+                // same inside this codeReuse branch, and this one narrows the language to
+                // one the utils verifier covers, which is what the steps require.
+                if (isModularizeFirstHandOffTarget(reuseTestType, params.language)) {
                     // SKYR-4220: record the hand-off at the site that emits it, under the same
                     // condition, so skyramp_execute_test can refuse a test that skipped the pair
                     // and the report can mark it — without ever owing it for a test that was not
                     // told to run it. Keyed by the files this call wrote: a test generated into
                     // the same directory without codeReuse owes nothing.
-                    await recordReuseHandOff(written, testType, params.language || "", effectiveFramework);
+                    await recordReuseHandOff(written, testType, params.language, effectiveFramework);
                     // Browser tests: the assertion enhancer anchors new assertions to
                     // selectors present in the test file, and after modularize → reuse
                     // those selectors live in the utils file. So for UI the enhancer runs
@@ -154,23 +174,15 @@ export class TestGenerationService {
                     // assertion in the test body. API enhancers key off response paths,
                     // so integration keeps its validated modularize → reuse → enhance order.
                     const enhanceFirst = testType === TestType.UI && !!params.enhanceAssertions;
-                    const steps = [
-                        ...(enhanceFirst
-                            ? [
-                                `Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated test file, \`testType: "${testType}"\`, and \`enhanceType: "generation"\`, and apply every instruction returned to that file — BEFORE modularization, while the file's selectors are still inline.`,
-                            ]
-                            : []),
-                        `Call \`skyramp_modularization\` with \`testFile\`, \`testType: "${testType}"\`, and \`isTraceBased: true\`, and apply the returned instructions — this extracts the test's steps into named helper functions, which is what makes cross-test reuse possible.`,
-                        `Immediately after writing the modularized file — as your very NEXT skyramp tool call — call \`skyramp_reuse_code\` with ${reuseArgs}. The modularization call does NOT count as this step: reuse is a separate tool and MUST be invoked even when you expect it to find nothing. Follow the returned steps to completion. Sibling tests offering nothing to reuse is a normal outcome — the returned steps still move THIS test's own helpers into the shared utils file and import them back, so the test file IS expected to change; finish those steps, then continue (do NOT retry).`,
-                    ];
-                    const ordering = enhanceFirst
-                        ? "three sub-steps, STRICTLY SEQUENTIAL (never in the same tool-call batch)"
-                        : "two sub-steps, STRICTLY SEQUENTIAL (never in the same tool-call batch), BOTH BEFORE `skyramp_enhance_assertions`";
                     postGenerationMessage += `
  Test generated successfully!
 
-⏭️**CRITICAL NEXT STEPS — ${ordering}**:
-${steps.map((text, i) => `${String.fromCharCode(97 + i)}. ${text}`).join("\n")}
+${buildModularizeFirstNextSteps({
+                        testType: reuseTestType,
+                        language: params.language,
+                        framework: effectiveFramework,
+                        enhanceFirst,
+                    })}
 `;
                 }
                 else {
@@ -271,10 +283,15 @@ The generated test file remains unchanged and ready to use as-is.
                     const suggested = /\.[tj]s$/.test(parsed.ext)
                         ? params.output.replace(/\.[tj]s$/, ".spec.ts")
                         : params.output + ".spec.ts";
+                    // Both spellings are named: the repository decides which files are tests,
+                    // and one that declares `testMatch: ["**/*.test.ts"]` collects no
+                    // *.spec.ts (SKYR-4489).
+                    const alternative = suggested.replace(/\.spec\.ts$/, ".test.ts");
                     errList.content.push({
                         type: "text",
-                        text: `Error: Playwright requires test files to match *.{spec}.{ts,js} (got "${params.output}"). ` +
-                            `Rename to e.g. ${suggested} so Playwright can discover it.`,
+                        text: `Error: Playwright requires test files to match *.{spec,test}.{ts,js} (got "${params.output}"). ` +
+                            `Rename to ${suggested}, or to ${alternative} if the tests already in ` +
+                            `${params.outputDir} use that spelling.`,
                     });
                 }
             }
@@ -303,13 +320,15 @@ The generated test file remains unchanged and ready to use as-is.
     }
     /**
      * Whether this generation's codeReuse hand-off sequences skyramp_modularization
-     * before skyramp_reuse_code (routing: isModularizeFirstTarget). Subclasses that
+     * before skyramp_reuse_code (isModularizeFirstHandOffTarget). Subclasses that
      * add their own post-generation steps consult this so modularization is
      * instructed exactly once.
      */
     emitsModularizeFirstHandOff(params) {
+        const testType = this.getTestType();
         return (!!params.codeReuse &&
-            isModularizeFirstTarget(this.getTestType(), params.language));
+            testType !== MOCK_TYPE &&
+            isModularizeFirstHandOffTarget(testType, params.language));
     }
     async handleApiAnalysis(params) {
         if (params.apiSchema && params.endpointURL && params.method === "") {

package/build/skills/enhanceAssertionsSkill.d.ts

@@ -0,0 +1,45 @@
+import type { EnhanceType } from "../types/EnhanceType.js";
+/**
+ * The `enhance-assertions` skill ships in `plugin/skills/` at the
+ * package root (SKYR-4310). Its markdown is the single source of the assertion
+ * instructions: Claude Code loads the skill through `--plugin-dir`, and every
+ * other agent gets the same rules assembled from the same files by
+ * `skyramp_enhance_assertions`, whose behaviour is otherwise unchanged.
+ */
+export declare const ENHANCE_ASSERTIONS_SKILL = "enhance-assertions";
+/** The shared response-body rules, without the surrounding framing. */
+export declare function sharedAssertionRules(): string;
+/** Full instruction text, assembled from the same markdown the skill reads.
+ *  Used by agents that cannot load the plugin. */
+export declare function buildEnhanceAssertionsInstructions(testFile: string, testType: string, enhanceType: EnhanceType): string;
+/**
+ * The maintenance equivalent, for the UPDATE strategy. It covers a set of
+ * already-edited files rather than one freshly generated file, so it names no
+ * single test type and states the per-file duty over that set.
+ *
+ * This route was the last one still naming the tool literally. Because MCP tool
+ * output beats the prompt on conflict, that one call handed the agent the whole
+ * rule text, and an agent already holding the rules has no reason to invoke the
+ * skill — which is why two A/B runs recorded zero invocations while the
+ * per-file gates worked (SKYR-4310).
+ */
+export declare function enhanceAssertionsMaintenanceCall(): string;
+/** `enhanceAssertionsCall` as a standalone sentence, for a generation result's
+ *  numbered step list. */
+export declare function enhanceAssertionsStep(testType: string, fileDescription: string): string;
+/**
+ * How a prompt or a generation result should tell the agent to enhance
+ * assertions. With the skills plugin loaded the skill owns the whole workflow
+ * — baseline, rules, verification — so naming the tool here would hand the
+ * agent the same rules a second time (SKYR-4310).
+ *
+ * The per-file duty is stated HERE, in the routing text, not left to the skill
+ * body. A tool call is cheap and repeatable, so the agent makes one per file
+ * without thinking; a skill invocation loads instructions into the
+ * conversation, and invoking it again reads as redundant. In the first A/B the
+ * agent therefore invoked the skill once and enhanced 3 of 5 files, against 5
+ * of 5 with the plugin off. So the routing says the count, and puts the
+ * repeated action on the two tools, which are called once per file however
+ * many times the skill itself is invoked.
+ */
+export declare function enhanceAssertionsCall(testType: string, fileDescription: string): string;

package/build/skills/enhanceAssertionsSkill.js

@@ -0,0 +1,103 @@
+import { getPersonaPrefix } from "../prompts/personas.js";
+import { TestType } from "../types/TestTypes.js";
+import { isSkillsLoaded, isTestbotEnabled } from "../utils/featureFlags.js";
+import { readSkillFile, section, sectionBody, sliceBetween, sliceFrom, sliceUntil, fillPlaceholders, } from "./skillFiles.js";
+/**
+ * The `enhance-assertions` skill ships in `plugin/skills/` at the
+ * package root (SKYR-4310). Its markdown is the single source of the assertion
+ * instructions: Claude Code loads the skill through `--plugin-dir`, and every
+ * other agent gets the same rules assembled from the same files by
+ * `skyramp_enhance_assertions`, whose behaviour is otherwise unchanged.
+ */
+export const ENHANCE_ASSERTIONS_SKILL = "enhance-assertions";
+const TESTBOT_UI_SECTION = "## Additional checks in Testbot runs";
+function reference(name) {
+    return readSkillFile(ENHANCE_ASSERTIONS_SKILL, `reference/${name}.md`);
+}
+/** The shared response-body rules, without the surrounding framing. */
+export function sharedAssertionRules() {
+    return sectionBody(reference("shared-rules"), "## Assertion Rules with Examples");
+}
+/** Full instruction text, assembled from the same markdown the skill reads.
+ *  Used by agents that cannot load the plugin. */
+export function buildEnhanceAssertionsInstructions(testFile, testType, enhanceType) {
+    const shared = reference("shared-rules");
+    // Only the maintenance mode narrows scope; generation keeps the whole file.
+    const scope = enhanceType === "maintenance"
+        ? ` ${sectionBody(shared, "### When maintaining an existing test")}`
+        : "";
+    if (testType === TestType.UI) {
+        const uiRef = reference("ui");
+        const ui = sliceFrom(uiRef, "## First Check");
+        const rules = isTestbotEnabled() ? ui : sliceUntil(ui, TESTBOT_UI_SECTION);
+        // The principle governs every rule below it, so it leads the hand-out too.
+        // Both slicers used to start below it and dropped it silently.
+        const body = `${section(uiRef, "## What to assert")}\n\n${rules}`;
+        // Positional order matches the skill: the two fixed values first, then
+        // the path, so a path containing a space cannot shift them.
+        return fillPlaceholders(`${getPersonaPrefix()}Your task is to enhance assertions for the given UI test file: \`${testFile}\`.${scope}\n\n${body}\n`, [testType, enhanceType, testFile]);
+    }
+    if (testType !== TestType.CONTRACT && testType !== TestType.INTEGRATION) {
+        throw new Error(`Unsupported testType for skyramp_enhance_assertions: ${testType}`);
+    }
+    const body = [
+        section(shared, "## What to assert"),
+        sliceBetween(shared, "## Pre-Edit Assertion Analysis", "## What not to do"),
+        sliceFrom(reference(testType), "## Additional assertion rules"),
+        sliceFrom(shared, "## What not to do"),
+    ].join("\n\n");
+    return fillPlaceholders(`${getPersonaPrefix()}Your task is to enhance response body assertions in the given test file: \`${testFile}\`.${scope}\n\n${body}`, [testType, enhanceType, testFile]);
+}
+/**
+ * The maintenance equivalent, for the UPDATE strategy. It covers a set of
+ * already-edited files rather than one freshly generated file, so it names no
+ * single test type and states the per-file duty over that set.
+ *
+ * This route was the last one still naming the tool literally. Because MCP tool
+ * output beats the prompt on conflict, that one call handed the agent the whole
+ * rule text, and an agent already holding the rules has no reason to invoke the
+ * skill — which is why two A/B runs recorded zero invocations while the
+ * per-file gates worked (SKYR-4310).
+ */
+export function enhanceAssertionsMaintenanceCall() {
+    if (isSkillsLoaded()) {
+        return (`invoke the \`${ENHANCE_ASSERTIONS_SKILL}\` skill for each updated file, with arguments ` +
+            `\`<testType> maintenance <absolute path of the file>\`. Do this for EVERY file you just ` +
+            `edited, one at a time: five updated files means five ` +
+            `\`skyramp_enhance_assertions_snapshot\` calls and five passing ` +
+            `\`skyramp_verify_enhance_assertions\` calls. The snapshot for a file comes after your ` +
+            `maintenance edit and before you add assertions to it — it is the baseline the ` +
+            `verification measures against. Read the skill's rules once, then repeat its per-file ` +
+            `steps for the rest`);
+    }
+    return (`call \`skyramp_enhance_assertions\` once per updated file, with that file's path, its ` +
+        `\`testType\`, and \`enhanceType: "maintenance"\`, and apply every instruction returned to ` +
+        `that file`);
+}
+/** `enhanceAssertionsCall` as a standalone sentence, for a generation result's
+ *  numbered step list. */
+export function enhanceAssertionsStep(testType, fileDescription) {
+    const call = enhanceAssertionsCall(testType, fileDescription);
+    return `${call.charAt(0).toUpperCase()}${call.slice(1)}.`;
+}
+/**
+ * How a prompt or a generation result should tell the agent to enhance
+ * assertions. With the skills plugin loaded the skill owns the whole workflow
+ * — baseline, rules, verification — so naming the tool here would hand the
+ * agent the same rules a second time (SKYR-4310).
+ *
+ * The per-file duty is stated HERE, in the routing text, not left to the skill
+ * body. A tool call is cheap and repeatable, so the agent makes one per file
+ * without thinking; a skill invocation loads instructions into the
+ * conversation, and invoking it again reads as redundant. In the first A/B the
+ * agent therefore invoked the skill once and enhanced 3 of 5 files, against 5
+ * of 5 with the plugin off. So the routing says the count, and puts the
+ * repeated action on the two tools, which are called once per file however
+ * many times the skill itself is invoked.
+ */
+export function enhanceAssertionsCall(testType, fileDescription) {
+    if (isSkillsLoaded()) {
+        return `invoke the \`${ENHANCE_ASSERTIONS_SKILL}\` skill with arguments \`${testType} generation <absolute path of the ${fileDescription}>\` (a project skill with the same name takes precedence over the plugin copy) and follow every step it lists, including its final verification. Do this for EVERY ${fileDescription}, one file at a time. Read the skill's rules once, then repeat its per-file steps for each remaining file — \`skyramp_enhance_assertions_snapshot\` and \`skyramp_verify_enhance_assertions\` are called once per file, so N such files means N snapshot calls and N passing verify calls. Do not re-invoke the skill for a file whose rules you already hold, and do not stop after the first file`;
+    }
+    return `call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the ${fileDescription}, \`testType: "${testType}"\`, and \`enhanceType: "generation"\`, and apply every instruction returned to that file. Do this for EVERY ${fileDescription} — N such files means N calls`;
+}

package/build/skills/fixTestImportErrorsSkill.d.ts

@@ -1,8 +1,8 @@
 /**
  * The `fix-test-import-errors` skill ships in `plugin/skills/` at the package
  * root (SKYR-4296). It carries the same instructions `skyramp_fix_errors`
- * returns, so an agent that loads the plugin follows the skill and an agent
- * that does not keeps calling the tool. The tool itself is unchanged.
+ * returns from the same Markdown, so an agent that loads the plugin follows
+ * the skill and an agent that does not keeps calling the tool.
  */
 export declare const FIX_TEST_IMPORT_ERRORS_SKILL = "fix-test-import-errors";
 /**

package/build/skills/fixTestImportErrorsSkill.js

@@ -2,8 +2,8 @@ import { isSkillsLoaded } from "../utils/featureFlags.js";
 /**
  * The `fix-test-import-errors` skill ships in `plugin/skills/` at the package
  * root (SKYR-4296). It carries the same instructions `skyramp_fix_errors`
- * returns, so an agent that loads the plugin follows the skill and an agent
- * that does not keeps calling the tool. The tool itself is unchanged.
+ * returns from the same Markdown, so an agent that loads the plugin follows
+ * the skill and an agent that does not keeps calling the tool.
  */
 export const FIX_TEST_IMPORT_ERRORS_SKILL = "fix-test-import-errors";
 const FIX_ERRORS_TOOL = "skyramp_fix_errors";

package/build/skills/runTestSkill.d.ts

@@ -0,0 +1,6 @@
+/** The `run-test` skill ships in `plugin/skills/` at the package root. */
+export declare const RUN_TEST_SKILL = "run-test";
+/** How to shape a command for skyramp_execute_test without the skill. */
+export declare const RUN_TEST_COMMAND_RULES: string;
+/** How a prompt tells the agent to run one test file. */
+export declare function runTestCall(): string;

package/build/skills/runTestSkill.js

@@ -0,0 +1,17 @@
+import { isSkillsLoaded } from "../utils/featureFlags.js";
+import { fixErrorsInstruction } from "./fixTestImportErrorsSkill.js";
+/** The `run-test` skill ships in `plugin/skills/` at the package root. */
+export const RUN_TEST_SKILL = "run-test";
+/** How to shape a command for skyramp_execute_test without the skill. */
+export const RUN_TEST_COMMAND_RULES = `for a TypeScript or JavaScript Playwright UI or end-to-end test, add \`--config "$SKYRAMP_PLAYWRIGHT_CONFIG"\`; ` +
+    `find the environment variable the test reads for its base URL — \`SKYRAMP_TEST_BASE_URL\` in a generated test, or the name the repository's own config reads in an existing one — and when the run exports no value for that name, put \`<NAME>=$SKYRAMP_TEST_SERVICE_URL_<SERVICENAME>\` in front of the command, for the service the test targets`;
+/** How a prompt tells the agent to run one test file. */
+export function runTestCall() {
+    if (isSkillsLoaded()) {
+        return (`invoke the \`${RUN_TEST_SKILL}\` skill with arguments ` +
+            `\`<absolute path of the test file> <language> <framework> <test type>\``);
+    }
+    return (`call \`skyramp_execute_test\` with the repository's own command for that one test file, ` +
+        `or the framework's usual command when the repository has none (${RUN_TEST_COMMAND_RULES}). ` +
+        `If the output shows that a package is missing — the runner itself, or a module the test or its config imports — ${fixErrorsInstruction()} and run the test again`);
+}

package/build/skills/skillFiles.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Reader for the Agent Skills shipped in `plugin/skills/` at the package root
+ * (SKYR-4296, SKYR-4310). The markdown files are the single source of the
+ * instruction text: Claude Code loads them through `--plugin-dir`, and every
+ * other agent receives the same text back from the MCP tool that would
+ * otherwise hand out a prompt.
+ */
+/** Absolute path of the shipped `plugin/` directory. */
+export declare function pluginRoot(): string;
+/** Removes a leading YAML frontmatter block, if present. */
+export declare function stripFrontmatter(raw: string): string;
+/** Raw contents of a file inside one skill directory, e.g. `SKILL.md` or
+ *  `reference/ui.md`. */
+export declare function readSkillFile(skillName: string, relPath: string): string;
+/** SKILL.md body with the YAML frontmatter removed. */
+export declare function readSkillBody(skillName: string): string;
+/** Fill positional `$0`, `$1`, ... placeholders in `text` with `values[n]`,
+ *  in one pass. `\$` unescapes to a literal `$`, so `\$19.98` in an example
+ *  reads as itself rather than value 1 followed by "9.98". A placeholder's
+ *  surrounding backticks, if any, are untouched by the match — the regex
+ *  matches only the token, not its context — so a standalone code span
+ *  (`` `$0` ``) and a placeholder nested inside a larger one both come out
+ *  correctly with no extra handling. */
+export declare function fillPlaceholders(text: string, values: string[]): string;
+/** Everything from `heading` (matched as a line prefix) to the end. */
+export declare function sliceFrom(markdown: string, heading: string): string;
+/** Everything before `heading`; the whole text when the heading is absent. */
+export declare function sliceUntil(markdown: string, heading: string): string;
+/** Everything from `heading` up to `until`, exclusive. */
+export declare function sliceBetween(markdown: string, heading: string, until: string): string;
+/** One section including its heading: `heading` plus the lines under it, up to
+ *  the next heading of the same or a higher level. */
+export declare function section(markdown: string, heading: string): string;
+/** Body of one section: the lines under `heading`, up to the next heading of
+ *  the same or a higher level. Lines inside a fenced code block are code, not
+ *  headings — a Python comment in an example starts with `#` and would
+ *  otherwise end the section at the first example that carries one. */
+export declare function sectionBody(markdown: string, heading: string): string;