@skyramp/mcp 0.4.1 → 0.4.2-rc.1

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/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;

package/build/skills/skillFiles.js

@@ -0,0 +1,94 @@
+import { readFileSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+/**
+ * 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 function pluginRoot() {
+    // build/skills/<file>.js or src/skills/<file>.ts → package root → plugin/
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, "..", "..", "plugin");
+}
+/** Removes a leading YAML frontmatter block, if present. */
+export function stripFrontmatter(raw) {
+    const match = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);
+    return match ? raw.slice(match[0].length) : raw;
+}
+/** Raw contents of a file inside one skill directory, e.g. `SKILL.md` or
+ *  `reference/ui.md`. */
+export function readSkillFile(skillName, relPath) {
+    return readFileSync(path.join(pluginRoot(), "skills", skillName, relPath), "utf8");
+}
+/** SKILL.md body with the YAML frontmatter removed. */
+export function readSkillBody(skillName) {
+    return stripFrontmatter(readSkillFile(skillName, "SKILL.md")).trim();
+}
+/** 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 function fillPlaceholders(text, values) {
+    return text.replace(/\\?\$(\d+)/g, (match, index) => {
+        if (match.startsWith("\\"))
+            return match.slice(1);
+        return values[Number(index)] ?? match;
+    });
+}
+function headingIndex(markdown, heading) {
+    // Anchored to line start so a heading quoted mid-paragraph cannot match.
+    if (markdown.startsWith(heading))
+        return 0;
+    const at = markdown.indexOf(`\n${heading}`);
+    return at === -1 ? -1 : at + 1;
+}
+/** Everything from `heading` (matched as a line prefix) to the end. */
+export function sliceFrom(markdown, heading) {
+    const at = headingIndex(markdown, heading);
+    if (at === -1)
+        throw new Error(`markdown section not found: ${heading}`);
+    return markdown.slice(at).trim();
+}
+/** Everything before `heading`; the whole text when the heading is absent. */
+export function sliceUntil(markdown, heading) {
+    const at = headingIndex(markdown, heading);
+    return (at === -1 ? markdown : markdown.slice(0, at)).trim();
+}
+/** Everything from `heading` up to `until`, exclusive. */
+export function sliceBetween(markdown, heading, until) {
+    return sliceUntil(sliceFrom(markdown, heading), until);
+}
+/** One section including its heading: `heading` plus the lines under it, up to
+ *  the next heading of the same or a higher level. */
+export function section(markdown, heading) {
+    const body = sectionBody(markdown, heading);
+    return body ? `${heading}\n\n${body}` : heading;
+}
+/** 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 function sectionBody(markdown, heading) {
+    const level = heading.match(/^#+/)?.[0].length ?? 0;
+    const from = sliceFrom(markdown, heading);
+    const lines = from.split("\n").slice(1);
+    let fenced = false;
+    const end = lines.findIndex((line) => {
+        if (/^\s*(```|~~~)/.test(line)) {
+            fenced = !fenced;
+            return false;
+        }
+        if (fenced)
+            return false;
+        const h = line.match(/^(#+)\s/);
+        return h !== null && h[1].length <= level;
+    });
+    return (end === -1 ? lines : lines.slice(0, end)).join("\n").trim();
+}

package/build/skills/validateAssertionAlignmentSkill.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The `validate-assertion-alignment-post-execution` skill ships in
+ * `plugin/skills/` (same arrangement as fix-test-import-errors). It is the
+ * post-execution check, for an executed test of any type
+ * `ASSERTION_ENHANCEABLE_TEST_TYPES` names (`src/types/TestTypes.ts`), that
+ * its assertions evaluate the one behaviour its plan entry asked for, using
+ * the file's recorded execution result as evidence.
+ */
+export declare const VALIDATE_ASSERTION_ALIGNMENT_SKILL = "validate-assertion-alignment-post-execution";
+/**
+ * The skill's full instructions for one file, with `$0`/`$1` replaced by the
+ * real test type and path — the same content the skill itself reads when
+ * Claude Code loads it, assembled here for an agent that cannot. Mirrors
+ * `buildEnhanceAssertionsInstructions`: built from the shipped markdown via
+ * the shared skillFiles helpers, not a hand-typed paraphrase, and called
+ * from a tool handler with real arguments rather than baked into the
+ * always-sent workflow prompt — reference/evidence.md and reference/checks.md
+ * are each a few hundred words, too much to inline into every run's prompt
+ * whether or not this check ever fires, but entirely reasonable as the
+ * response of a tool call made only when it does.
+ */
+export declare function buildAlignAssertionsInstructions(testFile: string, testType: string): string;
+/**
+ * Mid-sentence clause for the workflow's assertion-alignment step (same
+ * convention as fixErrorsInstruction). Names the skill when the plugin is
+ * loaded — a project skill of the same name overrides the plugin copy — and
+ * falls back to a short hand-off otherwise: the full rules are the response
+ * of `skyramp_align_assertions` (buildAlignAssertionsInstructions), not
+ * repeated here, so this stays a one-line pointer regardless of which branch
+ * fires — matching enhanceAssertionsCall's non-skills branch, which points
+ * at `skyramp_enhance_assertions` the same way rather than inlining its
+ * rules into the prompt.
+ */
+export declare function alignAssertionsStep(): string;

