@skyramp/mcp 0.4.1 → 0.4.2-rc.2

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

@@ -15,7 +15,6 @@ export const TOOL_PHASE_MAP = {
     skyramp_generate_enriched_integration_test: "generating",
     skyramp_enrich_test_with_mocks: "generating",
     skyramp_execute_test: { before: "maintaining", after: "executing" },
-    skyramp_run_existing_tests: { before: "maintaining", after: "executing" },
     skyramp_analyze_test_health: "maintaining",
     skyramp_submit_report: "reporting",
 };
@@ -42,6 +41,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/budgetExcuse.d.ts

@@ -0,0 +1,15 @@
+/** True when this answer's reason for dropping a test is that the run was running
+ *  out. Blank answers are NOT this: an unanswered objection is published open,
+ *  which is already honest. */
+export declare function citesBudget(answer: string | undefined): boolean;
+/** How many times the report may be refused for this. The refusal is meant to
+ *  cost the agent the tests it dropped, not the whole run: past this the answer
+ *  stands and is published with the report, where a reader can weigh it. Same
+ *  bound and same reasoning as the unrecorded-UI gate. */
+export declare const MAX_BUDGET_EXCUSE_REFUSALS = 3;
+/** Count one refusal and return the new total. */
+export declare function countBudgetExcuseRefusal(): number;
+/** Refusals so far, without counting one. */
+export declare function budgetExcuseRefusals(): number;
+/** Test seam. */
+export declare function resetBudgetExcuseStoreForTests(): void;

package/build/tools/budgetExcuse.js

@@ -0,0 +1,113 @@
+import { currentRunStateFile } from "../utils/AnalysisStateManager.js";
+import { logger } from "../utils/logger.js";
+/** "The run ran out of budget" as a reason a planned test was dropped, and how
+ *  many times the report has been refused for giving it.
+ *
+ *  WHY THIS EXISTS. `deliveredMatchesPlan` raises "planned but not delivered" and
+ *  suggests "add the test to the report, or record in the report why it was
+ *  dropped". Run 9dfc8405 recorded the reason seven times — "this run exhausted
+ *  its working budget" — and shipped 2 of 9 planned tests with the report
+ *  accepted. It wrote that at 46% of a 1M context window, with no warning from
+ *  anywhere, and the word appears NOWHERE in its reasoning: it is a justification
+ *  written at submit time, not a decision reached from a reading.
+ *
+ *  So this is not a budget check. It is a check on ONE SENTENCE the run is not
+ *  entitled to write. A test blocked by something outside the run — a service
+ *  that is not running, a branch that is gone, a credential the run lacks — still
+ *  answers and still ships, exactly as before. */
+/** Phrases that say "I stopped because I was running out", and nothing else.
+ *
+ *  Deliberately narrow, and narrowed further after review: `budget` and `token
+ *  limit` are ORDINARY APPLICATION NOUNS. An unscoped `\bbudget\b` refuses "the
+ *  budget page does not render: /budgets returns 500", and an unscoped `token
+ *  limit` refuses "the API rejects the request past its token limit" — real
+ *  blockers on a customer whose product has budgets, unreachable on any eval
+ *  repo, and nothing here is gated on the gauge, so the collision is the whole
+ *  test.
+ *
+ *  Every answer run 9dfc8405 sent is run-scoped — "this run exhausted its
+ *  working budget", "for budget reasons" — so scoping costs nothing. A miss
+ *  costs a refusal that would have helped; a false positive costs a run that
+ *  cannot report a genuine blocker, which is far worse. */
+const BUDGET_EXCUSE = [
+    // "for budget reasons" / "for budgetary reasons" — no other reading.
+    /\bbudget(ary)? reasons?\b/i,
+    // A spending verb beside the budget: "exhausted its working budget", "the
+    // remaining budget". SINGULAR ONLY — a product's own budgets are a plural
+    // list ("the remaining budgets are empty") and are not this.
+    /\b(exhausted|spent|ran out of|out of|low on|remaining|no more)\b[^.;]{0,24}\bbudget\b/i,
+    // "no budget left for", "not enough context left". The trailing word is what
+    // keeps "the page has no time zone selector" out.
+    /\b(no|insufficient|not enough) (time|context|tokens?|budget) (left|remaining|available|to spare|for)\b/i,
+    // The run's own context. Not a domain noun in any application we test.
+    /\bcontext (window|limit|budget)\b/i,
+    /\b(low on|out of|ran out of|exhausted (its|the|my)?) ?(context|time)\b/i,
+    /\btime (ran out|constraints?|pressure)\b/i,
+    // A token BUDGET is the agent talking about itself; a token LIMIT is a real
+    // API concept and stays out.
+    /\btokens? budget\b/i,
+    // Tokens only with the run as the subject: a rate limiter runs out of tokens
+    // too, and says so in a sentence a blocker needs.
+    /\b(this run|the run|I|we)\b[^.;]{0,30}\b(ran out of|out of|low on|exhausted)\b[^.;]{0,12}\btokens?\b/i,
+];
+/** True when this answer's reason for dropping a test is that the run was running
+ *  out. Blank answers are NOT this: an unanswered objection is published open,
+ *  which is already honest. */
+export function citesBudget(answer) {
+    const text = typeof answer === "string" ? answer.trim() : "";
+    if (!text)
+        return false;
+    return BUDGET_EXCUSE.some((pattern) => pattern.test(text));
+}
+/** How many times the report may be refused for this. The refusal is meant to
+ *  cost the agent the tests it dropped, not the whole run: past this the answer
+ *  stands and is published with the report, where a reader can weigh it. Same
+ *  bound and same reasoning as the unrecorded-UI gate. */
+export const MAX_BUDGET_EXCUSE_REFUSALS = 3;
+/** In process and keyed by the run, for the reason `traceExportStore` gives: the
+ *  only reader shares a process with the tool, and `NO_RUN` is a slot like any
+ *  other so a run whose state path will not resolve is still bounded. */
+const NO_RUN = "<no-run>";
+let countedRunStateFile;
+let refusals = 0;
+function reseatRun() {
+    let runStateFile;
+    try {
+        runStateFile = currentRunStateFile() ?? NO_RUN;
+    }
+    catch {
+        runStateFile = NO_RUN;
+    }
+    if (runStateFile !== countedRunStateFile) {
+        countedRunStateFile = runStateFile;
+        refusals = 0;
+    }
+}
+/** Count one refusal and return the new total. */
+export function countBudgetExcuseRefusal() {
+    try {
+        reseatRun();
+        refusals += 1;
+        return refusals;
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        logger.warning(`countBudgetExcuseRefusal failed: ${detail}`);
+        return MAX_BUDGET_EXCUSE_REFUSALS;
+    }
+}
+/** Refusals so far, without counting one. */
+export function budgetExcuseRefusals() {
+    try {
+        reseatRun();
+        return refusals;
+    }
+    catch {
+        return MAX_BUDGET_EXCUSE_REFUSALS;
+    }
+}
+/** Test seam. */
+export function resetBudgetExcuseStoreForTests() {
+    countedRunStateFile = undefined;
+    refusals = 0;
+}

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,
+        };
+    });
+}

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

