@skyramp/mcp 0.3.4 → 0.3.6-rc.1

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

@@ -1,15 +1,21 @@
 import { z } from "zod";
+import * as path from "path";
 import { logger } from "../../utils/logger.js";
-import { getCodeReusePrompt, isPomAwareTarget } from "../../prompts/code-reuse.js";
-import { selectScopedPoms } from "../../utils/pom-scope/index.js";
+import { toolError } from "../../utils/utils.js";
+import { getCodeReusePrompt } from "../../prompts/code-reuse.js";
+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 } from "./reuse-state.js";
-import { codeRefactoringSchema, languageSchema, } from "../../types/TestTypes.js";
+import { infraGateFailure, zeroReuseGateFailure, composeVerifyText, } from "./verify-gates.js";
+import { recordCandidates, recordNoPomLayer, recordVerifyOutcome, recordUtilsReuseIssued, recordUtilsVerifyOutcome, recordUtilsVerifyError, pendingModularization, } from "./reuse-state.js";
+import { formatUtilsVerifyText } from "./utils-verify-gates.js";
+import { stageUtilsArtifacts, 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";
-import { isPomReuseEnabled } from "../../utils/featureFlags.js";
+import { isPomReuseEnabled, isUtilsReuseEnabled, } from "../../utils/featureFlags.js";
 import { stageGeneratedPaths } from "../../utils/gitStaging.js";
+import { currentRunStateFile } from "../../utils/AnalysisStateManager.js";
 const codeReuseSchema = z.object({
     testFile: z
         .string()
@@ -24,15 +30,255 @@ const codeReuseSchema = z.object({
     verify: z
         .boolean()
         .default(false)
-        .describe("Verify a previously written refactored test's POM calls against source instead of returning the reuse prompt"),
+        .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."),
+    testType: z
+        .nativeEnum(TestType)
+        .optional()
+        .describe("The type of the test being refactored (shared TestType vocabulary). The tool routes on it server-side: browser types (ui, e2e) may take the POM path; every other type takes the SkyrampUtils path. Omit when unknown."),
 });
 const TOOL_NAME = "skyramp_reuse_code";
+/**
+ * Specs whose discovery pass has run, keyed by `<run state file>:<resolved spec path>`.
+ *
+ * Deliberately in memory rather than in the run state file. The question it answers
+ * — has discovery run for this spec, in this run? — is intra-run and intra-process
+ * (one Testbot run is one MCP server process, the same assumption the run anchor in
+ * AnalysisStateManager rests on), and nothing outside this file reads it. Persisting
+ * it would put a precondition into a shared read-modify-write blob, where the reuse
+ * fan-out's concurrent verify calls can drop records.
+ *
+ * A server restart mid-run empties this, costing one extra discovery pass for a spec
+ * already refactored. That is self-correcting: the refusal IS the discovery pass.
+ */
+const discoveredSpecs = new Set();
+/** The key this spec is marked under, or undefined when there is no run to enforce
+ *  the precondition in — standalone/IDE calls have no run to have recorded a pass in.
+ *
+ *  The run's state file is part of the key rather than merely a gate, so one process
+ *  that ever serves two runs cannot carry run 1's marks into run 2. A stale mark would
+ *  stamp a spec that never received the procedure, which is the failure this guard
+ *  exists to close. */
+function markKeyFor(testFile) {
+    const stateFile = currentRunStateFile();
+    return stateFile === undefined
+        ? undefined
+        : `${stateFile}:${path.resolve(testFile)}`;
+}
+/** Prefixed to the discovery result when verify mode is called before it.
+ *
+ *  Leads with `VERIFICATION <STATE>` because every other verify-mode response does —
+ *  PASSED, FAILED, SKIPPED, ERROR — and the prompts tell the agent to read that line
+ *  ("finish only when it reports PASSED"). A fresh top-level keyword would be a state
+ *  it was never taught. NOT RUN rather than SKIPPED: SKIPPED already means "nothing to
+ *  verify, carry on", which is the opposite action to this one.
+ *
+ *  Worded to fit either branch that follows — the refactoring procedure, or the "no
+ *  reusable POM layer detected" abstention — and to leave the "verify when you are
+ *  done" instruction to that content, which already carries it in both branches. */
+const DISCOVER_FIRST_NOTICE = `VERIFICATION NOT RUN — this test file has not been through code-reuse discovery. That pass runs now, and its result follows below.
+
+Discovery is per test file: it scopes page-object candidates to this file's own selectors, so discovery done for another spec does not cover this one. Verification confirms only that the page-object calls a spec ALREADY contains resolve against their source — it cannot name the calls the spec should have made. That is why verifying first reports a spec that reuses almost nothing as PASSED.
+
+Follow the result below for this test file; it states what to do next.`;
 // Only advertised when SKYRAMP_FEATURE_POM_REUSE=1 — with the flag off this tool
 // never takes the POM path, so describing it would promise behavior it won't do.
 const POM_AWARE_MODE_DESCRIPTION = `
 
       **POM-AWARE MODE (TypeScript/JavaScript + Playwright):**
       For projects with \`language: "typescript" or "javascript"\` and \`framework: "playwright"\`, this tool first checks whether the project has an existing Page Object Model (POM) library (\`pageobjects/\` directories or \`*.page.ts\` / \`*.page.js\` files). If POMs are found, the test is refactored to use those POM classes and methods — replacing raw inline locators with the existing abstractions. SkyrampUtils consolidation is skipped on this path. If no POMs are found, the tool falls back to the standard SkyrampUtils path. New POM creation is out of scope — existing POMs are reused only. After POM-aware code reuse, do NOT call skyramp_modularization — on this path that supersedes WORKFLOW SUMMARY step 6.`;
+/** Whether a `verify: true` call must be turned into the discovery pass it skipped.
+ *
+ *  The two modes return very different things — discovery returns the whole refactoring
+ *  procedure, `verify: true` a one-line stamp — and nothing ordered them, so a spec could
+ *  be stamped having never received the procedure (measured: 2 of 3 specs in one run). The
+ *  rule existed as prompt prose and was skipped anyway; it is a precondition here instead.
+ *
+ *  `isPomAwareTarget` also carries the feature flag and the browser-test-type check, so a
+ *  call that could never have reached the POM procedure is never refused for lacking it.
+ *  Enforced only inside a run — see `markKeyFor`. */
+function mustDiscoverFirst(params, markKey) {
+    return (markKey !== undefined &&
+        isPomAwareTarget(params.language, params.framework, params.testType) &&
+        !discoveredSpecs.has(markKey));
+}
+/** Verify mode for the SkyrampUtils path: stage the shared utils file(s) this spec
+ *  wrote or imports — located by header, in code, after the edits exist — then check
+ *  their invariants and record the verdict that clears the utils debt.
+ *
+ *  Staging comes FIRST and is unconditional: a utils file that fails verification is
+ *  still the file the test imports, and an unstaged one ships a test that cannot run
+ *  at all (SKYR-4196 Part B run 2). */
+async function runUtilsVerify(params) {
+    if (!isUtilsReuseEnabled()) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "VERIFICATION SKIPPED — SkyrampUtils code reuse is disabled (SKYRAMP_FEATURE_UTILS_REUSE). Nothing to verify; continue.",
+                },
+            ],
+        };
+    }
+    if (!utilsSpecFor(params.language)) {
+        // Say so rather than record a NoUtilsFile verdict nothing established.
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `VERIFICATION SKIPPED — shared-helper verification does not cover ${params.language}; nothing was staged or checked. Continue.`,
+                },
+            ],
+        };
+    }
+    try {
+        const staging = await stageUtilsArtifacts(params.testFile, params.language);
+        const r = await verifyUtils({
+            testFile: params.testFile,
+            language: params.language,
+            testType: params.testType,
+        });
+        // 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
+        // whatever the file's invariants say.
+        if (staging.failed.length > 0)
+            r.ok = false;
+        const recorded = await recordUtilsVerifyOutcome(params.testFile, r, params.language, params.framework, params.testType);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatUtilsVerifyText(r, {
+                        staged: staging.staged,
+                        unstaged: staging.failed,
+                        recorded,
+                    }),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        logger.warning("SkyrampUtils verification threw — recording a verify error so the debt fails open", {
+            testFile: params.testFile,
+            error: String(err),
+        });
+        await recordUtilsVerifyError(params.testFile);
+        return toolError(`VERIFICATION ERROR — the shared-helper verifier could not run: ${String(err)}. This is not something to retry blindly; ` +
+            `it does not block skyramp_enhance_assertions or skyramp_execute_test. If the cause is in your files (unreadable utils file), fix it and verify once more.`);
+    }
+}
+/** Verify mode: check the page-object calls the delivered spec already contains. */
+async function runVerify(params) {
+    // Route on the same predicate the prompt path routes on. A target the POM path
+    // never took must not reach the POM verifier — it is the sole writer of the POM
+    // reuse summary, and a POM-less run would otherwise emit POM numbers — so every
+    // non-POM target, including browser tests with the POM flag off, takes the
+    // SkyrampUtils verifier, which is what the prompt path handed it.
+    if (!isPomAwareTarget(params.language, params.framework, params.testType)) {
+        return runUtilsVerify(params);
+    }
+    try {
+        const r = await verifyReuse(params.testFile, params.language);
+        const gate = (await infraGateFailure(params, r)) ??
+            (await zeroReuseGateFailure(params, r));
+        // Record what this pass established before returning the text report:
+        // every number in it is already in hand here, so the agent is never
+        // asked to read one back out and retype it later.
+        await recordVerifyOutcome(params.testFile, r, gate !== undefined, params.language);
+        return {
+            content: [{ type: "text", text: composeVerifyText(gate, r) }],
+        };
+    }
+    catch (err) {
+        logger.warning("POM verification threw", {
+            testFile: params.testFile,
+            error: String(err),
+        });
+        return toolError(`VERIFICATION ERROR (treat as unverified, do not retry more than once): ${String(err)}`);
+    }
+}
+/** Discovery mode: the POM-aware refactoring procedure, scoped to this one spec.
+ *
+ *  Both the ordinary discovery call and the refused-verify path go through here, so the
+ *  workflow a refused verify receives cannot drift from the one a first call receives. */
+async function runDiscovery(params, markKey) {
+    logger.info("Analyzing code for reuse opportunities", {
+        testFile: params.testFile,
+        language: params.language,
+        framework: params.framework,
+    });
+    // Stage so testbot includes the generated files in its output commit.
+    await stageGeneratedPaths(params.testFile);
+    // Deterministic POM pre-scoping (TS/JS+Playwright browser tests only).
+    // Never blocks: any error or empty result falls back to the agent-driven STEP 1.
+    let scopedPoms;
+    const pomAware = isPomAwareTarget(params.language, params.framework, params.testType);
+    // The SkyrampUtils path records its debt here, where the instructions are issued:
+    // from this point the tools that follow reuse on this spec refuse until a
+    // `verify: true` pass has staged and checked the utils file (SKYR-4220).
+    // Only for languages the verifier covers: a debt the verify pass cannot pay (Java —
+    // utils reuse is disabled for it, and there is no analyzer) would clear as
+    // "no shared utils file" without anything being staged or checked.
+    // Gated by the same flag that gates the rest of SkyrampUtils reuse: with it off the
+    // testbot prompt never asks for reuse and tells the agent a no-op is normal, so a debt
+    // recorded here would block enhance/execute on today's default configuration.
+    if (!pomAware && isUtilsReuseEnabled() && utilsSpecFor(params.language)) {
+        await recordUtilsReuseIssued(params.testFile, params.language, params.framework, params.testType);
+    }
+    if (pomAware) {
+        try {
+            const t0 = Date.now();
+            const { tier1, tier2, diagnostics } = await selectScopedPoms({
+                testFile: params.testFile,
+                specContent: params.prompt,
+            });
+            if (tier1.length + tier2.length > 0) {
+                scopedPoms = { tier1, tier2 };
+                // Only report candidates found through the conventional POM globs.
+                //
+                // The selector-grep fallback also matches ordinary in-repo frontend
+                // source — app components legitimately contain the spec's test-ids by
+                // construction — so in a repo with no page-object layer at all it still
+                // yields "candidates". Reporting those would render, on a POM-less repo,
+                // "4 candidate POM files detected" next to zero reuse: each number true
+                // in isolation, but together they assert reusable page objects existed
+                // and were ignored. `zeroReuseGateFailure` already draws this exact line
+                // for the same reason; the report has to draw it too.
+                //
+                // The agent is still handed the grep-discovered files to consider —
+                // only the customer-facing count is withheld.
+                if (diagnostics.discovery === "globs") {
+                    await recordCandidates(params.testFile, tier1.length, params.language);
+                }
+            }
+            else if (diagnostics.selectors > 0 &&
+                diagnostics.discovery !== "skipped-too-large") {
+                // A clean scan ran (glob or selector-grep) and found zero overlap — distinct from
+                // "scoping wasn't attempted" (no selectors) or "scan was skipped" (repo too large).
+                scopedPoms = { tier1: [], tier2: [], scannedNoOverlap: true };
+                await recordNoPomLayer(params.testFile);
+            }
+            logger.info("POM pre-scoping", {
+                ...diagnostics,
+                tier1: tier1.length,
+                tier2: tier2.length,
+                ms: Date.now() - t0,
+            });
+        }
+        catch (err) {
+            logger.warning("POM pre-scoping failed — falling back to agent-driven detection", { error: String(err) });
+        }
+    }
+    const codeReusePrompt = getCodeReusePrompt(params.testFile, params.language, params.framework, scopedPoms, params.testType);
+    // Marked on the last line before the return, so the mark cannot be observed until the
+    // workflow it stands for has been built. An earlier mark let a verify arriving mid-scope
+    // check a spec that had not been handed the procedure yet.
+    //
+    // Every scoping outcome reaches this line — hit, empty, or thrown — because a discovery
+    // pass that could not clear the precondition would be refused forever.
+    if (pomAware && markKey !== undefined)
+        discoveredSpecs.add(markKey);
+    return codeReusePrompt;
+}
 export function registerCodeReuseTool(server) {
     server.registerTool(TOOL_NAME, {
         description: `Analyzes code for reuse opportunities and enforces code reuse principles.
@@ -42,29 +288,28 @@ export function registerCodeReuseTool(server) {
       **CRITICAL RULES - VIOLATION WILL RESULT IN ERROR:**
       1. THIS TOOL MUST BE CALLED IF DURING THE TEST GENERATION THE CODE REUSE FLAG IS SET TO TRUE EXPLICITLY
       2. DO NOT create new helper functions - only find and reuse existing ones
-      3. ONLY create a utils file if ACTUAL helper functions (with signatures) exist in OTHER test files
+      3. ONLY create a utils file when the returned steps say so: either ACTUAL helper functions (with signatures) exist in OTHER test files, or the returned steps include a seeding step that moves the CURRENT test's own helpers (created by skyramp_modularization) into the utils file
       4. DO NOT create utils files for repetitive patterns - that's refactoring, not reuse
       5. DO NOT extract patterns from current or other test files - only move existing functions
-      6. If other test files are identical/similar with no helper functions, DO NOTHING
+      6. If other test files are identical/similar with no helper functions, DO NOTHING with them — unless the returned steps include a seeding step, in which case the CURRENT test's own helpers are still moved
       7. Helper functions must have explicit function definitions, not just patterns
-      8. If no existing helper functions found, test file remains unchanged
+      8. If no existing helper functions are found AND the returned steps have no seeding step, the test file remains unchanged; with a seeding step, the current test's helpers move to the utils file and are imported back
 
 
       **WORKFLOW SUMMARY:**
       1. Check existing utils with header ${SKYRAMP_UTILS_HEADER} → reuse if found WITHOUT ANY OTHER CHANGES
       2. Search OTHER test files (not current test file) for local helpers with header ${SKYRAMP_UTILS_HEADER}
       3. **ONLY IF** reusable helpers are found in OTHER test files → move to utils and update imports
-      4. **IF NO** existing utils or reusable helpers are found in test files then reuse is complete, without creating any files or changes to the test files
+      4. **IF NO** existing utils or reusable helpers are found in test files then reuse is complete, without creating any files or changes to the test files — unless the returned steps include a seeding step for the current test's own helpers
       5. Verify no duplicate code remains and tests work as expected
-      6. **MANDATORY**: After code reuse is complete, proceed to modularization by calling skyramp_modularization tool ONLY for UI, E2E, INTEGRATION or LOAD tests generated from traces.
+      6. The returned steps include a MANDATORY line about skyramp_modularization for this test file — follow it (it states whether modularization follows this pass or must not be run again).
 
-      **WHEN TO SKIP (DO NOTHING):**
+      **WHEN TO SKIP (DO NOTHING) — applies to sibling-file reuse; a seeding step in the returned workflow still runs:**
       - Other test files only have repetitive patterns, no helper functions
       - Other test files are essentially identical to current file
       - No actual function definitions found in other test files
 
-      **MANDATORY**: ONLY ALLOW CODE REUSE IF THE IS TRACE BASED FLAG IS SET TO TRUE ELSE DO NOT ALLOW CODE REUSE AND LEAVE THE TEST FILE AS IS.
-      **CRITICAL**: NON TRACE BASED TESTS ARE ALREADY MODULARIZED AND DO NOT NEED CODE REUSE.
+      Applicability is decided by the caller: when a generation result was produced with \`codeReuse: true\`, it directs you here — ALWAYS follow through (a no-op result is a normal outcome, never a failure). Multi-step tests (UI, E2E, INTEGRATION, LOAD) are the ones that benefit; simple single-request tests (smoke, contract, fuzz) do not request code reuse.
       The tool will provide step-by-step instructions that MUST be followed exactly.${isPomReuseEnabled() ? POM_AWARE_MODE_DESCRIPTION : ""}`,
         inputSchema: codeReuseSchema.shape,
         _meta: {
@@ -80,98 +325,37 @@ export function registerCodeReuseTool(server) {
         let errorResult;
         try {
             if (params.verify) {
-                // The verify pass is POM-only, and it is the sole writer of the report's
-                // reuse summary — so with the flag off a stale instruction to verify must
-                // not run it, or a POM-less run would still emit POM reuse numbers.
-                if (!isPomReuseEnabled()) {
+                const markKey = markKeyFor(params.testFile);
+                if (mustDiscoverFirst(params, markKey)) {
+                    logger.info("Verify called before the discovery pass — returning the discovery workflow", { testFile: params.testFile });
+                    const workflow = await runDiscovery(params, markKey);
                     return {
                         content: [
                             {
                                 type: "text",
-                                text: "VERIFICATION SKIPPED — POM-aware code reuse is disabled. Nothing to verify; continue.",
-                            },
-                        ],
-                    };
-                }
-                try {
-                    const r = await verifyReuse(params.testFile, params.language);
-                    const gate = (await infraGateFailure(params, r)) ?? (await zeroReuseGateFailure(params, r));
-                    // Record what this pass established before returning the text report:
-                    // every number in it is already in hand here, so the agent is never
-                    // asked to read one back out and retype it later.
-                    await recordVerifyOutcome(params.testFile, r, gate !== undefined, params.language);
-                    return { content: [{ type: "text", text: composeVerifyText(gate, r) }] };
-                }
-                catch (err) {
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: `VERIFICATION ERROR (treat as unverified, do not retry more than once): ${String(err)}`,
+                                text: `${DISCOVER_FIRST_NOTICE}\n\n---\n\n${workflow}`,
                             },
                         ],
                     };
                 }
+                return await runVerify(params);
             }
-            logger.info("Analyzing code for reuse opportunities", {
-                testFile: params.testFile,
-                language: params.language,
-                framework: params.framework,
-            });
-            // Stage so testbot includes the generated files in its output commit.
-            await stageGeneratedPaths(params.testFile);
-            // Deterministic POM pre-scoping (TS/JS+Playwright only). Never blocks:
-            // any error or empty result falls back to the agent-driven STEP 1.
-            let scopedPoms;
-            if (isPomAwareTarget(params.language, params.framework)) {
-                try {
-                    const t0 = Date.now();
-                    const { tier1, tier2, diagnostics } = await selectScopedPoms({
-                        testFile: params.testFile,
-                        specContent: params.prompt,
-                    });
-                    if (tier1.length + tier2.length > 0) {
-                        scopedPoms = { tier1, tier2 };
-                        // Only report candidates found through the conventional POM globs.
-                        //
-                        // The selector-grep fallback also matches ordinary in-repo frontend
-                        // source — app components legitimately contain the spec's test-ids by
-                        // construction — so in a repo with no page-object layer at all it still
-                        // yields "candidates". Reporting those would render, on a POM-less repo,
-                        // "4 candidate POM files detected" next to zero reuse: each number true
-                        // in isolation, but together they assert reusable page objects existed
-                        // and were ignored. `zeroReuseGateFailure` already draws this exact line
-                        // for the same reason; the report has to draw it too.
-                        //
-                        // The agent is still handed the grep-discovered files to consider —
-                        // only the customer-facing count is withheld.
-                        if (diagnostics.discovery === "globs") {
-                            await recordCandidates(params.testFile, tier1.length);
-                        }
-                    }
-                    else if (diagnostics.selectors > 0 && diagnostics.discovery !== "skipped-too-large") {
-                        // A clean scan ran (glob or selector-grep) and found zero overlap — distinct from
-                        // "scoping wasn't attempted" (no selectors) or "scan was skipped" (repo too large).
-                        scopedPoms = { tier1: [], tier2: [], scannedNoOverlap: true };
-                        await recordNoPomLayer(params.testFile);
-                    }
-                    logger.info("POM pre-scoping", {
-                        ...diagnostics,
-                        tier1: tier1.length,
-                        tier2: tier2.length,
-                        ms: Date.now() - t0,
-                    });
-                }
-                catch (err) {
-                    logger.warning("POM pre-scoping failed — falling back to agent-driven detection", { error: String(err) });
+            // Modularize-first targets owe skyramp_modularization before reuse is issued —
+            // the other half of the pair the hand-off names. Only ever owed for a file
+            // generation handed off, so NL callers and POM targets are untouched.
+            if (isUtilsReuseEnabled() &&
+                !isPomAwareTarget(params.language, params.framework, params.testType)) {
+                const owed = await pendingModularization(params.testFile);
+                if (owed) {
+                    errorResult = toolError(owed);
+                    return errorResult;
                 }
             }
-            const codeReusePrompt = getCodeReusePrompt(params.testFile, params.language, params.framework, scopedPoms);
             return {
                 content: [
                     {
                         type: "text",
-                        text: codeReusePrompt,
+                        text: await runDiscovery(params, markKeyFor(params.testFile)),
                     },
                 ],
             };
@@ -195,7 +379,9 @@ export function registerCodeReuseTool(server) {
                 testFile: params.testFile,
                 language: params.language,
                 framework: params.framework,
-            }).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            }).catch((err) => {
+                logger.warning("Analytics event failed", { error: String(err) });
+            });
         }
     });
 }

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

