@skyramp/mcp 0.4.1 → 0.4.2-rc.1

package/build/utils/utils-verify/verify.js

@@ -1,13 +1,31 @@
 import * as fs from "fs";
 import * as path from "path";
 import { logger } from "../logger.js";
-import { locateUtilsFiles } from "./locate.js";
-import { blankCommentsAndStrings, countAssertions, hasPageErrorGuard, parseUtilsFile, } from "./parse.js";
+import { isInside, locateUtilsFiles, realpath, resolveSpecImports, } from "./locate.js";
+import { generateSkyrampHeader } from "../utils.js";
+import { typecheckDelivered } from "./typecheck.js";
+import { blankComments, blankCommentsAndStrings, countAssertions, hasPageErrorGuard, parseUtilsFile, } from "./parse.js";
 import { escapeRegExp } from "../regex.js";
+import { detectGitRoot } from "../gitStaging.js";
+import { isModularizeFirstTarget } from "../reuseRouting.js";
+import { findDuplicateBodyReach, findUnreachableBodies } from "./body-reach.js";
+import { misnamedNewModules } from "./module-name.js";
+import { additiveChanges, locateInHouseModules, resolveInHouseCalls, } from "./in-house.js";
 import { findSiblingInlineCallSites, findUnextractedDuplicates, generatedSiblings, } from "./call-sites.js";
 import { parseUtilsAllows, } from "./allow.js";
+import { describeFixedSleeps, fixedSleepReplacement } from "./fixed-sleep.js";
 import { singleImporterHelpers, } from "./importers.js";
+import { assertsStatusEquality, defaultedStatusParam, pinnedStatusLiteral, restatedStatusAssertions, } from "./status-once.js";
+import { STATUS_ONCE_RULE } from "../../prompts/shared-helper-policy.js";
+import { committedBaseline } from "./retrofit-equivalence.js";
+import { incumbentSignatureViolations } from "./incumbent.js";
 import { helperFamilyFor, helperFamilyOf, scenarioNameViolation, utilsSpecFor, utilsSpecForFile, } from "./language-spec.js";