package/build/skills/validateAssertionAlignmentSkill.js

@@ -0,0 +1,59 @@
+import { isSkillsLoaded } from "../utils/featureFlags.js";
+import { readSkillFile, readSkillBody, sectionBody, fillPlaceholders, } from "./skillFiles.js";
+/**
+ * The `validate-assertion-alignment-post-execution` skill ships in
+ * `plugin/skills/` (same arrangement as fix-test-import-errors). It is the
+ * post-execution check, for an executed test of any type
+ * `ASSERTION_ENHANCEABLE_TEST_TYPES` names (`src/types/TestTypes.ts`), that
+ * its assertions evaluate the one behaviour its plan entry asked for, using
+ * the file's recorded execution result as evidence.
+ */
+export const VALIDATE_ASSERTION_ALIGNMENT_SKILL = "validate-assertion-alignment-post-execution";
+function skillBody() {
+    return readSkillBody(VALIDATE_ASSERTION_ALIGNMENT_SKILL);
+}
+function reference(name) {
+    return readSkillFile(VALIDATE_ASSERTION_ALIGNMENT_SKILL, `reference/${name}.md`).trim();
+}
+/**
+ * The skill's full instructions for one file, with `$0`/`$1` replaced by the
+ * real test type and path — the same content the skill itself reads when
+ * Claude Code loads it, assembled here for an agent that cannot. Mirrors
+ * `buildEnhanceAssertionsInstructions`: built from the shipped markdown via
+ * the shared skillFiles helpers, not a hand-typed paraphrase, and called
+ * from a tool handler with real arguments rather than baked into the
+ * always-sent workflow prompt — reference/evidence.md and reference/checks.md
+ * are each a few hundred words, too much to inline into every run's prompt
+ * whether or not this check ever fires, but entirely reasonable as the
+ * response of a tool call made only when it does.
+ */
+export function buildAlignAssertionsInstructions(testFile, testType) {
+    const body = skillBody();
+    const goal = sectionBody(body, "## Goal");
+    const constraints = sectionBody(body, "## Constraints");
+    let steps = sectionBody(body, "## Steps");
+    steps = steps
+        .replace("Otherwise, read `reference/evidence.md`. It names the four inputs — the user's intention, the plan entry (or, for a maintained test, the maintenance verdict), the test `$1`, and the execution result — and where to find each. Do not ask for any of them or invent them.", "Otherwise, the four inputs are below — the user's intention, the plan entry (or, for a maintained test, the maintenance verdict), the test, and the execution result. Do not ask for any of them or invent them.")
+        .replace("Read `reference/checks.md`. Following it, map the behaviour to the assertions in both directions", "Following the checks below, map the behaviour to the assertions in both directions")
+        .replace("as `reference/checks.md` describes", "as the checks below describe");
+    const evidence = reference("evidence").replace("The checks in `reference/checks.md` are about what an assertion proves, not how it is spelled.", "The checks below are about what an assertion proves, not how it is spelled.");
+    const checks = reference("checks");
+    return fillPlaceholders([goal, steps, evidence, checks, constraints].join("\n\n"), [testType, testFile]);
+}
+/**
+ * Mid-sentence clause for the workflow's assertion-alignment step (same
+ * convention as fixErrorsInstruction). Names the skill when the plugin is
+ * loaded — a project skill of the same name overrides the plugin copy — and
+ * falls back to a short hand-off otherwise: the full rules are the response
+ * of `skyramp_align_assertions` (buildAlignAssertionsInstructions), not
+ * repeated here, so this stays a one-line pointer regardless of which branch
+ * fires — matching enhanceAssertionsCall's non-skills branch, which points
+ * at `skyramp_enhance_assertions` the same way rather than inlining its
+ * rules into the prompt.
+ */
+export function alignAssertionsStep() {
+    if (isSkillsLoaded()) {
+        return `invoke the \`${VALIDATE_ASSERTION_ALIGNMENT_SKILL}\` skill once per file with arguments \`<testType> <absolute test file path>\` — type first, path last (a project skill with the same name takes precedence over the plugin copy)`;
+    }
+    return "call `skyramp_align_assertions` once per file with its `testType` and absolute `testFile` path, and follow every instruction it returns — including its own verification and completion-line steps";
+}