@@ -0,0 +1,49 @@
+/**
+ * SKYR-4262 — enforcement for the assertion-enhancement step.
+ *
+ * `skyramp_enhance_assertions` is prompt-returning: it hands the agent
+ * instructions and relies on it to Read + Edit the spec. Nothing verified that
+ * the file actually changed, and one production run showed an agent calling the
+ * tool for 9 generated specs back-to-back, declaring the assertions adequate
+ * without reading a single file, and shipping specs whose named behavior
+ * (disabled-state checks) was asserted nowhere.
+ *
+ * Same enforcement shape as SKYR-4115's pendingReuseVerification: record an
+ * obligation when the instructions are handed out, check it at the next tool
+ * that touches the same spec, fail open on any state error, and make the
+ * clearing action one the agent can always perform:
+ *   - edit the spec (any content change clears the debt), or
+ *   - document a deliberate no-change decision with a
+ *     `// assertions reviewed:` comment in the spec — which is itself an edit,
+ *     so the hash check is the only gate and the marker is the documentation.
+ */
+/** Snapshot of a spec at the moment enhancement instructions were handed out. */
+export interface EnhanceRecord {
+    /** Absolute path, for basename-collision detection in multi-repo runs. */
+    testFilePath?: string;
+    /** sha256 of the file content at handout time. */
+    sha256?: string;
+    /** Number of `expect(` occurrences at handout time — for the block message. */
+    expectCount?: number;
+}
+/**
+ * Record that enhancement instructions were handed out for `testFile`.
+ * Best-effort: a missing run state (non-Testbot use) or unreadable file
+ * degrades to "no enforcement", never to a failed tool call.
+ */
+export declare function recordEnhanceObligation(testFile: string, explicitStateFile?: string): Promise<void>;
+/**
+ * Was this spec handed assertion-enhancement instructions it never acted on?
+ *
+ * Returns an actionable message when the file is byte-identical to its state at
+ * handout time, `undefined` otherwise. The debt clears through the file itself:
+ * any edit — adding the missing assertions, or documenting a deliberate
+ * no-change decision with a `// assertions reviewed: <reason>` comment —
+ * changes the hash. Enforcing "the file changed" rather than "the assertions
+ * are good" keeps this a checkpoint, not a judge: assertion quality stays where
+ * it belongs, in the enhancement instructions and the report.
+ *
+ * Fails open on every error path: an unreadable state file or spec is not
+ * evidence the agent skipped anything.
+ */
+export declare function pendingAssertionEnhancement(testFile: string, explicitStateFile?: string): Promise<string | undefined>;

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

