@skyramp/mcp 0.3.6 → 0.3.8

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

@@ -0,0 +1,375 @@
+import * as path from "path";
+import { realpathSync } from "fs";
+import { mkdir, readFile, rm, writeFile } from "fs/promises";
+import { logger } from "../../utils/logger.js";
+import { resolveRunStatePath, StateManager, } from "../../utils/AnalysisStateManager.js";
+import { computeAssertionMetrics, detectAssertionLanguage, formatAssertionVerifyReport, sha256Of, verifyAssertionEnhancement, } from "../../utils/assertion-verify/index.js";
+/**
+ * Persistence for the assertion-enhancement verification loop, keyed by the
+ * spec's CANONICAL absolute path in `UnifiedAnalysisState.assertionOutcomes`.
+ * Path keying (not basename, unlike reuseOutcomes — nothing here needs to
+ * match report rows) removes the multi-repo basename-collision class outright,
+ * and canonicalization closes the alias bypass: `dir//x.spec.ts` and
+ * `dir/./x.spec.ts` must hit the same record as `dir/x.spec.ts`.
+ *
+ * Every write is best-effort: verification must never be able to fail an
+ * enhancement that otherwise succeeded, so a missing/unreadable state file
+ * degrades to stateless checks and open gates — always with a warning.
+ */
+/** Canonical identity of a test file — all keying and ownership comparisons
+ *  go through this so a non-normalized agent-supplied path cannot fork or
+ *  bypass a record. realpath also collapses symlinked directories; a path
+ *  that does not (yet) exist falls back to plain resolution. */
+export function canonicalTestPath(testFile) {
+    const resolved = path.resolve(testFile);
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+/** Read-modify-write one spec's record. The patch sees the existing record
+ *  (or undefined) and returns the COMPLETE next record — or undefined to skip
+ *  the write (e.g. a verdict for a record that does not exist). Returns true
+ *  only when the record was actually written. */
+async function updateAssertionOutcome(testFile, patch, explicitStateFile, 
+// State the caller already read for THIS file — skips the re-read (each
+// gate call was re-parsing the same run-state JSON up to 8 times).
+preloaded) {
+    const stateFile = resolveRunStatePath(explicitStateFile);
+    if (!stateFile)
+        return false;
+    try {
+        const manager = StateManager.fromStatePath(stateFile);
+        const data = preloaded ?? (await manager.readData());
+        if (!data) {
+            // A resolvable path is not proof of a run (this repo's own CI sets
+            // RUNNER_TEMP): the state file simply doesn't exist. Say so — silently
+            // returning here disables the whole gate for the run with no trace.
+            logger.warning("Run state file not found — assertion-enhancement state not recorded, verification gate inactive", { stateFile, testFile });
+            return false;
+        }
+        const key = canonicalTestPath(testFile);
+        const next = patch(data.assertionOutcomes?.[key]);
+        if (next === undefined)
+            return false;
+        await manager.writeData({
+            ...data,
+            assertionOutcomes: {
+                ...data.assertionOutcomes,
+                [key]: next,
+            },
+        });
+        return true;
+    }
+    catch (err) {
+        logger.warning("Could not record assertion-enhancement state", {
+            testFile,
+            error: String(err),
+        });
+        return false;
+    }
+}
+/** The state files a record may live in: the explicitly supplied one first,
+ *  then the run-default path. Callers thread `stateFile` inconsistently across
+ *  tools (enhance may record to the default while execute checks an explicit
+ *  path, or vice versa) — reading both closes the asymmetry that otherwise
+ *  fails the gate open on a mismatched `stateFile`. */
+function candidateStateFiles(explicitStateFile) {
+    const explicit = resolveRunStatePath(explicitStateFile);
+    const fallback = resolveRunStatePath(undefined);
+    return [...new Set([explicit, fallback])].filter((p) => p !== undefined);
+}
+/** The record and the state file it actually lives in, or undefined. */
+async function locateAssertionRecord(testFile, explicitStateFile) {
+    for (const stateFile of candidateStateFiles(explicitStateFile)) {
+        try {
+            const data = await StateManager.fromStatePath(stateFile).readData();
+            const record = data?.assertionOutcomes?.[canonicalTestPath(testFile)];
+            if (data && record !== undefined)
+                return { record, stateFile, data };
+        }
+        catch (err) {
+            logger.warning("Could not read a candidate run state file for the assertion record — trying the next", { stateFile, testFile, error: String(err) });
+        }
+    }
+    return undefined;
+}
+/** A record only counts for `testFile` when its stored path canonicalizes to
+ *  the same spec — the single home for the ownership invariant (previously
+ *  copied in baselineFrom, recordAssertionVerdict, and the enhance tool). */
+export function trustedRecord(record, testFile) {
+    return record !== undefined &&
+        canonicalTestPath(record.testFilePath) === canonicalTestPath(testFile)
+        ? record
+        : undefined;
+}
+/** One spec's record, or undefined when there is no run state / no record. */
+export async function readAssertionRecord(testFile, explicitStateFile) {
+    return (await locateAssertionRecord(testFile, explicitStateFile))?.record;
+}
+/**
+ * Snapshot the file at instruction hand-out time — the baseline verify measures
+ * against. Keep-first rule: while no Passed verdict exists for the same file and
+ * enhanceType, a repeat hand-out does NOT re-baseline (re-calling the tool after
+ * half-editing must not shrink the required delta). A hand-out after a Passed
+ * verdict, or with a different enhanceType, starts a new enhancement round.
+ */
+export async function recordAssertionBaseline(testFile, testType, enhanceType, explicitStateFile) {
+    const stateFile = resolveRunStatePath(explicitStateFile);
+    if (!stateFile)
+        return;
+    try {
+        // Probe the state file BEFORE writing the baseline copy: a resolvable path
+        // with no state file (RUNNER_TEMP set, no analyze-changes run) must not
+        // leave an orphan copy behind while the record write silently no-ops.
+        const data = await StateManager.fromStatePath(stateFile).readData();
+        if (!data) {
+            logger.warning("Run state file not found — assertion baseline not recorded, verification gate inactive for this file", { stateFile, testFile });
+            return;
+        }
+        const canonical = canonicalTestPath(testFile);
+        const existing = data.assertionOutcomes?.[canonical];
+        if (existing?.fileSha256 !== undefined &&
+            existing.verification !== "passed" &&
+            existing.enhanceType === enhanceType) {
+            return;
+        }
+        const content = await readFile(testFile, "utf8");
+        const sha = sha256Of(content);
+        const language = detectAssertionLanguage(testFile);
+        const metrics = language
+            ? computeAssertionMetrics(content, language)
+            : undefined;
+        const baselineFilePath = await saveBaselineCopy(stateFile, canonical, sha, content);
+        const written = await updateAssertionOutcome(testFile, 
+        // Full replacement — a new enhancement round resets any earlier verdict.
+        // Only executionCount survives: executions already happened regardless
+        // of which round's instructions were in force.
+        (previous) => ({
+            testFilePath: canonical,
+            testType,
+            executionCount: previous?.executionCount ?? 0,
+            enhanceType,
+            fileSha256: sha,
+            baselineFilePath,
+            baselineCount: metrics?.count,
+            baselineStrength: metrics?.strengthScore,
+            baselineFingerprints: metrics?.fingerprints,
+            issuedAt: new Date().toISOString(),
+        }), explicitStateFile, data);
+        // A failed record write must not strand an orphan copy nobody references.
+        if (!written && baselineFilePath !== undefined) {
+            await rm(baselineFilePath, { force: true }).catch(() => { });
+        }
+    }
+    catch (err) {
+        logger.warning("Could not record assertion baseline — verification will run stateless checks only", { testFile, error: String(err) });
+    }
+}
+/**
+ * Preserve the generated file as delivered at hand-out time, beside the run
+ * state (never in the repo — a repo sidecar could leak into the customer
+ * commit and would need its own cleanup step, like the reuse flow's .raw.bak).
+ * The sha prefix disambiguates basename collisions across repos and rounds.
+ * Best-effort: an unsaved copy costs the diff/restore aid, not the baseline.
+ */
+async function saveBaselineCopy(stateFile, testFile, sha, content) {
+    try {
+        const dir = path.join(path.dirname(stateFile), "assertion-baselines");
+        await mkdir(dir, { recursive: true });
+        const copyPath = path.join(dir, `${sha.slice(0, 8)}-${path.basename(testFile)}`);
+        await writeFile(copyPath, content, "utf8");
+        return copyPath;
+    }
+    catch (err) {
+        logger.warning("Could not save the assertion baseline copy", {
+            testFile,
+            error: String(err),
+        });
+        return undefined;
+    }
+}
+/** The baseline verify measures against, from a record; undefined when the
+ *  record carries no snapshot or belongs to a different canonical path. */
+export function baselineFrom(record, testFile) {
+    if (record?.fileSha256 === undefined)
+        return undefined;
+    if (trustedRecord(record, testFile) === undefined)
+        return undefined;
+    return {
+        fileSha256: record.fileSha256,
+        count: record.baselineCount,
+        strengthScore: record.baselineStrength,
+        fingerprints: record.baselineFingerprints,
+        baselineFilePath: record.baselineFilePath,
+    };
+}
+/** Record what one verify pass established. The verdict is written to the
+ *  state file the record actually LIVES in (not blindly to the explicit path —
+ *  a mismatched `stateFile` would otherwise split verdict from baseline).
+ *  Never writes onto a record owned by a different canonical path, and never
+ *  fails silently. */
+export async function recordAssertionVerdict(testFile, result, explicitStateFile) {
+    let home;
+    let homeData;
+    try {
+        const located = await locateAssertionRecord(testFile, explicitStateFile);
+        home = located?.stateFile;
+        homeData = located?.data;
+        if (located !== undefined &&
+            trustedRecord(located.record, testFile) === undefined) {
+            logger.warning("Assertion verdict not recorded — the record is owned by a different spec path", { testFile, recordedPath: located.record.testFilePath });
+            return;
+        }
+    }
+    catch (err) {
+        logger.warning("Assertion verdict not recorded — could not read the run state", { testFile, error: String(err) });
+        return;
+    }
+    await updateAssertionOutcome(testFile, 
+    // A verdict amends an existing record; without one there is nothing the
+    // verdict is ABOUT (verify-with-no-baseline records a baseline instead,
+    // never a verdict), so skip the write rather than invent a partial record.
+    (existing) => existing === undefined
+        ? undefined
+        : {
+            ...existing,
+            verification: result.ok ? "passed" : "failed",
+            declinedReason: result.markerReason,
+        }, home ?? explicitStateFile, homeData);
+}
+/**
+ * Deterministic execute-time verification: skyramp_execute_test calls this
+ * itself, so the check runs whether or not the agent ever called `verify: true`
+ * — a prose instruction can be ignored, a server-side call cannot. Returns the
+ * feedback text when the assertions are insufficient (the caller returns it
+ * instead of executing), or undefined to proceed.
+ *
+ * Self-clearing: the checks run on the file's CURRENT content, so fixing the
+ * assertions and re-executing passes — no separate verify call is required.
+ * Skipped once a verdict has PASSED: sanctioned later rewrites (a `.raw.bak`
+ * restore during execution fix-up) would otherwise false-fail the differential
+ * gates. Modularization needs no special handling: the shared-helper policy
+ * keeps every value assertion in the test body, so the baseline comparison
+ * stays valid across it. Fails open on no baseline and unreadable state/file.
+ */
+export async function assertionFeedbackForExecution(testFile, explicitStateFile) {
+    try {
+        const record = await readAssertionRecord(testFile, explicitStateFile);
+        if (record === undefined)
+            return undefined;
+        const baseline = baselineFrom(record, testFile);
+        if (baseline === undefined)
+            return undefined;
+        if (record.verification === "passed")
+            return undefined;
+        const result = await verifyAssertionEnhancement({
+            testFile,
+            testType: record.testType,
+            // The baseline writer sets enhanceType with the snapshot, so a record
+            // with a baseline always carries it; a hand-truncated state file
+            // defaults to the STRICTER mode rather than deferring execution.
+            enhanceType: record.enhanceType ?? "generation",
+            baseline,
+        });
+        await recordAssertionVerdict(testFile, result, explicitStateFile);
+        if (result.ok)
+            return undefined;
+        return (`Execution deferred — the assertion enhancement of ${path.basename(testFile)} is insufficient. ` +
+            `Fix the violations below, then call skyramp_execute_test again (it re-checks the file automatically; ` +
+            `you can also get early feedback anytime via skyramp_enhance_assertions with verify: true).\n\n` +
+            formatAssertionVerifyReport(result, testFile));
+    }
+    catch (err) {
+        logger.warning("Could not verify assertion enhancement at execution time — proceeding", { testFile, error: String(err) });
+        return undefined;
+    }
+}
+/**
+ * Count one execution of this spec (called by skyramp_execute_test after its
+ * gates pass, best-effort). Creates a minimal record when none exists so an
+ * executed-but-never-enhanced spec is still visible to the report cross-check.
+ */
+export async function recordAssertionExecution(testFile, testType, explicitStateFile) {
+    const located = await locateAssertionRecord(testFile, explicitStateFile).catch(() => undefined);
+    await updateAssertionOutcome(testFile, (existing) => existing === undefined
+        ? {
+            testFilePath: canonicalTestPath(testFile),
+            testType,
+            executionCount: 1,
+        }
+        : { ...existing, executionCount: existing.executionCount + 1 }, located?.stateFile ?? explicitStateFile, located?.data);
+}
+/** The record for a report row, matched by the canonical-path keys' basenames
+ *  and then GUARDED: the record's testType must match the row's, and when the
+ *  run's checkouts are known, the record's path must live in the row's repo
+ *  (primary when the row names none). Without the guards, a basename shared
+ *  across repos published one spec's proof-of-work under another's name — and
+ *  the victim was exactly the never-enhanced spec the field exists to expose.
+ *  Ambiguity after filtering still fails open: wrong attribution is worse
+ *  than omission. */
+export function findAssertionRecordByFileName(outcomes, row, checkouts) {
+    const base = path.basename(row.fileName);
+    const matches = Object.entries(outcomes).filter(([key, record]) => {
+        if (path.basename(key) !== base)
+            return false;
+        if (row.testType !== undefined && record.testType !== row.testType) {
+            return false;
+        }
+        if (checkouts.length > 0) {
+            const home = checkouts.find((c) => record.testFilePath.startsWith(c.root + path.sep));
+            // A record living in a KNOWN checkout must belong to the row's repo
+            // (rows without a repository belong to the primary). A record outside
+            // every known checkout stays eligible — fail open on the guard itself.
+            if (home) {
+                const rowIsPrimary = row.repository === undefined;
+                if (rowIsPrimary ? !home.primary : home.repository !== row.repository) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    });
+    return matches.length === 1 ? matches[0][1] : undefined;
+}
+/**
+ * Report-facing proof-of-work summary re-derived from the spec as delivered
+ * NOW — final metrics come from the file, not from verify-time state, so
+ * post-verify edits cannot publish stale counts. Always returns the status
+ * fields (verification, declinedReason, executionCount — they come from the
+ * record); the metric fields are omitted when the file cannot supply them.
+ */
+export async function rederiveAssertionOutcome(record) {
+    const { testFilePath, verification, declinedReason } = record;
+    const base = {
+        verification: verification ?? "never-verified",
+        declinedReason,
+        executionCount: record.executionCount,
+    };
+    try {
+        // Metrics exist only for the languages the analyzer supports (python, ts,
+        // js, java). Maintained rows can point at other languages the discovery
+        // patterns accept (go, ruby, php) — those report status without metrics.
+        const language = detectAssertionLanguage(testFilePath);
+        if (language === undefined)
+            return base;
+        const metrics = computeAssertionMetrics(await readFile(testFilePath, "utf8"), language);
+        return {
+            ...base,
+            assertionsBaseline: record.baselineCount,
+            assertionsFinal: metrics.count,
+            strengthBaseline: record.baselineStrength,
+            strengthFinal: metrics.strengthScore,
+        };
+    }
+    catch (err) {
+        // readFile is the only throw here: the delivered spec is gone or
+        // unreadable at report time (deleted after execution, permissions).
+        // Deterministic — a retry would re-read the same missing file — so
+        // report the status fields and omit the metrics.
+        logger.warning("Could not re-derive the assertion outcome from the delivered spec — omitting metrics from the report", { testFile: testFilePath, error: String(err) });
+        return base;
+    }
+}

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

@@ -1,3 +1,4 @@
+import { stageAndRecordRetrofits } from "./retrofit-state.js";
 import { z } from "zod";
 import * as path from "path";
 import { logger } from "../../utils/logger.js";
@@ -7,9 +8,9 @@ import { isPomAwareTarget } from "../../utils/reuseRouting.js";
 import { selectScopedPoms, } from "../../utils/pom-scope/index.js";
 import { verifyReuse } from "../../utils/pom-verify/index.js";
 import { infraGateFailure, zeroReuseGateFailure, composeVerifyText, } from "./verify-gates.js";
-import { recordCandidates, recordNoPomLayer, recordVerifyOutcome, recordUtilsReuseIssued, recordUtilsVerifyOutcome, recordUtilsVerifyError, pendingModularization, } from "./reuse-state.js";
+import { recordCandidates, recordNoPomLayer, recordVerifyOutcome, recordUtilsReuseIssued, recordUtilsVerifyOutcome, recordUtilsVerifyError, pendingModularization, utilsBaselineFor, } from "./reuse-state.js";
 import { formatUtilsVerifyText } from "./utils-verify-gates.js";
-import { stageUtilsArtifacts, utilsSpecFor, verifyUtils, } from "../../utils/utils-verify/index.js";
+import { utilsSpecFor, verifyUtils } from "../../utils/utils-verify/index.js";
 import { codeRefactoringSchema, languageSchema, TestType, } from "../../types/TestTypes.js";
 import { SKYRAMP_UTILS_HEADER } from "../../utils/utils.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
@@ -30,7 +31,7 @@ const codeReuseSchema = z.object({
     verify: z
         .boolean()
         .default(false)
-        .describe("Verify a previously refactored test instead of returning the reuse prompt. POM path (browser tests): checks the test's POM calls against source; requires the discovery pass — this tool called for the same testFile without `verify` — to have run first. SkyrampUtils path (every other test type): stages the shared utils file for the output commit and checks its invariants (API helpers: one helper per method+path, status-code-only assertions, method+resource names; browser helpers: actions and structural waits only, intent names). Call it after the reuse edits are written; skyramp_enhance_assertions and skyramp_execute_test refuse until it has passed."),
+        .describe("Verify a previously refactored test instead of returning the reuse prompt. POM path (browser tests): checks the test's POM calls against source; requires the discovery pass — this tool called for the same testFile without `verify` — to have run first. SkyrampUtils path (every other test type): stages the shared utils file for the output commit, checks its invariants, and — when skyramp_modularization recorded a baseline for this spec — compares the delivered assertion count and page.on('pageerror') guard against that hand-out, rejecting a net loss (API helpers: one helper per method+path, status-code-only assertions, method+resource names; browser helpers: actions and structural waits only, intent names). Call it after the reuse edits are written; skyramp_enhance_assertions and skyramp_execute_test refuse until it has passed."),
     testType: z
         .nativeEnum(TestType)
         .optional()
@@ -131,11 +132,12 @@ async function runUtilsVerify(params) {
         };
     }
     try {
-        const staging = await stageUtilsArtifacts(params.testFile, params.language);
+        const staging = await stageAndRecordRetrofits(params.testFile, params.language);
         const r = await verifyUtils({
             testFile: params.testFile,
             language: params.language,
             testType: params.testType,
+            baseline: await utilsBaselineFor(params.testFile),
         });
         // A utils file git refused to stage ships a test importing a module the output
         // commit lacks — the exact failure this gate exists for — so it fails the pass

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

@@ -1,9 +1,11 @@
 import { z } from "zod";
 import { pendingReuseDebt } from "./reuse-state.js";
-import { recordEnhanceObligation } from "./enhance-state.js";
-import { stageUtilsArtifacts } from "../../utils/utils-verify/index.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 * as path from "path";
 import { toolError } from "../../utils/utils.js";
-import { TestType } from "../../types/TestTypes.js";
+import { ASSERTION_ENHANCEABLE_TEST_TYPES, TestType, } from "../../types/TestTypes.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { getContractProviderAssertionsPrompt } from "../../prompts/enhance-assertions/contractProviderAssertionsPrompt.js";
 import { getIntegrationAssertionsPrompt } from "../../prompts/enhance-assertions/integrationAssertionsPrompt.js";
@@ -53,7 +55,7 @@ const enhanceAssertionsSchema = {
         .string()
         .describe("Absolute path to the generated or updated test file whose assertions must be enhanced. Pass the exact file you just created or modified."),
     testType: z
-        .enum([TestType.INTEGRATION, TestType.CONTRACT, TestType.UI])
+        .enum(ASSERTION_ENHANCEABLE_TEST_TYPES)
         .describe("The type of test whose assertions should be enhanced. Contract applies to provider contract tests only, not consumer contract tests."),
     enhanceType: z
         .enum(["generation", "maintenance"])
@@ -66,6 +68,18 @@ const enhanceAssertionsSchema = {
         .describe("When true, returns a compact instruction set (10 lines) that tells the agent to " +
         "read the test file, enhance assertions per standard rules, and write it back directly. " +
         "When false (default), returns the full verbose instruction set."),
+    verify: z
+        .boolean()
+        .default(false)
+        .describe("Set true AFTER applying the enhancement instructions to deterministically verify " +
+        "they were applied (assertions added or strengthened, rubric rules followed). " +
+        "Returns VERIFICATION PASSED or FAILED with per-violation remediations. " +
+        "Use the same testFile, testType, and enhanceType as the instruction call."),
+    stateFile: z
+        .string()
+        .optional()
+        .describe("Absolute path to the run state file, when one was provided by the workflow. " +
+        "Optional — in CI the run state is resolved automatically."),
 };
 export function registerEnhanceAssertionsTool(server) {
     server.registerTool(TOOL_NAME, {
@@ -73,36 +87,77 @@ export function registerEnhanceAssertionsTool(server) {
 
 ### When to call
 - After generating a new supported test file
-- After updating an existing supported test file during maintenance`,
+- After updating an existing supported test file during maintenance
+- Optionally with \`verify: true\` for early feedback — the same deterministic checks run automatically inside skyramp_execute_test, which returns per-violation feedback instead of executing until they pass.`,
         inputSchema: enhanceAssertionsSchema,
     }, async (params) => {
-        const { testFile, testType, enhanceType, autoApply } = params;
+        const { testFile, testType, enhanceType, autoApply, verify, stateFile } = params;
+        // Everything downstream keys state by this path; a relative spelling
+        // would fork records and fail gates open (review finding on SKYR-4262).
+        if (!path.isAbsolute(testFile)) {
+            return toolError(`testFile must be an absolute path, got: ${testFile}`);
+        }
         // 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.
-        //
-        // No stateFile is passed because this tool's schema has no such field, so outside
-        // CI — where nothing anchors the run state path — this checkpoint fails open. The
-        // execute_test backstop does take params.stateFile and covers that caller.
         // 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 stageUtilsArtifacts(testFile);
-        const owed = await pendingReuseDebt(testFile, undefined, testType, {
+        await stageAndRecordRetrofits(testFile);
+        const owed = await pendingReuseDebt(testFile, stateFile, testType, {
             chain: false,
         });
         if (owed)
             return toolError(owed);
         // Stage so testbot includes the generated files in its output commit.
         await stageGeneratedPaths(testFile);
-        // SKYR-4262: snapshot the spec at instruction-handout time. This tool only
-        // returns instructions — nothing here verifies the agent follows them — so
-        // skyramp_execute_test blocks later if the file is still byte-identical
-        // (instructions acknowledged, never acted on). Any edit clears the debt,
-        // including a documented `// assertions reviewed:` no-change decision.
-        await recordEnhanceObligation(testFile);
+        // Verify pass: deterministically check the hand-out instructions were applied
+        // (hash delta, no removed coverage, rubric lints, strength increase) and give
+        // per-violation feedback. isError on FAILED forces the fix-and-retry loop.
+        if (verify) {
+            try {
+                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);
+                AnalyticsService.pushMCPToolEvent(TOOL_NAME, undefined, {
+                    testFile,
+                    testType,
+                    enhanceType,
+                    verify: true,
+                    verifyPassed: result.ok,
+                }).catch(() => { });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: formatAssertionVerifyReport(result, testFile),
+                        },
+                    ],
+                    isError: !result.ok,
+                };
+            }
+            catch (err) {
+                // Not necessarily the test file — state reads can throw here too.
+                return toolError(`${TOOL_NAME} verification failed for ${testFile}: ${err.message}`);
+            }
+        }
+        // Hand-out: snapshot the file as generated so the verify pass has a baseline
+        // to measure against. Best-effort — no run state means stateless verify later.
+        await recordAssertionBaseline(testFile, testType, enhanceType, stateFile);
         if (autoApply) {
             const compactInstructions = [
                 `Enhance response body assertions in: \`${testFile}\``,

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

@@ -0,0 +1,53 @@
+import { type UnifiedAnalysisState } from "../../utils/AnalysisStateManager.js";
+import { type StagingResult } from "../../utils/utils-verify/index.js";
+/**
+ * Retrofit tracking (SKYR-4276 A4): a RETROFIT is a pre-existing Skyramp-generated
+ * test the reuse pass edited to import from the shared utils file (STEP 5c / the
+ * sibling-inline advisory). Staging carries the edit into the output commit, so the
+ * report must disclose it — with an execution that ran the edited bytes.
+ *
+ * Whether an execution counts is answered by TIME, not by a stored hash: the
+ * execution record already carries `executedAt`, and the file's mtime says when it
+ * was last edited — an execution older than the last edit ran bytes that no longer
+ * exist. That also covers a bare editor write with no tool call in between, which a
+ * record-time hash cannot see. (Same identity pattern as VideoRecord's
+ * status/executedAt.)
+ */
+/** Stage the utils artifacts for `testFile` and record any retrofits staging found.
+ *  The one call every checkpoint makes (reuse verify, enhance, execute). */
+export declare function stageAndRecordRetrofits(testFile: string, language?: string, explicitStateFile?: string): Promise<StagingResult>;
+/**
+ * Record the pre-existing generated tests the reuse pass edited (found by staging).
+ * Idempotent; a retrofit already recorded keeps its first attribution. Fails open
+ * like every other reuse-state write.
+ */
+export declare function recordReuseRetrofits(retrofits: string[], utilsFiles: string[], testFile: string, explicitStateFile?: string): Promise<void>;
+/** One retrofit as the report sees it. */
+export interface RetrofitView {
+    /** Absolute path. */
+    file: string;
+    utilsFile: string;
+    /** The spec whose reuse pass caused the edit (absolute). */
+    testFile: string;
+    /** Status of an execution that ran the CURRENT bytes (executedAt ≥ the file's
+     *  mtime), if any. */
+    execution?: import("../../types/TestExecution.js").TestExecutionStatus;
+}
+/**
+ * The retrofits that still stand in the working tree, with the execution that ran
+ * their current bytes. `changedFilesAbs` is ABSOLUTE paths across every checkout (see
+ * listChangedFilesAbs) — a retrofit the agent reverted is not among them and drops
+ * out. An execution older than the file's mtime ran bytes that no longer exist and
+ * does not count; an unreadable mtime fails open (the execution counts), matching
+ * the surrounding SKYR-3883 infrastructure-failure semantics.
+ */
+export declare function standingRetrofits(state: Pick<UnifiedAnalysisState, "reuseRetrofits" | "existingTests">, changedFilesAbs: string[]): Promise<RetrofitView[]>;
+/**
+ * The report gate over the standing retrofits: every one needs an execution of its
+ * current bytes, or the report is refused. Returns the views (for the report rows)
+ * and, when any are unexecuted, the refusal text.
+ */
+export declare function retrofitGate(state: Pick<UnifiedAnalysisState, "reuseRetrofits" | "existingTests">, changedFilesAbs: string[], repoRoot: string): Promise<{
+    views: RetrofitView[];
+    refusal?: string;
+}>;