+/** What the compiler says about a name defined twice, which `helper-redefined`
+ *  already reports once with its remediation: TS2393 "Duplicate function
+ *  implementation" and TS2323 "Cannot redeclare exported variable" for two
+ *  `function` declarations, TS2451 "Cannot redeclare block-scoped variable" for two
+ *  `const` arrow helpers. */
+const REDECLARATION_CODES = new Set([2393, 2323, 2451]);
 /**
  * Deterministic post-reuse check of the shared utils file(s) a spec depends on.
  *
@@ -25,20 +43,51 @@ import { helperFamilyFor, helperFamilyOf, scenarioNameViolation, utilsSpecFor, u
  *    helper (runs 5 and 11 — `assert total_amount == 16.0` in `update_order`); a
  *    body assertion carries one scenario's values into a function every scenario calls.
  *  - `scenario-name` (ADVISORY only): a helper named for its scenario rather than its step.
+ *  - `status-default` (ADVISORY for now) and `status-restated`: the status a test
+ *    expects is stated ONCE, as the call's argument — not omitted behind a defaulted
+ *    parameter, and not asserted again in the spec on the response the helper
+ *    returned. See status-once.ts.
+ *  - `type-error` (TypeScript): the delivered module or spec fails the compiler with
+ *    every strictness flag off — an error under every configuration (a path parameter
+ *    typed `unknown`, request options built as a record and handed to `sendRequest`).
+ *    An error only the repository's own tsconfig raises is the `tsconfig-type-error`
+ *    ADVISORY. See typecheckDelivered.
  *
  * Analyses the utils files' INTERNAL invariants — unlike the POM verifier, which
  * checks a spec's cross-file references — so it reads the utils files, not the spec,
  * except to count what the spec imports.
  */
 export async function verifyUtils(params) {
-    const spec = utilsSpecFor(params.language) ?? utilsSpecForFile(params.testFile);
+    // The spec file's extension decides its language; the declared language covers
+    // a path whose extension names none. Each utils file is then judged by ITS OWN
+    // extension (`fileSpec` below): a TypeScript spec may import a JavaScript
+    // module, and the TypeScript-only rules — the signature advisory, the compiler —
+    // must not read it (run 9, sample-microservices: `client: SkyrampClient`
+    // prescribed into a `.js` file, and node's `assert` reported unresolved).
+    const spec = utilsSpecForFile(params.testFile) ?? utilsSpecFor(params.language);
     const family = helperFamilyFor(params.testType);
+    // CANONICAL, once: `locateInHouseModules` realpaths every module it returns, and
+    // `git show HEAD:<rel>` needs a path relative to the same root. A caller-supplied
+    // cwd routinely is not canonical — a sandboxed run works under macOS's /tmp, a
+    // symlink to /private/tmp — and the mismatch made `path.relative` yield a path git
+    // could not read, so the additive gate returned `ran: false` and the pass went
+    // green over a module it never compared.
+    const rawRoot = params.cwd ?? detectGitRoot(params.testFile);
+    const root = rawRoot ? await realpath(rawRoot) : undefined;
+    // The repository's own modules the spec imports — ownership decided at HEAD (see
+    // locateInHouseModules). Found BEFORE the utils files so a customer module that
+    // gained our header this run is judged by the additive gate, never by the Skyramp
+    // invariants: the header locator would otherwise claim it.
+    const inHouse = spec
+        ? await locateInHouseModules({ testFile: params.testFile, spec, cwd: root })
+        : [];
+    const inHouseFiles = new Set(inHouse.map((m) => m.file));
     const utilsFiles = spec
-        ? await locateUtilsFiles({
+        ? (await locateUtilsFiles({
             testFile: params.testFile,
             language: spec.language,
             cwd: params.cwd,
-        })
+        })).filter((f) => !inHouseFiles.has(f))
         : [];
     const result = {
         ok: true,
@@ -49,6 +98,7 @@ export async function verifyUtils(params) {
         violations: [],
         allowed: [],
         advisories: [],
+        carriedConsumed: [],
         malformedAllows: [],
         spec,
         fallbackFamily: family,
@@ -67,9 +117,19 @@ export async function verifyUtils(params) {
     }
     if (spec.language === "python")
         result.violations.push(...importFormViolations(params.testFile, specContent, utilsFiles));
+    // Imports and module qualifiers are read with comments blanked and strings kept:
+    // a commented-out `import * as client from "./skyrampUtils"` authorised `client.`
+    // as the module's qualifier, and a commented-out named import counted as one.
+    const liveSpec = blankComments(specContent, spec);
+    /** Per utils file, the helpers defined at HEAD — not this run's. Read once and
+     *  kept: both the status advisory's scope and the restatement's remediation
+     *  turn on it. */
+    const incumbentsOfFile = new Map();
     const allHelpers = [];
     const helpersByFile = new Map();
     const allAllows = [];
+    /** Findings from every located file, classified after the walk — see below. */
+    const pending = [];
     const importedNames = new Set();
     const importedByFile = new Map();
     const helpersOfFile = new Map();
@@ -93,61 +153,328 @@ export async function verifyUtils(params) {
             });
             throw err; // the caller records a verify error, which fails OPEN — never a silent PASS
         }
-        const helpers = parseUtilsFile(content, spec);
+        const fileSpec = utilsSpecForFile(file) ?? spec;
+        const helpers = parseUtilsFile(content, fileSpec);
+        // The module as committed: its helpers are INCUMBENTS. The status rule governs
+        // helpers this run writes, so a defaulted status on an incumbent is not advised
+        // — and an incumbent's signature is held to what it was (incumbent.ts). Absent
+        // for a module this run created, or outside git: then every helper is this run's.
+        const baseline = await committedBaseline(file);
+        const headHelpers = baseline === undefined ? [] : parseUtilsFile(baseline, fileSpec);
+        const incumbents = new Set(headHelpers.map((h) => h.name));
+        incumbentsOfFile.set(file, incumbents);
+        pending.push(...incumbentSignatureViolations(headHelpers, helpers, file));
         for (const h of helpers) {
-            // An untyped parameter is an error under `noImplicitAny`; whether the host repo's
-            // tsconfig reaches the tests directory is its call, so this advises and never blocks.
-            if (h.untypedParams.length > 0)
+            // A static reading of the signature. An unannotated parameter is an error only
+            // under `noImplicitAny`, and `any` is never one — whether the host repo's
+            // tsconfig reaches the tests directory is its call — so this advises and never
+            // blocks; the compiler run below is what blocks, on the error an `unknown`
+            // parameter produces at its first use.
+            if (h.unusableParamTypes.length > 0)
                 result.advisories.push({
-                    kind: "untyped-parameter",
+                    kind: "unusable-parameter-type",
                     file,
                     helper: h.name,
                     line: h.line,
                     // Names only — the remediation is stated once, in the advisory footer.
-                    detail: h.untypedParams.map((p) => `\`${p}\``).join(", "),
+                    detail: h.unusableParamTypes.map((p) => `\`${p}\``).join(", "),
                 });
         }
         allHelpers.push(...helpers);
         helpersByFile.set(file, helpers);
         helpersOfFile.set(file, helpers);
-        const { allows, malformed } = parseUtilsAllows(content, spec);
-        allAllows.push(...allows);
+        const { allows, malformed } = parseUtilsAllows(content, fileSpec);
+        allAllows.push(...allows.map((a) => ({ ...a, file })));
         result.helpers += helpers.length;
         result.malformedAllows.push(...malformed.map((line) => ({ file, line })));
         const stem = path.basename(file).replace(/\.[^.]+$/, "");
         const defined = new Set(helpers.map((h) => h.name));
         const importedHere = new Set();
-        for (const n of spec.importedNames(specContent, stem))
+        for (const n of spec.importedNames(liveSpec, stem))
             if (defined.has(n)) {
                 importedNames.add(n);
                 importedHere.add(n);
             }
         importedByFile.set(file, importedHere);
-        // One marker documents ONE violation of that kind in that helper: a second,
-        // undocumented scenario claim in the same helper is not covered by the first
-        // decline. Markers are consumed in order.
-        const budget = new Map();
-        for (const a of allows) {
-            const k = `${a.kind}\0${a.helper}`;
-            budget.set(k, (budget.get(k) ?? 0) + 1);
-        }
-        for (const v of violationsIn(helpers, file, family, spec, { byRoute, byName, byAction }, result.advisories)) {
-            const k = `${v.kind}\0${v.helper}`;
-            const left = budget.get(k) ?? 0;
-            if (left > 0) {
-                budget.set(k, left - 1);
-                result.allowed.push(v);
-            }
-            else if (v.kind === "scenario-name") {
-                result.advisories.push(v);
+        // Findings are collected here and classified once every file has been read: a
+        // marker may sit beside the CALLER while the finding it documents is raised in
+        // the module next to it, and a per-file budget could never reach across.
+        pending.push(...violationsIn(helpers, file, family, fileSpec, { byRoute, byName, byAction }, result.advisories, incumbents));
+    }
+    result.imported = importedNames.size;
+    result.importedNames = [...importedNames].sort();
+    // The repository's own modules the spec imports. Their helpers join the baseline
+    // count for every family — the count asks what the delivered test asserts, and a
+    // customer's helper asserts whatever it asserts — while the resolve and additive
+    // checks run for browser helpers only: a browser helper and the step it replaces
+    // drive one library, so the checks have something to read; an API helper written
+    // against another HTTP client does not, and that gate is a separate change.
+    // The SAME predicate the prompt routes on, not a copy of its conditions: STEP
+    // 2b/3b are emitted for a modularize-first browser target, which is UI with utils
+    // reuse on and page-object reuse OFF. A hand-maintained `testType === "ui"` also
+    // fired where the prompt gives no workflow — with the page-object flag on and a
+    // non-Playwright framework, which takes the plain reuse prompt — and a gate the
+    // agent was given no way to satisfy is a run that cannot finish.
+    const inHouseResult = isModularizeFirstTarget(params.testType, spec.language) &&
+        helperFamilyFor(params.testType).family === "browser" &&
+        inHouse.length > 0
+        ? {
+            modules: inHouse.map((m) => m.file),
+            resolved: [],
+            unverifiable: [],
+            additiveGateRan: true,
+            added: [],
+            widened: [],
+        }
+        : undefined;
+    for (const m of inHouse) {
+        let content;
+        try {
+            content = await fs.promises.readFile(m.file, "utf8");
+        }
+        catch (err) {
+            // A module HEAD holds and the working tree does not was deleted by this run:
+            // nothing to resolve against, and the additive gate is what says so.
+            if (err?.code === "ENOENT" &&
+                inHouseResult &&
+                root) {
+                const additive = await additiveChanges(m.file, root, spec);
+                if (!additive.ran)
+                    inHouseResult.additiveGateRan = false;
+                pending.push(...additive.violations);
+                continue;
             }
-            else {
-                result.violations.push(v);
+            logger.warning("Could not read an in-house module the spec imports", {
+                file: m.file,
+                error: String(err),
+            });
+            if (inHouseResult)
+                inHouseResult.additiveGateRan = false;
+            continue;
+        }
+        const helpers = parseUtilsFile(content, spec);
+        const stem = path.basename(m.file).replace(/\.[^.]+$/, "");
+        const defined = new Set(helpers.map((h) => h.name));
+        const importedHere = new Set();
+        for (const n of spec.importedNames(specContent, stem))
+            if (defined.has(n))
+                importedHere.add(n);
+        helpersOfFile.set(m.file, helpers);
+        importedByFile.set(m.file, importedHere);
+        if (!inHouseResult || !root)
+            continue;
+        const resolution = resolveInHouseCalls(specContent, content, stem, spec, m.file);
+        inHouseResult.resolved.push(...resolution.resolved);
+        inHouseResult.unverifiable.push(...resolution.unverifiable);
+        pending.push(...resolution.violations);
+        const additive = await additiveChanges(m.file, root, spec);
+        if (!additive.ran)
+            inHouseResult.additiveGateRan = false;
+        pending.push(...additive.violations);
+        inHouseResult.added.push(...additive.added.map((helper) => ({ file: m.file, helper })));
+        inHouseResult.widened.push(...additive.widened.map((helper) => ({ file: m.file, helper })));
+        for (const d of additive.duplicates)
+            result.advisories.push({
+                kind: "in-house-duplicate",
+                file: m.file,
+                helper: d.added,
+                line: helpers.find((h) => h.name === d.added)?.line ?? 1,
+                detail: `\`${d.added}\`, added this run, performs the action sequence \`${d.existing}\` already performs in this module — call \`${d.existing}\` instead (lift a differing value into a defaulted parameter of it if needed) and delete \`${d.added}\``,
+            });
+    }
+    if (inHouseResult) {
+        inHouseResult.resolved.sort();
+        inHouseResult.unverifiable.sort();
+        result.inHouse = inHouseResult;
+    }
+    // The spec's own relative imports are evidence the locator can check without
+    // the header. Every one must be a utils file, an in-house module, or a test; a
+    // module none of those readers claims is one this pass cannot verify or stage,
+    // and a PASSED over it is a gate failing open — fixture 12, run 9: a module
+    // rewritten with a bare `// Generated by Skyramp` line passed four verify calls
+    // as "nothing to verify". Relative imports only (a package the sandbox lacks is
+    // a trap this must fail OPEN on) and not Python (spelled the same as a package).
+    const unchecked = [];
+    const unresolved = [];
+    const realTestFile = await realpath(params.testFile);
+    const utilsSet = new Set(utilsFiles);
+    const headerLine = generateSkyrampHeader(spec.language).trim();
+    const testShaped = (file) => /\.(?:spec|test)\.[cm]?[jt]sx?$/.test(path.basename(file));
+    for (const imp of await resolveSpecImports(params.testFile, spec)) {
+        const stem = (imp.specifier.split("/").pop() ?? imp.specifier).replace(/\.[cm]?[jt]sx?$/, "");
+        if (!imp.resolved) {
+            // A module HEAD holds and the working tree does not is located from HEAD
+            // and refused by the additive gate; this would say the same twice.
+            if (imp.candidates.some((c) => inHouseFiles.has(c)))
+                continue;
+            if (testShaped(imp.candidates[0] ?? ""))
+                continue;
+            // Reported, not blocked. This resolver tries a fixed set of extensions and an
+            // index file; the customer's toolchain resolves more — a component test
+            // imports a `.vue`, a fixture imports a `.sql`, a path alias points elsewhere
+            // — and every one of those exists on disk. "Could not resolve" is evidence
+            // about this pass, not about the file.
+            unresolved.push(imp.specifier);
+            continue;
+        }
+        if (utilsSet.has(imp.resolved) || imp.resolved === realTestFile)
+            continue;
+        if (inHouseFiles.has(imp.resolved)) {
+            if (!inHouseResult)
+                unchecked.push(imp.resolved);
+            continue;
+        }
+        if (testShaped(imp.resolved))
+            continue;
+        if (root && !isInside(imp.resolved, root)) {
+            unchecked.push(imp.resolved);
+            continue;
+        }
+        // A module is one the reuse step should have written only if the spec calls
+        // HELPERS from it. A data module — constants, bodies, fixtures — is a
+        // legitimate thing for a run to create beside a test, and demanding a Skyramp
+        // header on it is a block the agent cannot act on. The evidence is checkable:
+        // the names the spec imports, against the functions the module defines.
+        let defines = [];
+        try {
+            const imported = new Set(spec.importedNames(specContent, path.basename(imp.resolved).replace(/\.[^.]+$/, "")));
+            defines = parseUtilsFile(await fs.promises.readFile(imp.resolved, "utf8"), spec)
+                .map((h) => h.name)
+                .filter((n) => imported.has(n));
+        }
+        catch {
+            /* unreadable: judged below on the import alone */
+        }
+        if (defines.length === 0) {
+            unchecked.push(imp.resolved);
+            continue;
+        }
+        pending.push({
+            kind: "unresolved-module",
+            file: imp.resolved,
+            helper: stem,
+            line: 1,
+            // A module reaching this point is NOT tracked at HEAD: one at HEAD with the
+            // header is a utils file, and one at HEAD without it is the repository's
+            // own. So it is either a module this run wrote, or the customer's own file
+            // that is not committed yet — and nothing here can tell those apart. The
+            // message states both, because telling the agent to stamp our header on
+            // their file is the fault this PR's second blocking fix removed.
+            detail: `the test imports ${defines.map((n) => `\`${n}\``).join(", ")} from \`${imp.specifier}\` → ${root ? path.relative(root, imp.resolved) : imp.resolved}, a module of helpers that is not tracked at HEAD and carries no Skyramp header, so this pass cannot verify it or stage it and the pull request would not carry it. If this run wrote it: make its FIRST line exactly \`${headerLine}\` — the \`on <timestamp>\` part is what the shared-module tools recognise — and change nothing else in the file. If it is the repository's OWN module and simply not committed yet: do NOT add the header, leave the step inline, and name the module in the report. Then re-verify`,
+        });
+    }
+    if (unresolved.length > 0)
+        result.unresolvedImports = unresolved;
+    if (unchecked.length > 0) {
+        result.uncheckedModules = unchecked.sort();
+        if (!inHouseResult && inHouse.length > 0)
+            result.inHouseChecksSkipped = `this pass ran ${params.testType
+                ? `as a ${params.testType.toLowerCase()} test`
+                : "with no test type supplied"}, and they run for a UI test with page-object reuse off`;
+    }
+    // The spec asserts a status a helper it calls already asserted on the response it
+    // returned. Spec-level, like assertion-loss: the finding names the spec and the
+    // marker token is the helper. Only helpers that pin the status to ONE value count
+    // — after `toBeLessThan(500)` a `toBe(200)` in the spec is a tighter claim, not a
+    // repetition.
+    if (specContent) {
+        // Per utils FILE: a helper's contract travels with the module that defines it
+        // and the names the spec binds THAT module to. One flattened set of helpers
+        // and one of qualifiers cross-multiplied — `users.get` was scanned under
+        // `orders.get`'s pinning contract, and a same-name, equal-arity helper in two
+        // modules is a shape the verifier permits.
+        for (const [file, imported] of importedByFile) {
+            const pinning = [];
+            /** Helpers that pin a LITERAL status: the remediation differs, see below. */
+            const literalOf = new Map();
+            const incumbents = incumbentsOfFile.get(file) ?? new Set();
+            for (const h of helpersOfFile.get(file) ?? []) {
+                if (!imported.has(h.name) || !assertsStatusEquality(h, spec))
+                    continue;
+                pinning.push(h.name);
+                const literal = pinnedStatusLiteral(h, spec);
+                if (literal !== undefined)
+                    literalOf.set(h.name, literal);
             }
+            const qualifiers = spec.moduleQualifiers(liveSpec, path.basename(file).replace(/\.[^.]+$/, ""));
+            for (const r of restatedStatusAssertions(specContent, spec, pinning, qualifiers))
+                pending.push({
+                    kind: "status-restated",
+                    file: params.testFile,
+                    helper: r.helper,
+                    line: r.line,
+                    // Three shapes, three remediations. A helper that reads the status from a
+                    // parameter: the call already states it, so the spec's copy goes. A helper
+                    // THIS RUN WROTE that pins a literal has no call argument to keep, so the
+                    // literal is lifted first. An INCUMBENT that pins a literal keeps its
+                    // signature — adding a required parameter is what `incumbent-signature`
+                    // refuses, and prescribing it here would cost the run a round and end in a
+                    // marker; the pin is acceptable because no caller can vary it.
+                    detail: `\`${r.text}\` restates the status \`${r.helper}\` already asserts on the response it returned${r.sites > 1 ? ` (${r.sites} call sites do)` : ""} — ${STATUS_ONCE_RULE.notRestated}. ${remediation(r.helper, literalOf.get(r.helper), incumbents.has(r.helper))}`,
+                });
         }
     }
-    result.imported = importedNames.size;
-    result.importedNames = [...importedNames].sort();
+    // The compiler over the delivered files: the shared module(s) and the spec that
+    // imports them. The executor transpiles TypeScript without typechecking it, so
+    // this is the first typecheck the files meet before the customer's own. An error
+    // under the permissive settings fails under every configuration and blocks; one
+    // only the repository's tsconfig raises advises (see typecheckDelivered).
+    // Over the TypeScript files only, by extension: a JavaScript module is not
+    // typechecked (its spec would be `checkJs`, which no delivered file relies on),
+    // and a JavaScript spec is not compiled beside a TypeScript module.
+    const isTs = (f) => utilsSpecForFile(f)?.language === "typescript";
+    const tsUtils = utilsFiles.filter(isTs);
+    if (tsUtils.length > 0) {
+        // No existence guard: `realpath` falls back to `path.resolve`, and a root the
+        // compiler cannot find yields no source file, which the diagnostic walk skips.
+        const realSpec = await realpath(params.testFile);
+        const specFile = realSpec && isTs(realSpec) ? realSpec : undefined;
+        const files = specFile ? [...tsUtils, specFile] : tsUtils;
+        const tc = await typecheckDelivered(files);
+        result.typecheck = tc;
+        const subjectOf = (file, line) => file === specFile
+            ? path.basename(specFile).replace(/\W/g, "_")
+            : (helpersOfFile
+                .get(file)
+                ?.find((h) => h.line <= line && line <= h.endLine)?.name ??
+                path.basename(file).replace(/\.[^.]+$/, ""));
+        // One detector per fault: a name defined twice is `helper-redefined`, with its
+        // own remediation; the compiler says the same on each of the two definitions,
+        // twice each ("Duplicate function implementation", "Cannot redeclare exported
+        // variable"), and those four lines would add nothing but noise.
+        const redefined = new Set(pending
+            .filter((v) => v.kind === "helper-redefined")
+            .map((v) => `${v.file}\0${v.helper}`));
+        for (const e of tc.errors) {
+            const helper = subjectOf(e.file, e.line);
+            if (REDECLARATION_CODES.has(e.code) &&
+                redefined.has(`${e.file}\0${helper}`))
+                continue;
+            pending.push({
+                kind: "type-error",
+                file: e.file,
+                helper,
+                line: e.line,
+                detail: `\`TS${e.code}: ${e.message}\``,
+            });
+        }
+        for (const e of tc.ambientErrors)
+            result.advisories.push({
+                kind: "ambient-type-error",
+                file: e.file,
+                helper: subjectOf(e.file, e.line),
+                line: e.line,
+                detail: `\`TS${e.code}: ${e.message}\``,
+            });
+        for (const e of tc.settingErrors)
+            result.advisories.push({
+                kind: "tsconfig-type-error",
+                file: e.file,
+                helper: subjectOf(e.file, e.line),
+                line: e.line,
+                detail: `\`TS${e.code}: ${e.message}\``,
+            });
+    }
     // One directory walk feeds every sibling advisory: each sibling is read exactly once.
     let siblings = [];
     try {
@@ -190,16 +517,120 @@ export async function verifyUtils(params) {
             inHelpers,
         };
         for (const v of baselineViolations(params.baseline, params.testFile, spec, specContent, inSpec, inHelpers, guardInHelpers)) {
-            // A marker in any utils file documents an assertion-loss (never a removed
-            // guard). At most one loss finding exists per verify, so a matching marker's
-            // presence is the whole budget — nothing to consume.
-            if (v.kind === "assertion-loss" &&
-                allAllows.some((a) => a.kind === v.kind && a.helper === v.helper))
-                result.allowed.push(v);
-            else
-                result.violations.push(v);
+            // Classified with every other finding below: an assertion-loss marker lives in
+            // a utils file and the finding is about the spec, so it is cross-file by
+            // construction.
+            pending.push(v);
+        }
+    }
+    // Two rules about the module this run WROTE, both ungated by test type: a helper
+    // that issues a request follows the API rules whatever the test type drives (see
+    // helperFamilyOf), and a module's name is not a question about its helpers at all.
+    // Both fail open, and both ADVISE for their first cohort — the prompt states each
+    // rule, which is the lever that converges a cohort; this counts what it did.
+    result.advisories.push(...(await misnamedNewModules(utilsFiles, spec, params.cwd ?? detectGitRoot(params.testFile))));
+    try {
+        for (const d of await findDuplicateBodyReach(utilsFiles, spec))
+            result.advisories.push({
+                kind: "duplicate-body-reach",
+                file: d.utilsFile,
+                helper: d.helper,
+                line: d.line,
+                detail: `\`${d.helper}\` sends its request body from a body parameter AND from \`${d.override}\`, passed straight through. The body parameter already reaches every property a caller could override, so \`${d.override}\` changes nothing it cannot — and a second run writing this helper has no rule telling it whether to add one. Take one form: keep the body parameter and delete \`${d.override}\` from the signature and the request call, or keep the override and drop the body parameter. Update the call sites either way`,
+            });
+    }
+    catch {
+        /* never fails a verify on its own error */
+    }
+    // ONE classification pass, over every finding and every marker this verify saw.
+    //
+    // A marker documents ONE finding of its kind and helper, and it is consumed in
+    // order. The budget spans all the located utils files rather than one of them: a
+    // decline is written where the agent is working, which is often beside the CALLER
+    // and not beside the helper the finding names. A per-file budget left that finding
+    // blocking, the agent wrote a second marker in the other file, and the first then
+    // reported `stale-allow` — two refusals for one decline.
+    //
+    // A decline this run removed from a delivered file before delivery counts first.
+    // The marker is gone from the customer's copy, not from the run's record of what
+    // was declined, so a further submission must not refuse a fault already declined.
+    // It is never reported as stale: it is no line in any file, so there is nothing
+    // for the agent to delete.
+    // Queued, not counted: the ENTRY the caller passed is echoed back when a finding
+    // consumes it, so a tag the caller put on it (which file it came from) survives.
+    const carried = new Map();
+    for (const c of params.carriedAllows ?? []) {
+        const k = `${c.kind}\0${c.helper}`;
+        carried.set(k, [...(carried.get(k) ?? []), c]);
+    }
+    // Markers in file order, so "consumed in order" still holds and the SURPLUS marker
+    // is the later one — which is the line a reader would otherwise trust.
+    // A shared helper whose body no parameter reaches, beside a spec that wrote its own
+    // helper for the same route. Integration only, as the body rule is: the prompt
+    // states the shape, and this is the same statement in code, where it cannot be read
+    // two ways. Blocking, unlike the sibling advisories — those name a change to a
+    // PRE-EXISTING test the customer owns, and this names the module the run authored.
+    // Fails open on any read error, and bodyReachable answers `true` for everything it
+    // cannot establish, so a run is never blocked on a guess.
+    if ((params.testType ?? "").toLowerCase() === "integration") {
+        try {
+            for (const f of await findUnreachableBodies(params.testFile, utilsFiles, spec, siblings))
+                pending.push({
+                    kind: "frozen-body",
+                    file: f.utilsFile,
+                    helper: f.helper,
+                    line: 1,
+                    detail: `\`${f.helper}\` holds the body it sends to ${f.method} ${f.path}, and no parameter of its signature reaches it — so \`${f.rivalHelper}\` in ${path.basename(f.rivalFile)} could not call it and wrote the request again. Lift the body: a parameter defaulted to what the helper sends today, or the differing values through the override map, then delete \`${f.rivalHelper}\` and call the shared helper`,
+                });
+        }
+        catch {
+            /* never fails a verify on its own error */
         }
     }
+    const markers = new Map();
+    for (const a of allAllows) {
+        const k = `${a.kind}\0${a.helper}`;
+        markers.set(k, [...(markers.get(k) ?? []), a]);
+    }
+    for (const v of pending) {
+        const k = `${v.kind}\0${v.helper}`;
+        const held = carried.get(k);
+        if (held && held.length > 0) {
+            result.carriedConsumed.push(held.shift());
+            result.allowed.push(v);
+            continue;
+        }
+        const queue = markers.get(k);
+        if (queue && queue.length > 0) {
+            queue.shift();
+            result.allowed.push(v);
+        }
+        else if (v.kind === "scenario-name" || v.kind === "status-default") {
+            // `status-default` advises for now. The defaulted status was measured on 11 of
+            // 16 rows of one release and 12 of 16 on the one before, then ten more helpers
+            // across five repositories in the next cohort; blocking from day one would fail
+            // most of a cohort at once while the prompt side catches up. One cohort as an
+            // advisory measures whether the prompt rule landed; blocking is then this
+            // clause dropping the kind.
+            result.advisories.push(v);
+        }
+        else {
+            result.violations.push(v);
+        }
+    }
+    // Whatever no finding consumed is a marker that documents nothing: either it never
+    // applied, or the agent went on to fix the fault and left the line behind, so the
+    // file states a reason its own code contradicts. Nothing re-reads a marker once
+    // written, which is how such a line reached a customer's repository.
+    for (const queue of markers.values())
+        for (const a of queue)
+            result.violations.push({
+                kind: "stale-allow",
+                file: a.file,
+                helper: a.helper,
+                line: a.line,
+                detail: `this pass found no further \`${a.kind}\` for \`${a.helper}\`, so the decline describes nothing in the delivered files — delete the marker line`,
+            });
     result.ok =
         result.violations.length === 0 && result.malformedAllows.length === 0;
     // Integration only — the same gate as the prompt rule. `contract`, `load` and an
@@ -222,6 +653,15 @@ export async function verifyUtils(params) {
     }
     return result;
 }