@@ -0,0 +1,109 @@
+import * as path from "path";
+import { createHash } from "crypto";
+import { readFile } from "fs/promises";
+import { logger } from "../../utils/logger.js";
+import { resolveRunStatePath, StateManager, } from "../../utils/AnalysisStateManager.js";
+const REVIEW_MARKER = "// assertions reviewed:";
+async function fileSnapshot(testFile) {
+    try {
+        const content = await readFile(testFile, "utf8");
+        return {
+            content,
+            sha256: createHash("sha256").update(content).digest("hex"),
+            expectCount: (content.match(/\bexpect\s*\(/g) ?? []).length,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Record that enhancement instructions were handed out for `testFile`.
+ * Best-effort: a missing run state (non-Testbot use) or unreadable file
+ * degrades to "no enforcement", never to a failed tool call.
+ */
+export async function recordEnhanceObligation(testFile, explicitStateFile) {
+    const stateFile = resolveRunStatePath(explicitStateFile);
+    if (!stateFile)
+        return;
+    const snapshot = await fileSnapshot(testFile);
+    if (!snapshot)
+        return;
+    try {
+        const manager = StateManager.fromStatePath(stateFile);
+        const data = await manager.readData();
+        if (!data)
+            return;
+        const key = path.basename(testFile);
+        await manager.writeData({
+            ...data,
+            enhanceOutcomes: {
+                ...data.enhanceOutcomes,
+                [key]: {
+                    testFilePath: testFile,
+                    sha256: snapshot.sha256,
+                    expectCount: snapshot.expectCount,
+                },
+            },
+        });
+    }
+    catch (err) {
+        logger.warning("Could not record the assertion-enhancement obligation — proceeding", {
+            testFile,
+            error: String(err),
+        });
+    }
+}
+/**
+ * Was this spec handed assertion-enhancement instructions it never acted on?
+ *
+ * Returns an actionable message when the file is byte-identical to its state at
+ * handout time, `undefined` otherwise. The debt clears through the file itself:
+ * any edit — adding the missing assertions, or documenting a deliberate
+ * no-change decision with a `// assertions reviewed: <reason>` comment —
+ * changes the hash. Enforcing "the file changed" rather than "the assertions
+ * are good" keeps this a checkpoint, not a judge: assertion quality stays where
+ * it belongs, in the enhancement instructions and the report.
+ *
+ * Fails open on every error path: an unreadable state file or spec is not
+ * evidence the agent skipped anything.
+ */
+export async function pendingAssertionEnhancement(testFile, explicitStateFile) {
+    try {
+        const stateFile = resolveRunStatePath(explicitStateFile);
+        if (!stateFile)
+            return undefined;
+        const data = await StateManager.fromStatePath(stateFile).readData();
+        const record = data?.enhanceOutcomes?.[path.basename(testFile)];
+        if (!record?.sha256)
+            return undefined;
+        // enhanceOutcomes is keyed by basename across the whole run; in a multi-repo
+        // run two specs can share one record. Blocking a tool on another spec's debt
+        // is worse than missing this one, so a mismatch fails open.
+        if (record.testFilePath && record.testFilePath !== testFile)
+            return undefined;
+        const snapshot = await fileSnapshot(testFile);
+        if (!snapshot)
+            return undefined;
+        if (snapshot.sha256 !== record.sha256)
+            return undefined;
+        if (snapshot.content.includes(REVIEW_MARKER))
+            return undefined;
+        const spec = path.basename(testFile);
+        const countNote = record.expectCount !== undefined
+            ? ` It still has the same ${record.expectCount} expect() call${record.expectCount === 1 ? "" : "s"} it was generated with.`
+            : "";
+        return (`skyramp_enhance_assertions handed out instructions for ${spec} and the file has not changed since.${countNote} ` +
+            `Read the file and apply the enhancement instructions — in particular, add expect() assertions for the specific ` +
+            `behavior this test is named for (state checks like toBeDisabled/toBeEnabled/toHaveCount, not just replayed text ` +
+            `assertions). If after actually reading the file you determine no change is needed, document that in the spec with ` +
+            `a \`${REVIEW_MARKER} <what you checked and why it is sufficient>\` comment near the top of the test.`);
+    }
+    catch (err) {
+        logger.warning("Could not check for a pending assertion enhancement — proceeding", {
+            testFile,
+            error: String(err),
+        });
+        return undefined;
+    }
+}