@@ -79,7 +79,7 @@ export type RepoCheckoutRef = RepoCheckout;
 export declare function findAssertionRecordByFileName(outcomes: Record<string, AssertionRecord>, row: {
     fileName: string;
     testType?: string;
-    repository?: string;
+    repository: string;
 }, checkouts: RepoCheckoutRef[]): AssertionRecord | undefined;
 /**
  * Report-facing proof-of-work summary re-derived from the spec as delivered

package/build/tools/code-refactor/assertion-state.js

@@ -54,7 +54,7 @@ preloaded) {
         const next = patch(data.assertionOutcomes?.[key]);
         if (next === undefined)
             return false;
-        await manager.writeData({
+        await manager.appendData({
             ...data,
             assertionOutcomes: {
                 ...data.assertionOutcomes,

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

@@ -0,0 +1,44 @@
+/**
+ * The deterministic half of assertion enhancement, shared by
+ * `skyramp_enhance_assertions` and by the two single-purpose tools the
+ * `enhance-assertions` skill drives (SKYR-4310). One implementation, so the
+ * skill workflow and the original tool can never diverge on the gates, the
+ * baseline, or the verdict.
+ */
+export interface AssertionCallParams {
+    testFile: string;
+    testType: string;
+    enhanceType: string;
+    stateFile?: string;
+}
+/**
+ * Reject a relative test-file path: everything downstream keys state by this
+ * path, and a relative spelling would fork records and fail gates open
+ * (review finding on SKYR-4262). Shared with `skyramp_align_assertions`,
+ * whose post-execution check keys the same `testExecutions` state by this
+ * path but needs neither the reuse-debt gate nor the retrofit staging below,
+ * both generation-time concerns.
+ */
+export declare function requireAbsoluteTestFile(testFile: string): string | undefined;
+/**
+ * Everything both entry points must do before either branch: reject a relative
+ * path, stage the shared utils file, and run the reuse-debt gate.
+ *
+ * Returns the gate's refusal message, or undefined when the call may proceed.
+ */
+export declare function prepareAssertionCall(params: AssertionCallParams): Promise<string | undefined>;
+/**
+ * Snapshot the file as generated so a later verify pass has a baseline to
+ * measure against. Best-effort — no run state means a stateless verify later.
+ */
+export declare function snapshotAssertionBaseline(params: AssertionCallParams): Promise<void>;
+export interface AssertionVerifyOutcome {
+    ok: boolean;
+    report: string;
+}
+/**
+ * Deterministically check the hand-out instructions were applied — hash delta,
+ * no removed coverage, rubric lints, strength increase — and format the
+ * per-violation feedback that drives the fix-and-retry loop.
+ */
+export declare function verifyAssertionCall(params: AssertionCallParams): Promise<AssertionVerifyOutcome>;

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