+/** What to do about a restated status, by the shape of the helper that asserted it.
+ *  Stated here rather than inline so the gate note and this text stay one rule. */
+function remediation(helper, literal, incumbent) {
+    if (literal === undefined)
+        return "Delete the assertion; keep the status as the call's argument";
+    if (incumbent)
+        return `\`${helper}\` is defined at HEAD and keeps its signature, so the literal \`${literal}\` stays where it is — a status no caller can vary hides nothing. Just delete the assertion from the spec`;
+    return `\`${helper}\` pins the status inside the helper: lift the literal \`${literal}\` into a required expected-status parameter, pass it at every call site of \`${helper}\`, then delete the assertion`;
+}
 /** The compared counts as one phrase, shared by the assertion-loss detail and the
  *  PASSED line's note so the two cannot drift. */
 export function describeAssertionCount(c) {
@@ -363,7 +803,9 @@ export function importFormViolations(testFile, specContent, utilsFiles) {
 function blankTripleQuoted(src) {
     return src.replace(/("""|''')[\s\S]*?\1/g, (m) => m.replace(/[^\n]/g, " "));
 }
-function violationsIn(helpers, file, fallback, spec, seen, advisories) {
+function violationsIn(helpers, file, fallback, spec, seen, advisories, 
+/** Helpers defined at HEAD — not this run's, and outside the status rule's scope. */
+incumbents = new Set()) {
     const { byRoute, byName, byAction } = seen;
     // Names seen in THIS file: a second definition here is a redefinition, not drift.
     const inThisFile = new Map();
@@ -468,6 +910,36 @@ function violationsIn(helpers, file, fallback, spec, seen, advisories) {
                 });
             }
         }
+        // A wait for a duration rather than for a condition — one finding per helper, so
+        // a helper's timing reads as one note rather than one per call. The family decides
+        // only the REPLACEMENT named in the text: the fault is the same in both, and
+        // fixture 2's fifty-second polling helper was the API form of it. Advisory for its
+        // first cohort — see UTILS_ADVISORY_KINDS.
+        if (h.fixedSleeps.length > 0) {
+            advisories.push({
+                kind: "fixed-sleep",
+                file,
+                helper: h.name,
+                line: h.fixedSleeps[0].line,
+                detail: `${describeFixedSleeps(h.fixedSleeps)}. A shared helper's wait is inherited by every test that calls it and is invisible at the call site. ${fixedSleepReplacement(family.family, spec.language)}`,
+            });
+        }
+        // The parameter the status assertion reads carries a default: a call site may
+        // omit the status it expects, and the spec then states it nowhere. Helpers this
+        // run writes only — an incumbent keeps its signature, default included.
+        const defaulted = incumbents.has(h.name)
+            ? undefined
+            : defaultedStatusParam(h, spec);
+        if (defaulted) {
+            out.push({
+                kind: "status-default",
+                file,
+                helper: h.name,
+                line: h.line,
+                // The rule itself is stated once, in the advisory's footer.
+                detail: `\`${defaulted.param}\` lets a caller omit the status it expects — remove the default and pass the status at every call site of \`${h.name}\``,
+            });
+        }
         const naming = scenarioNameViolation(h.name);
         if (naming) {
             out.push({