@skyramp/mcp 0.3.6 → 0.3.7

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

@@ -0,0 +1,162 @@
+import * as path from "path";
+import { readFile, stat } from "fs/promises";
+import { logger } from "../../utils/logger.js";
+import { resolveRunStatePath, StateManager, } from "../../utils/AnalysisStateManager.js";
+import { stageUtilsArtifacts, } from "../../utils/utils-verify/index.js";
+import { importFormViolations, locateUtilsFiles, retrofitMismatches, utilsSpecForFile, } from "../../utils/utils-verify/index.js";
+import { realpath } from "../../utils/utils-verify/index.js";
+import { canonPath, samePath, utilsFileLabel } from "./reuse-state.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 async function stageAndRecordRetrofits(testFile, language, explicitStateFile) {
+    const staging = await stageUtilsArtifacts(testFile, language);
+    await recordReuseRetrofits(staging.retrofits, staging.utilsFiles, testFile, explicitStateFile);
+    return staging;
+}
+/**
+ * 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 async function recordReuseRetrofits(retrofits, utilsFiles, testFile, explicitStateFile) {
+    if (retrofits.length === 0)
+        return;
+    const stateFile = resolveRunStatePath(explicitStateFile);
+    if (!stateFile)
+        return;
+    try {
+        const manager = StateManager.fromStatePath(stateFile);
+        const data = await manager.readData();
+        if (!data)
+            return;
+        const utilsFile = utilsFileLabel(utilsFiles);
+        const entries = { ...data.reuseRetrofits };
+        for (const f of retrofits) {
+            const key = await realpath(f);
+            if (!entries[key])
+                entries[key] = { utilsFile, testFile: await realpath(testFile) };
+        }
+        await manager.writeData({ ...data, reuseRetrofits: entries });
+    }
+    catch (err) {
+        logger.warning("Could not record the reuse retrofits — the report will not be checked for them", { retrofits, error: String(err) });
+    }
+}
+/**
+ * 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 async function standingRetrofits(state, changedFilesAbs) {
+    const changed = new Set(changedFilesAbs.map((f) => canonPath(f)));
+    const out = [];
+    for (const [file, r] of Object.entries(state.reuseRetrofits ?? {})) {
+        if (!changed.has(canonPath(file)))
+            continue;
+        const recorded = state.existingTests?.find((t) => samePath(t.testFile, file))?.executionAfter;
+        let execution = recorded?.status;
+        if (recorded) {
+            try {
+                const mtime = (await stat(file)).mtimeMs;
+                if (Date.parse(recorded.executedAt) < mtime)
+                    execution = undefined;
+            }
+            catch {
+                /* fail open: an unreadable mtime must not demand a re-run */
+            }
+        }
+        out.push({ file, utilsFile: r.utilsFile, testFile: r.testFile, execution });
+    }
+    return out;
+}
+/**
+ * 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 async function retrofitGate(state, changedFilesAbs, repoRoot) {
+    const views = await standingRetrofits(state, changedFilesAbs);
+    // A retrofit that changed the request is refused whether or not it ran: an
+    // execution proves the edited file was exercised, not that it still exercises the
+    // same thing. Checked here rather than where the edit happens because the agent
+    // performs the substitution itself (STEP 5c) — this is the deterministic check
+    // over what it actually did.
+    const checked = (await Promise.all(views.map(async (v) => {
+        const spec = utilsSpecForFile(v.file);
+        if (!spec)
+            return { mismatches: [], imports: [] };
+        try {
+            // The rewired file's own imports resolve the utils file(s) it now uses —
+            // RetrofitView carries only a basename label for the report row.
+            const utilsFiles = await locateUtilsFiles({
+                testFile: v.file,
+                language: spec.language,
+                // The root the report is written against — without it every retrofit
+                // re-detects the git root.
+                cwd: repoRoot,
+            });
+            if (utilsFiles.length === 0)
+                return { mismatches: [], imports: [] };
+            // STEP 5c adds an import to the SIBLING, and siblings share the spec's
+            // directory — so if that directory is a package, the sibling's new import
+            // needs the same fallback pair the spec's does. verifyUtils only ever sees
+            // the spec, so without this the gate covered one of the two files it should.
+            const imports = spec.language === "python"
+                ? importFormViolations(v.file, await readFile(v.file, "utf8"), utilsFiles)
+                : [];
+            return {
+                mismatches: await retrofitMismatches(v.file, utilsFiles, spec),
+                imports,
+            };
+        }
+        catch {
+            return { mismatches: [], imports: [] }; // never fail a report on the check
+        }
+    }))).flat();
+    const mismatches = checked.flatMap((c) => c.mismatches);
+    const badImports = checked.flatMap((c) => c.imports);
+    if (badImports.length > 0) {
+        const refusal = `${badImports.length} pre-existing generated test(s) were rewired onto the shared helper with an import that will NOT resolve when the customer runs pytest — the file dies at collection.\n` +
+            badImports
+                .map((v) => `  - ${path.relative(repoRoot, v.file)}:${v.line} · ${v.detail}`)
+                .join("\n");
+        return { views, refusal };
+    }
+    if (mismatches.length > 0) {
+        const refusal = `${mismatches.length} pre-existing generated test(s) were rewired onto a shared helper that does NOT send the same request they sent before — ` +
+            `the edit changed what the customer's test exercises, which this flow must never do.\n` +
+            `For each one: either restore that file's own request block, or extend the helper with a parameter DEFAULTED to the value the helper already uses, so every existing call site keeps its behaviour and this file passes its own values.\n` +
+            mismatches
+                .map((m) => `  - ${path.relative(repoRoot, m.file)} · ${m.method} ${m.path} → ${m.helper}: ${m.detail}`)
+                .join("\n");
+        return { views, refusal };
+    }
+    const unexecuted = views.filter((v) => !v.execution);
+    if (unexecuted.length === 0)
+        return { views };
+    const refusal = `${unexecuted.length} pre-existing generated test(s) were edited by the code-reuse pass to import from a shared utils file, but have no recorded execution of the edited file — ` +
+        `Testbot will not report a rewired test it has not run.\n` +
+        `Run each file below with skyramp_execute_test (it is a pre-existing test, so pass its path and phase "after"); that records the execution and clears this.\n` +
+        `Do NOT remove imports from any test, inline helpers back, or restore files from HEAD to satisfy this check — un-sharing the helpers is the tamper path, not the fix.\n` +
+        `Only if the edit was unintended, restore that ONE file from HEAD and re-verify the tests that import the utils file:\n` +
+        unexecuted
+            .map((v) => `  - ${path.relative(repoRoot, v.file)} (now imports from ${v.utilsFile})`)
+            .join("\n");
+    return { views, refusal };
+}

package/build/tools/code-refactor/reuse-outcome.d.ts

@@ -60,6 +60,13 @@ export interface ReuseRecord {
      *  enforceable unit, as with every other debt here). Read by the reuse tool on a
      *  hand-off target: modularize-first flows owe modularization BEFORE reuse. */
     modularized?: true;