package/build/tool-phases.js

@@ -42,6 +42,10 @@ export const TOOLS_WITHOUT_PHASE = new Set([
     "skyramp_modularization",
     "skyramp_reuse_code",
     "skyramp_enhance_assertions",
+    "skyramp_enhance_assertions_snapshot",
+    "skyramp_verify_enhance_assertions",
+    "skyramp_align_assertions",
     "skyramp_preflight_mock_check",
     "skyramp_query_proxy_mocks",
+    "skyramp_verify_test_dependencies",
 ]);

package/build/tools/auth/loginTool.js

@@ -52,7 +52,9 @@ Logging into Skyramp provides access to additional platform features and service
             const recordParams = {
                 prompt: params.prompt,
             };
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => {
+                logger.warning("Analytics event failed", { error: String(err) });
+            });
         }
     });
 }

package/build/tools/auth/logoutTool.js

@@ -50,7 +50,9 @@ Logout from Skyramp platform to end your authenticated session.`,
             const recordParams = {
                 prompt: params.prompt,
             };
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => {
+                logger.warning("Analytics event failed", { error: String(err) });
+            });
         }
     });
 }

package/build/tools/code-refactor/alignAssertionsTool.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAlignAssertionsTool(server: McpServer): void;

package/build/tools/code-refactor/alignAssertionsTool.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { ASSERTION_ENHANCEABLE_TEST_TYPES } from "../../types/TestTypes.js";
+import { AnalyticsService } from "../../services/AnalyticsService.js";
+import { buildAlignAssertionsInstructions } from "../../skills/validateAssertionAlignmentSkill.js";
+import { requireAbsoluteTestFile } from "./assertionOperations.js";
+import { toolError } from "../../utils/utils.js";
+/**
+ * Deterministic-compatibility path for `validate-assertion-alignment-post-execution`,
+ * for an agent that cannot load the Claude Code skill (mirrors why
+ * `skyramp_enhance_assertions` exists alongside the `enhance-assertions` skill,
+ * SKYR-4310). Renders the skill's full procedure — Goal, Steps, both reference
+ * files, Constraints — from the same shipped markdown the skill itself reads,
+ * with `$0`/`$1` replaced by the real test type and file path. No state is
+ * read or written here; the returned text is the same instructions either
+ * path ends up following.
+ */
+const TOOL_NAME = "skyramp_align_assertions";
+const alignAssertionsSchema = {
+    testFile: z
+        .string()
+        .describe("Absolute path to the test file whose assertion alignment is being checked."),
+    testType: z
+        .enum(ASSERTION_ENHANCEABLE_TEST_TYPES)
+        .describe("The type of the test being checked."),
+};
+export function registerAlignAssertionsTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: `Get the post-execution assertion-alignment procedure for one test file.
+
+### When to call
+- Once per file, after its final execution is settled — it passed, or it failed at an assertion (not at a collection, import, fixture, or navigation error, which the execution-repair step owns instead).
+- For each ${ASSERTION_ENHANCEABLE_TEST_TYPES.join(", ")} test, new or maintained.
+
+Returns the full procedure for that file: read it, then follow every step, including its own verification and completion-line steps.`,
+        inputSchema: alignAssertionsSchema,
+    }, async (params) => {
+        const { testFile, testType } = params;
+        const pathError = requireAbsoluteTestFile(testFile);
+        if (pathError)
+            return toolError(pathError);
+        const instructions = buildAlignAssertionsInstructions(testFile, testType);
+        AnalyticsService.pushMCPToolEvent(TOOL_NAME, undefined, {
+            testFile,
+            testType,
+        }).catch(() => { });
+        return {
+            content: [{ type: "text", text: instructions }],
+            isError: false,
+        };
+    });
+}