@@ -0,0 +1,82 @@
+import * as path from "path";
+import { pendingReuseDebt } from "./reuse-state.js";
+import { baselineFrom, readAssertionRecord, recordAssertionBaseline, recordAssertionVerdict, trustedRecord, } from "./assertion-state.js";
+import { formatAssertionVerifyReport, verifyAssertionEnhancement, } from "../../utils/assertion-verify/index.js";
+import { stageAndRecordRetrofits } from "./retrofit-state.js";
+import { stageGeneratedPaths } from "../../utils/gitStaging.js";
+/**
+ * Reject a relative test-file path: everything downstream keys state by this
+ * path, and a relative spelling would fork records and fail gates open
+ * (review finding on SKYR-4262). Shared with `skyramp_align_assertions`,
+ * whose post-execution check keys the same `testExecutions` state by this
+ * path but needs neither the reuse-debt gate nor the retrofit staging below,
+ * both generation-time concerns.
+ */
+export function requireAbsoluteTestFile(testFile) {
+    if (!path.isAbsolute(testFile)) {
+        return `testFile must be an absolute path, got: ${testFile}`;
+    }
+    return undefined;
+}
+/**
+ * Everything both entry points must do before either branch: reject a relative
+ * path, stage the shared utils file, and run the reuse-debt gate.
+ *
+ * Returns the gate's refusal message, or undefined when the call may proceed.
+ */
+export async function prepareAssertionCall(params) {
+    const { testFile, testType, stateFile } = params;
+    const pathError = requireAbsoluteTestFile(testFile);
+    if (pathError)
+        return pathError;
+    // SKYR-4115: the reuse tool hands out POM mapping instructions and then relies on
+    // the agent to come back with `verify: true` — the call that runs the zero-reuse
+    // gate. This is the first tool called after it on the same spec, so it is where a
+    // skipped verify is caught cheapest. Enforcing the call (not the outcome) keeps
+    // the policy in the reuse phase where it belongs.
+    // SKYR-4220: stage the shared utils file this spec wrote or imports BEFORE the
+    // debt check, unconditionally — so the file reaches the output commit even on a
+    // path where the agent never calls verify. Located by header, not by name.
+    await stageAndRecordRetrofits(testFile);
+    const owed = await pendingReuseDebt(testFile, stateFile, testType, {
+        chain: false,
+    });
+    if (owed)
+        return owed;
+    // Stage so testbot includes the generated files in its output commit.
+    await stageGeneratedPaths(testFile);
+    return undefined;
+}
+/**
+ * Snapshot the file as generated so a later verify pass has a baseline to
+ * measure against. Best-effort — no run state means a stateless verify later.
+ */
+export async function snapshotAssertionBaseline(params) {
+    await recordAssertionBaseline(params.testFile, params.testType, params.enhanceType, params.stateFile);
+}
+/**
+ * Deterministically check the hand-out instructions were applied — hash delta,
+ * no removed coverage, rubric lints, strength increase — and format the
+ * per-violation feedback that drives the fix-and-retry loop.
+ */
+export async function verifyAssertionCall(params) {
+    const { testFile, testType, enhanceType, stateFile } = params;
+    const record = await readAssertionRecord(testFile, stateFile);
+    // Discriminators come from the persisted record when it matches this
+    // canonical path — params are agent-supplied, and flipping enhanceType
+    // to "maintenance" would disarm the strength gate and structural lints
+    // for a permanent PASS. Canonical comparison closes the alias bypass
+    // (dir//x.spec.ts). Falls back to params only when stateless.
+    const trusted = trustedRecord(record, testFile);
+    const result = await verifyAssertionEnhancement({
+        testFile,
+        testType: trusted?.testType ?? testType,
+        enhanceType: (trusted?.enhanceType ?? enhanceType),
+        baseline: baselineFrom(record, testFile),
+    });
+    await recordAssertionVerdict(testFile, result, stateFile);
+    return {
+        ok: result.ok,
+        report: formatAssertionVerifyReport(result, testFile),
+    };
+}

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

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

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

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import { ASSERTION_ENHANCEABLE_TEST_TYPES } from "../../types/TestTypes.js";
+import { AnalyticsService } from "../../services/AnalyticsService.js";
+import { toolError } from "../../utils/utils.js";
+import { prepareAssertionCall, snapshotAssertionBaseline, verifyAssertionCall, } from "./assertionOperations.js";
+/**
+ * The two halves of `skyramp_enhance_assertions`' deterministic work, exposed
+ * as single-purpose tools so the `enhance-assertions` skill can drive the
+ * workflow itself: snapshot, apply the rules, verify (SKYR-4310).
+ *
+ * They share one implementation with the original tool, and are registered
+ * only when the skills plugin is loaded — with it off, nothing invokes them
+ * and no agent pays for their schemas.
+ */
+const SNAPSHOT_TOOL_NAME = "skyramp_enhance_assertions_snapshot";
+const VERIFY_TOOL_NAME = "skyramp_verify_enhance_assertions";
+const sharedSchema = {
+    testFile: z
+        .string()
+        .describe("Absolute path to the generated or updated test file whose assertions are being enhanced."),
+    testType: z
+        .enum(ASSERTION_ENHANCEABLE_TEST_TYPES)
+        .describe("The type of test whose assertions are being enhanced. Contract applies to provider contract tests only, not consumer contract tests."),
+    enhanceType: z
+        .enum(["generation", "maintenance"])
+        .describe("The context of the enhancement. " +
+        "Use 'generation' after generating a new test file (applies to every test function). " +
+        "Use 'maintenance' during drift UPDATE (applies only to new or diff-affected functions)."),
+    stateFile: z
+        .string()
+        .optional()
+        .describe("Path to the run state file, when the run has one."),
+};
+export function registerAssertionSnapshotTool(server) {
+    server.registerTool(SNAPSHOT_TOOL_NAME, {
+        description: `Record the assertion baseline for a test file BEFORE its assertions are enhanced. Returns no instructions — the \`enhance-assertions\` skill carries those. Call this first, apply the rules, then call ${VERIFY_TOOL_NAME}.`,
+        inputSchema: sharedSchema,
+    }, async (params) => {
+        const refusal = await prepareAssertionCall(params);
+        if (refusal)
+            return toolError(refusal);
+        await snapshotAssertionBaseline(params);
+        AnalyticsService.pushMCPToolEvent(SNAPSHOT_TOOL_NAME, undefined, {
+            testFile: params.testFile,
+            testType: params.testType,
+            enhanceType: params.enhanceType,
+        }).catch(() => { });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Assertion baseline recorded for \`${params.testFile}\`. Apply the assertion rules, then call ${VERIFY_TOOL_NAME} with the same arguments.`,
+                },
+            ],
+            isError: false,
+        };
+    });
+}
+export function registerAssertionVerifyTool(server) {
+    server.registerTool(VERIFY_TOOL_NAME, {
+        description: `Deterministically verify the assertion enhancement of a test file against the baseline ${SNAPSHOT_TOOL_NAME} recorded. Returns PASS, or FAIL with per-violation remediations. Fix every violation and call again until it passes.`,
+        inputSchema: sharedSchema,
+    }, async (params) => {
+        const refusal = await prepareAssertionCall(params);
+        if (refusal)
+            return toolError(refusal);
+        try {
+            const { ok, report } = await verifyAssertionCall(params);
+            AnalyticsService.pushMCPToolEvent(VERIFY_TOOL_NAME, undefined, {
+                testFile: params.testFile,
+                testType: params.testType,
+                enhanceType: params.enhanceType,
+                verifyPassed: ok,
+            }).catch(() => { });
+            return {
+                content: [{ type: "text", text: report }],
+                // isError on FAILED forces the fix-and-retry loop.
+                isError: !ok,
+            };
+        }
+        catch (err) {
+            // Not necessarily the test file — state reads can throw here too.
+            return toolError(`${VERIFY_TOOL_NAME} failed for ${params.testFile}: ${err.message}`);
+        }
+    });
+}