+    /** The spec as it stood when `skyramp_modularization` handed out its instructions —
+     *  after the enhancer, before any code moved (SKYR-4276 A7/A8). The verify pass
+     *  compares the delivered spec plus the helpers it imports against this. */
+    baseline?: {
+        assertions: number;
+        pageErrorGuard: boolean;
+    };
 }
 export interface UtilsReuseRecord {
     /** True once the utils path handed out reuse instructions; a bare verify without a

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

@@ -76,12 +76,21 @@ export declare function recordUtilsReuseIssued(testFile: string, language: strin
 /** A verify pass that threw. Recorded so the debt FAILS OPEN — a verifier that cannot
  *  run must not leave a debt nothing can pay — and cleared by the next successful pass. */
 export declare function recordUtilsVerifyError(testFile: string, explicitStateFile?: string): Promise<void>;
+/** Canonical comparison: a record written through a symlinked path (macOS /var →
+ *  /private/var) must still be recognised as this spec's when checked by realpath. */
+export declare function samePath(a: string, b: string): boolean;
+/** Exported for retrofit-state: the same canonicalisation the records use. */
+export declare function canonPath(p: string): string;
+/** The basename label a report row shows for a set of utils files. */
+export declare function utilsFileLabel(files: string[]): string;
 /** Verdict of one utils verify pass. The verdict alone is stored — counts and the
  *  file list are re-derived from the delivered files at report time. */
 export declare function recordUtilsVerifyOutcome(testFile: string, r: UtilsVerifyResult, language: string, framework: string, testType: string | undefined, explicitStateFile?: string): Promise<boolean>;
 /** `skyramp_modularization` was called for this spec. Ownership on the write, like
  *  the utils debt: a same-basename spec elsewhere does not inherit the mark. */
 export declare function recordModularized(testFile: string, explicitStateFile?: string): Promise<void>;
+/** The modularization-hand-out baseline for this spec, if one was recorded for it. */
+export declare function utilsBaselineFor(testFile: string, explicitStateFile?: string): Promise<ReuseRecord["baseline"] | undefined>;
 /**
  * Does this spec owe `skyramp_modularization` before reuse may be issued? Only a spec
  * generation handed off (modularize-first flows: the hand-off names both calls, in

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

@@ -1,3 +1,4 @@
+import * as fsp from "fs/promises";
 import * as path from "path";
 import { readFile, stat, access, constants as fsConstants } from "fs/promises";
 import { realpathSync } from "fs";
@@ -7,7 +8,7 @@ import { logger } from "../../utils/logger.js";
 import { resolveRunStatePath, StateManager, } from "../../utils/AnalysisStateManager.js";
 import { verifyReuse, } from "../../utils/pom-verify/index.js";
 import { buildSkipped, findUnparsableKeptInline, flaggedFrom, mergeFlagged, verificationFrom, ReuseVerificationOutcome, HelperVerificationOutcome, } from "./reuse-outcome.js";
-import { verifyUtils, realpath, utilsSpecFor, } from "../../utils/utils-verify/index.js";
+import { verifyUtils, realpath, utilsSpecFor, countAssertions, hasPageErrorGuard, utilsSpecForFile, } from "../../utils/utils-verify/index.js";
 import { detectGitRoot } from "../../utils/gitStaging.js";
 const execFileAsync = promisify(execFile);
 import { resolvePomCatalogPath } from "../../utils/pom-catalog.js";
@@ -238,9 +239,17 @@ function owns(record, testFile) {
 }
 /** Canonical comparison: a record written through a symlinked path (macOS /var →
  *  /private/var) must still be recognised as this spec's when checked by realpath. */
-function samePath(a, b) {
+export function samePath(a, b) {
     return canon(a) === canon(b);
 }
+/** Exported for retrofit-state: the same canonicalisation the records use. */
+export function canonPath(p) {
+    return canon(p);
+}
+/** The basename label a report row shows for a set of utils files. */
+export function utilsFileLabel(files) {
+    return files.map((f) => path.basename(f)).join(", ");
+}
 function canon(p) {
     try {
         return realpathSync(p);
@@ -297,17 +306,43 @@ async function runStateWritable(explicitStateFile) {
 /** `skyramp_modularization` was called for this spec. Ownership on the write, like
  *  the utils debt: a same-basename spec elsewhere does not inherit the mark. */
 export async function recordModularized(testFile, explicitStateFile) {
+    // The spec as handed out — after the enhancer, before any code moves. Taken once;
+    // a second modularization call must not overwrite the true "before".
+    let baseline;
+    const spec = utilsSpecForFile(testFile);
+    if (spec) {
+        try {
+            const content = await fsp.readFile(testFile, "utf8");
+            baseline = {
+                assertions: countAssertions(content, spec),
+                pageErrorGuard: hasPageErrorGuard(content, spec),
+            };
+        }
+        catch {
+            /* fail open: no baseline, no assertion check */
+        }
+    }
     await updateReuseOutcome(testFile, (existing) => owns(existing, testFile)
-        ? { testFilePath: existing.testFilePath ?? testFile, modularized: true }
+        ? {
+            testFilePath: existing.testFilePath ?? testFile,
+            modularized: true,
+            baseline: existing.baseline ?? baseline,
+        }
         : {
             testFilePath: testFile,
             modularized: true,
+            baseline,
             utils: undefined,
             verification: undefined,
             candidatesDetected: undefined,
             flagged: undefined,
         }, explicitStateFile);
 }
+/** The modularization-hand-out baseline for this spec, if one was recorded for it. */
+export async function utilsBaselineFor(testFile, explicitStateFile) {
+    const record = await readReuseRecord(testFile, explicitStateFile);
+    return record && owns(record, testFile) ? record.baseline : undefined;
+}
 /**
  * Does this spec owe `skyramp_modularization` before reuse may be issued? Only a spec
  * generation handed off (modularize-first flows: the hand-off names both calls, in
@@ -606,13 +641,16 @@ async function rederiveHelperOutcome(record) {
         testFile: testFilePath,
         language,
         testType: record.utils?.testType,
+        baseline: record.baseline,
     });
     if (r.utilsFiles.length === 0)
         return {};
+    const lost = r.violations.some((v) => v.kind === "assertion-loss" || v.kind === "guard-removed");
     return {
         helpers: {
-            utilsFile: r.utilsFiles.map((f) => path.basename(f)).join(", "),
+            utilsFile: utilsFileLabel(r.utilsFiles),
             helpersImported: r.imported,
+            ...(record.baseline ? { assertionsPreserved: !lost } : {}),
             ...(r.inlineCallSites.length > 0
                 ? { siblingInlineCallSites: r.inlineCallSites.length }
                 : {}),

package/build/tools/code-refactor/utils-verify-gates.js

@@ -1,5 +1,5 @@
 import * as path from "path";
-import { allowMarkerLine, } from "../../utils/utils-verify/index.js";
+import { allowMarkerLine, MARKERABLE_UTILS_KINDS, HELPER_FAMILIES, } from "../../utils/utils-verify/index.js";
 /** How many verify rounds the agent may spend before it must document what remains.
  *  SKYR-4059: an unbounded repair loop made six execution attempts against a cap of
  *  two and destroyed verified reuse in between. The bound is stated in the text the
@@ -15,9 +15,12 @@ function show(file, r) {
         : file;
 }
 export function formatUtilsVerifyText(r, ctx = {}) {
-    const tail = verdictTail(ctx) + unstagedTail(r, ctx) + namingAdvisory(r);
+    const tail = verdictTail(ctx) +
+        unstagedTail(r, ctx) +
+        namingAdvisory(r) +
+        typingAdvisory(r);
     const spec = r.spec;
-    if (r.utilsFiles.length === 0) {
+    if (r.utilsFiles.length === 0 && r.violations.length === 0) {
         return ("VERIFICATION PASSED — no shared utils file is written or imported for this test; nothing to verify. " +
             "(If you did create one, it carries no `Generated by Skyramp on …` header line, so it cannot be recognised or staged — add the header and re-verify.)" +
             tail);
@@ -30,7 +33,8 @@ export function formatUtilsVerifyText(r, ctx = {}) {
         return (`VERIFICATION PASSED — ${files}: ${r.helpers} helper${r.helpers === 1 ? "" : "s"}, ${r.imported} imported by this test.${allowed} ` +
             `${ctx.staged && ctx.staged.length > 0 ? "The utils file is staged for the output commit. " : ""}Continue.` +
             tail +
-            inlineCallSitesAdvisory(r));
+            inlineCallSitesAdvisory(r) +
+            singleImporterAdvisory(r));
     }
     const lines = [];
     if (r.violations.length > 0) {
@@ -38,19 +42,36 @@ export function formatUtilsVerifyText(r, ctx = {}) {
         for (const v of r.violations) {
             lines.push(`- ${v.kind} · ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`);
         }
-        lines.push("", `Fix each violation in the utils file (${r.family.family === "browser" ? "a shared browser helper holds actions and structural waits only; names are the user intent" : "a shared API helper asserts only the status code; one helper per method+path, extended with defaulted parameters; names are method + resource only"}), update any call site whose signature changed, then call skyramp_reuse_code again with the SAME arguments and \`verify: true\`. Re-verify after every fix pass; finish only on PASSED.`, `A violation that is deliberate may be documented instead of fixed. Copy the matching line below into the utils file as a comment, replacing only the <reason…> part — nothing else satisfies the gate:`);
-        if (spec) {
-            for (const v of r.violations)
-                lines.push(`    ${allowMarkerLine(spec, v.kind, v.helper)}`);
+        lines.push("", 
+        // The fix rules come from the policy objects, not restated here; the browser
+        // clause reads as a continuation of the api one for mixed files.
+        `Fix each shared-helper violation in the utils file (${r.fallbackFamily.family === "browser"
+            ? `${HELPER_FAMILIES.api.fixRule}; ${HELPER_FAMILIES.browser.fixRule}`
+            : HELPER_FAMILIES.api.fixRule}), update any call site whose signature changed, then call skyramp_reuse_code again with the SAME arguments and \`verify: true\`. Re-verify after every fix pass; finish only on PASSED.`);
+        // Marker guidance only for kinds a marker can document: a guard-removed-only
+        // failure must not be told "every deliberate violation may be documented".
+        const markerable = r.violations.filter((v) => v.kind !== "guard-removed" && v.kind !== "import-form");
+        if (markerable.length > 0) {
+            lines.push(`A violation that is deliberate may be documented instead of fixed. Copy the matching line below into the utils file as a comment, replacing only the <reason…> part — nothing else satisfies the gate:`);
+            if (spec)
+                for (const v of markerable)
+                    lines.push(`    ${allowMarkerLine(spec, v.kind, v.helper)}`);
+            lines.push(`Do not spend more than ${UTILS_VERIFY_MAX_ROUNDS} verify rounds on this file: if violations remain after round ${UTILS_VERIFY_MAX_ROUNDS}, document each remaining one with its line above and re-verify once more.`);
         }
-        lines.push(`Do not spend more than ${UTILS_VERIFY_MAX_ROUNDS} verify rounds on this file: if violations remain after round ${UTILS_VERIFY_MAX_ROUNDS}, document each remaining one with its line above and re-verify once more.`);
+        if (r.violations.some((v) => v.kind === "import-form"))
+            lines.push("An `import-form` violation is in the TEST file, not the utils file: replace that import with the try/except pair shown on the line above, then re-verify. Nothing in the utils file needs to change for it.");
+        if (r.violations.some((v) => v.kind === "guard-removed"))
+            lines.push("A removed page-error guard cannot be documented away — restore the registration (in the spec, or in a shared helper the spec imports and calls) and its final expect, then re-verify.");
     }
     if (r.malformedAllows.length > 0) {
         lines.push(r.violations.length > 0
             ? ""
-            : "VERIFICATION FAILED — every violation is documented, but not every marker can be read back.", "Fix these `reuse-verify: allow` lines — the report cannot read them, so the declines they document would be dropped silently:", ...r.malformedAllows.map((m) => `    ${show(m.file, r)}: ${m.line}`), `The form is \`${spec?.commentPrefix ?? "#"} reuse-verify: allow <kind> <helper> — <reason>\` with the reason separated by an em dash or a hyphen with a space on BOTH sides, the kind one of duplicate-helper / body-assertion / scenario-name, and the reason written out (not the <reason…> placeholder).`);
+            : "VERIFICATION FAILED — every violation is documented, but not every marker can be read back.", "Fix these `reuse-verify: allow` lines — the report cannot read them, so the declines they document would be dropped silently:", ...r.malformedAllows.map((m) => `    ${show(m.file, r)}: ${m.line}`), `The form is \`${spec?.commentPrefix ?? "#"} reuse-verify: allow <kind> <helper> — <reason>\` with the reason separated by an em dash or a hyphen with a space on BOTH sides, the kind one of ${MARKERABLE_UTILS_KINDS.join(" / ")}, and the reason written out (not the <reason…> placeholder).`);
     }
-    return lines.join("\n") + tail + inlineCallSitesAdvisory(r);
+    return (lines.join("\n") +
+        tail +
+        inlineCallSitesAdvisory(r) +
+        singleImporterAdvisory(r));
 }
 /** SKYR-4219: the sibling call-site pass the prompt asks for and the agent skips (0/2
  *  seeded eval runs). Stated here because the verify call is the one point every run
@@ -68,9 +89,26 @@ function inlineCallSitesAdvisory(r) {
         "",
         `ADVISORY — ${n} inline request call${n === 1 ? "" : "s"} in other Skyramp-generated tests that a shared helper already wraps:`,
         ...r.inlineCallSites.map((c) => `- ${show(c.file, r)}:${c.line} · ${c.method} ${c.path} · ${utils}.${c.helper}`),
-        `Each is a candidate: the request's method, path and call shape match the helper's. Replace the block with a call to the helper only if the remaining differences are literals (they become the arguments; keep the block's response variable; import the helper into that file; change nothing else there), then re-verify. This does not block execution.`,
+        `Each is a candidate: the request's method, path and call shape match the helper's. Replace the block with a call to the helper only if the remaining differences are literals (they become the arguments; keep the block's response variable; import the helper into that file; change nothing else there), then re-verify AND run the edited file with skyramp_execute_test — an edited pre-existing test without a recorded execution cannot be reported. This does not block execution.`,
     ].join("\n");
 }
+/** Helpers only this test (or no test) imports. Advisory: on a first run every helper
+ *  is single-use by design — it seeds the utils file for the tests that follow — so
+ *  this never blocks; it names the helpers whose sharing has not (yet) happened. */
+function singleImporterAdvisory(r) {
+    const single = r.singleImporters;
+    if (single.length === 0 || r.helpers === 0)
+        return "";
+    const dead = single.filter((h) => h.importers === 0);
+    const lines = ["", ""];
+    if (dead.length > 0)
+        lines.push(`ADVISORY — ${dead.length} helper${dead.length === 1 ? " is" : "s are"} imported by NOTHING, not even the test that wrote ${dead.length === 1 ? "it" : "them"} (does not block):`, ...dead.map((h) => `- ${show(h.file, r)}:${h.line} · ${h.helper}`), "A dead helper is always actionable: call it from the test it belongs to, or delete it.");
+    const once = single.filter((h) => h.importers === 1);
+    if (once.length === 0)
+        return lines.join("\n");
+    lines.push(`ADVISORY — ${once.length} of ${r.helpers} shared helper${r.helpers === 1 ? "" : "s"} ${once.length === 1 ? "is" : "are"} imported by exactly one test (does not block):`, ...once.map((h) => `- ${show(h.file, r)}:${h.line} · ${h.helper}`), "Other delivered tests exist and do not call these. Inline a helper back into its test only if it wraps a step specific to this scenario's narrative that no other test would perform as-is; a request wrapper or a cross-test action (sign-in, open a form, apply a filter) stays shared.");
+    return lines.join("\n");
+}
 function unstagedTail(r, ctx) {
     if (!ctx.unstaged || ctx.unstaged.length === 0)
         return "";
@@ -81,17 +119,33 @@ function unstagedTail(r, ctx) {
 /** Naming is advised, never enforced: a heuristic that blocked execution on
  *  `create_test_case` or `list_expired_subscriptions` would be the worse outcome. */
 function namingAdvisory(r) {
-    if (r.advisories.length === 0)
+    const names = r.advisories.filter((v) => v.kind === "scenario-name");
+    if (names.length === 0)
         return "";
-    const n = r.advisories.length;
+    const n = names.length;
     return [
         "",
         "",
         `ADVISORY — ${n} helper name${n === 1 ? "" : "s"} look${n === 1 ? "s" : ""} scenario-flavoured (does not block):`,
-        ...r.advisories.map((v) => `- ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`),
+        ...names.map((v) => `- ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`),
         "Shared helpers are named by method + resource (API) or user intent (browser); scenario values and adjectives belong in arguments. Rename if the name would stop another test from reusing the helper; otherwise continue.",
     ].join("\n");
 }
+/** TypeScript only. Whether an untyped parameter breaks the customer's build depends
+ *  on their tsconfig reaching the tests directory, so this advises and never blocks. */
+function typingAdvisory(r) {
+    const typed = r.advisories.filter((v) => v.kind === "untyped-parameter");
+    if (typed.length === 0)
+        return "";
+    const n = typed.length;
+    return [
+        "",
+        "",
+        `ADVISORY — ${n} helper${n === 1 ? " has" : "s have"} untyped parameters (does not block):`,
+        ...typed.map((v) => `- ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`),
+        "Annotate each with its actual type — a Playwright page as `page: Page` (add `import type { Page } from '@playwright/test'` once, only if a page parameter is among them); API values by their shape (`client: SkyrampClient`, `headers: Record<string, string>`); never `any`. Advisory only: continue without re-verifying, and do NOT write a `reuse-verify` marker for it.",
+    ].join("\n");
+}
 function verdictTail(ctx) {
     if (ctx.recorded !== false)
         return "";

package/build/tools/executeSkyrampTestTool.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { pendingReuseDebt } from "./code-refactor/reuse-state.js";
-import { pendingAssertionEnhancement } from "./code-refactor/enhance-state.js";
-import { stageUtilsArtifacts } from "../utils/utils-verify/index.js";
+import { assertionFeedbackForExecution, recordAssertionExecution, } from "./code-refactor/assertion-state.js";
+import { stageAndRecordRetrofits } from "./code-refactor/retrofit-state.js";
 import path from "path";
 import { stripVTControlCharacters } from "util";
 import { TestExecutionService } from "../services/TestExecutionService.js";
@@ -227,17 +227,6 @@ export function registerExecuteSkyrampTestTool(server) {
                 errorResult = toolError(`testFile must be an absolute path, got: ${params.testFile}`);
                 return errorResult;
             }
-            // SKYR-4262: block execution when skyramp_enhance_assertions handed out
-            // instructions for this spec and the file has not changed since — the
-            // agent acknowledged the enhancement step without acting on it. The debt
-            // clears through the file itself (any edit, including a documented
-            // `// assertions reviewed:` no-change decision), so the agent can never
-            // be stuck here. Same enforcement shape as the reuse checkpoint above.
-            const owedEnhancement = await pendingAssertionEnhancement(params.testFile, params.stateFile);
-            if (owedEnhancement) {
-                errorResult = toolError(owedEnhancement);
-                return errorResult;
-            }
             // Deterministic external-test guard (SKYR-3924): this tool runs Skyramp-generated
             // tests in the executor and cannot run a repo's native (user-written) suite, so a
             // run on an external test only errors (e.g. pytest import/collection failure).
@@ -270,7 +259,7 @@ export function registerExecuteSkyrampTestTool(server) {
             // the last step before delivery, and a utils file left unstaged here ships a
             // test importing a module the PR lacks. After the external-test skip: a native
             // suite this tool will not run gets no scan and no staging.
-            await stageUtilsArtifacts(params.testFile);
+            await stageAndRecordRetrofits(params.testFile, undefined, params.stateFile);
             // SKYR-4115 backstop: enhance_assertions carries the same check, but nothing
             // guarantees the agent calls it, and execution is the last step that still
             // precedes reporting. See pendingReuseVerification for why enforcing the verify
@@ -285,6 +274,22 @@ export function registerExecuteSkyrampTestTool(server) {
                 errorResult = toolError(owedReuseVerification);
                 return errorResult;
             }
+            // Deterministic assertion-enhancement check: the server verifies the file
+            // itself here (never relying on the agent to call `verify: true` — prose
+            // can be ignored, this cannot). Insufficient assertions return feedback
+            // instead of executing; a fixed file passes on the next execute call.
+            // Sits BELOW the external-test guard: an external test is skipped, not
+            // executed, so deferring it for assertion work would demand fixes to a
+            // file this tool will never run.
+            const assertionFeedback = await assertionFeedbackForExecution(params.testFile, params.stateFile);
+            if (assertionFeedback) {
+                errorResult = toolError(assertionFeedback);
+                return errorResult;
+            }
+            // Proof-of-work substrate (SKYR-4262 follow-up): count this execution
+            // server-side so the report can cross-check generated vs executed —
+            // the narrative is LLM-authored, this number is not. Best-effort.
+            await recordAssertionExecution(params.testFile, params.testType, params.stateFile);
             // Send initial progress
             await sendProgress(5, 100, "Starting test execution...");
             // Cross-repo run (SKYR-3819): tests delivered under the run's testsRepoDir

package/build/tools/submitReportTool.js

@@ -12,9 +12,11 @@ import { StateManager, runArtifactDir, getTestsRepoDir, } from "../utils/Analysi
 import { toolError, testFileMatches } from "../utils/utils.js";
 import { matchesApprovedPlan } from "../utils/planMatchKeys.js";
 import { isTestbotEnabled } from "../utils/featureFlags.js";
-import { findInvalidSourceCitations, findUnchangedFileClaims, listChangedFiles, listChangedFilesAcross, } from "../utils/reportVerification.js";
+import { findInvalidSourceCitations, findUnchangedFileClaims, listChangedFiles, listChangedFilesAcross, listChangedFilesAbs, } from "../utils/reportVerification.js";
 import { getReportLanguage, isEnforcedReportLanguage, findLanguageViolations, findLanguageNearMisses, reportLanguageDisplayName, } from "../utils/reportLanguage.js";
-import { rederiveReuseOutcome, reuseChainSkipped, } from "./code-refactor/reuse-state.js";
+import { canonicalTestPath, findAssertionRecordByFileName, rederiveAssertionOutcome, } from "./code-refactor/assertion-state.js";
+import { rederiveReuseOutcome, reuseChainSkipped, samePath, } from "./code-refactor/reuse-state.js";
+import { retrofitGate, } from "./code-refactor/retrofit-state.js";
 // SKYR-3879 Path B: which testTypes the register-plan checkpoint gates. Mirrors
 // the generation tools actually wired to planGuard (batch-scenario/integration,
 // contract) — UI and E2E are on a separate blueprint-grounded pipeline and are
@@ -641,7 +643,26 @@ function computeReportMetrics(params) {
  * gets `chainSkipped: true` (SKYR-4220), the one claim that is exactly about the
  * reuse tool NOT having run. Applies to every test type: UI tests carry the POM
  * fields, API tests the shared-helper ones. */
-async function attachReuseOutcome(test, outcomes, handOffs) {
+/** Attach the assertion-enhancement summary to a report row.
+ *
+ *  How the row finds its record: records are keyed by the test file's full
+ *  path, but a report row only carries a file NAME. So the match compares
+ *  basenames, then checks testType and repository. When more than one record
+ *  still matches, the row gets NO summary — attaching the wrong spec's
+ *  numbers is worse than attaching none.
+ *
+ *  The numbers are server-derived and re-computed from the delivered file at
+ *  report time — the report narrative is LLM-authored, these numbers are not.
+ *  What a reader can conclude: `executionCount: 0` = generated but never
+ *  executed; no `assertions` field at all = the enhance tool never ran for
+ *  the file and it never executed. */
+async function attachAssertionOutcome(test, outcomes, checkouts) {
+    const record = findAssertionRecordByFileName(outcomes, test, checkouts);
+    if (!record)
+        return test;
+    return { ...test, assertions: await rederiveAssertionOutcome(record) };
+}
+async function attachReuseOutcome(test, outcomes, handOffs, retrofits = []) {
     // POM records describe browser specs; a basename collision with an API test's
     // fileName must not attach them there. A utils-path record is attachable anywhere.
     const record = outcomes?.[path.basename(test.fileName)];
@@ -652,6 +673,18 @@ async function attachReuseOutcome(test, outcomes, handOffs) {
         ? record
         : undefined;
     const derived = found ? await rederiveReuseOutcome(found) : undefined;
+    // Pre-existing generated tests this spec's reuse pass rewired (SKYR-4276 A4): the
+    // report names each with its recorded execution, so a reviewer sees that the
+    // module became a dependency of code they already owned — and that it still runs.
+    if (derived?.helpers && found?.testFilePath) {
+        const specPath = found.testFilePath;
+        const mine = retrofits.filter((r) => samePath(r.testFile, specPath));
+        if (mine.length > 0)
+            derived.helpers.retrofits = mine.map((r) => ({
+                file: path.basename(r.file),
+                ...(r.execution ? { execution: r.execution } : {}),
+            }));
+    }
     // The RAW record: a colliding record of any kind means reuse ran for this basename,
     // and the chain claim must not be made on the filtered view.
     const chainSkipped = await reuseChainSkipped(test.fileName, test.testType, record, handOffs);
@@ -1036,6 +1069,11 @@ export function registerSubmitReportTool(server) {
                 "Add a testMaintenanceDetails entry with the missing field(s), drafted from the execution output you already saw.");
             return errorResult;
         }
+        // SKYR-4276 A4: retrofits (pre-existing generated tests the reuse pass edited)
+        // that still stand in the working tree, resolved once here and attached to the
+        // rows below; an unexecuted one refuses the report (inside the SKYR-3883 block,
+        // which already enumerates the working tree).
+        let retrofitViews = [];
         // SKYR-3883: in a testbot run, refuse to ship a report that claims file work
         // the working tree doesn't reflect. The delivery step can only commit what the
         // agent actually created/edited, so a report claiming otherwise erodes trust
@@ -1096,6 +1134,17 @@ export function registerSubmitReportTool(server) {
                             `Files with actual working-tree changes:\n${changedList || "  (none)"}`);
                         return errorResult;
                     }
+                    const changedFilesAbs = await listChangedFilesAbs([
+                        repoRoot,
+                        getTestsRepoDir(),
+                        ...Object.values(fullState?.relatedRepos ?? {}).map((section) => section.repositoryPath),
+                    ]);
+                    const gate = await retrofitGate(stateData, changedFilesAbs, repoRoot);
+                    retrofitViews = gate.views;
+                    if (gate.refusal) {
+                        errorResult = toolError(gate.refusal);
+                        return errorResult;
+                    }
                 }
                 catch (err) {
                     // Never block a valid report because verification itself failed (path not a
@@ -1133,7 +1182,16 @@ export function registerSubmitReportTool(server) {
         // generation — downstream scoring scripts don't expect them and fail if
         // they encounter these string fields while traversing the object.
         // Also normalize each item's `repository` (blank → undefined).
-        const sanitizedNewTests = await Promise.all(dedupedNewTests.map(({ scenarioFile: _sf, traceFile: _tf, frontendTrace: _ft, ...rest }) => attachReuseOutcome(normalizeRepository(rest), stateData.reuseOutcomes, stateData.reuseHandOffs)));
+        // Checkout roots let the assertion-record matcher verify a candidate
+        // record actually lives in the row's repo (basename collisions across
+        // repos must not publish one spec's proof-of-work under another's name).
+        const assertionCheckouts = await stateManager
+            .listRepoCheckouts()
+            .catch(() => []);
+        const sanitizedNewTests = await Promise.all(dedupedNewTests.map(async ({ scenarioFile: _sf, traceFile: _tf, frontendTrace: _ft, ...rest }) => {
+            const row = await attachReuseOutcome(normalizeRepository(rest), stateData.reuseOutcomes, stateData.reuseHandOffs, retrofitViews);
+            return attachAssertionOutcome(row, stateData.assertionOutcomes ?? {}, assertionCheckouts);
+        }));
         const report = {
             businessCaseAnalysis: params.businessCaseAnalysis,
             newTestsCreated: sanitizedNewTests,
@@ -1142,10 +1200,25 @@ export function registerSubmitReportTool(server) {
             // an internal-only field, needed for matching but never meant to reach the report.
             // TODO(multi-repo maintenance): map(normalizeRepository) once testMaintenanceSchema
             // has a repository field (see TODO above).
-            testMaintenance: testMaintenance?.map(({ testFilePath, ...row }) => ({
-                ...row,
-                fileName: path.basename(testFilePath),
-            })),
+            testMaintenance: testMaintenance
+                ? await Promise.all(testMaintenance.map(async ({ testFilePath, ...row }) => {
+                    // Maintenance rows still carry the absolute path here, so the
+                    // assertion summary uses an EXACT canonical-path lookup — no
+                    // basename ambiguity. This is what carries the maintenance
+                    // honesty labels (nothing-to-verify vs verified) into the
+                    // report instead of leaving them as tool text the agent can
+                    // paraphrase.
+                    const record = stateData.assertionOutcomes?.[canonicalTestPath(testFilePath)];
+                    const assertions = record
+                        ? await rederiveAssertionOutcome(record)
+                        : undefined;
+                    return {
+                        ...row,
+                        fileName: path.basename(testFilePath),
+                        ...(assertions ? { assertions } : {}),
+                    };
+                }))
+                : undefined,
             // videoPath is filled from the run's execution records; testFilePath is the
             // match-only key and is stripped from the wire format, the same line drawn for
             // testMaintenance's own testFilePath above (downstream scoring scripts traverse