@skyramp/mcp 0.4.1 → 0.4.2-rc.2

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

@@ -1,6 +1,8 @@
 import * as path from "path";
 import { allowMarkerLine, describeAssertionCount, MARKERABLE_UTILS_KINDS, HELPER_FAMILIES, } from "../../utils/utils-verify/index.js";
+import { describeActionKey } from "../../utils/utils-verify/action-key.js";
 import { utilsFileLabel } from "./reuse-state.js";
+import { STATUS_ONCE_RULE } from "../../prompts/shared-helper-policy.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
@@ -19,74 +21,173 @@ export function formatUtilsVerifyText(r, ctx = {}) {
     const tail = verdictTail(ctx) +
         unstagedTail(r, ctx) +
         namingAdvisory(r) +
-        typingAdvisory(r);
+        unresolvedImportsNote(r) +
+        statusDefaultAdvisory(r) +
+        typingAdvisory(r) +
+        typecheckAdvisory(r) +
+        moduleNameAdvisory(r) +
+        duplicateBodyReachAdvisory(r);
     const spec = r.spec;
-    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.)" +
+    if (r.utilsFiles.length === 0 && r.violations.length === 0 && !r.inHouse) {
+        // Two states, stated apart: the spec imports no sibling module, or it imports
+        // modules this pass read and does not check. "Nothing to verify" is only ever
+        // the first. (A module the pass could not recognise is a FAILED, below.)
+        const unchecked = r.uncheckedModules ?? [];
+        return ((unchecked.length > 0
+            ? `VERIFICATION PASSED — no Skyramp utils file; this test imports ${unchecked.length} module${unchecked.length === 1 ? "" : "s"} the pass read and does not check: ${unchecked
+                .map((f) => path.basename(f))
+                .join(", ")} — the repository's own, tracked without a Skyramp header. The in-house resolve and additive checks did not run: ${r.inHouseChecksSkipped ?? "they run for a UI test with page-object reuse off"}. Continue.`
+            : "VERIFICATION PASSED — no shared utils file is written or imported for this test; nothing to verify.") +
             tail +
             unextractedDuplicatesAdvisory(r));
     }
     const files = r.utilsFiles.map((f) => show(f, r)).join(", ");
+    if (r.ok && r.utilsFiles.length === 0) {
+        // In-house modules only: the spec calls the repository's own helpers and no
+        // Skyramp module. That is the outcome the extension exists for, not "nothing
+        // to verify".
+        return (`VERIFICATION PASSED — no Skyramp utils file; ${inHouseSummary(r)}` +
+            `${assertionCountNote(r)} Continue.` +
+            tail +
+            inHouseAdvisories(r));
+    }
     if (r.ok) {
         const allowed = r.allowed.length > 0
             ? ` ${r.allowed.length} documented decline${r.allowed.length === 1 ? "" : "s"}.`
             : "";
         return (`VERIFICATION PASSED — ${files}: ${r.helpers} helper${r.helpers === 1 ? "" : "s"}, ${r.imported} imported by this test.${allowed}` +
-            `${assertionCountNote(r)} ` +
-            `${ctx.staged && ctx.staged.length > 0 ? "The utils file is staged for the output commit. " : ""}Continue.` +
+            `${assertionCountNote(r)}${r.inHouse ? ` ${inHouseSummary(r)}` : ""}` +
+            `${ctx.staged && ctx.staged.length > 0 ? " The utils file is staged for the output commit." : ""} Continue.` +
             tail +
             inlineCallSitesAdvisory(r) +
             unextractedDuplicatesAdvisory(r) +
             duplicateActionAdvisory(r) +
+            fixedSleepAdvisory(r) +
+            inHouseAdvisories(r) +
             singleImporterAdvisory(r));
     }
     const lines = [];
     if (r.violations.length > 0) {
-        lines.push(`VERIFICATION FAILED — the shared utils file violates ${r.violations.length} invariant${r.violations.length === 1 ? "" : "s"}:`);
+        const inHouseOnly = r.violations.every((v) => v.kind.startsWith("in-house-"));
+        const unresolvedOnly = r.violations.every((v) => v.kind === "unresolved-module");
+        lines.push(unresolvedOnly
+            ? `VERIFICATION FAILED — ${r.violations.length} module${r.violations.length === 1 ? "" : "s"} this test imports could not be verified:`
+            : inHouseOnly
+                ? `VERIFICATION FAILED — ${r.violations.length} finding${r.violations.length === 1 ? "" : "s"} against the repository's own helper module${r.inHouse && r.inHouse.modules.length === 1 ? "" : "s"}:`
+                : r.utilsFiles.length === 0
+                    ? // Findings of more than one kind, and no Skyramp module: the heading
+                        // must not name a file this run never wrote.
+                        `VERIFICATION FAILED — ${r.violations.length} finding${r.violations.length === 1 ? "" : "s"} on this test and the modules it imports:`
+                    : `VERIFICATION FAILED — the shared utils file violates ${r.violations.length} invariant${r.violations.length === 1 ? "" : "s"}:`);
         for (const v of r.violations) {
             lines.push(`- ${v.kind} · ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`);
         }
-        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${ctx.embedded
+        // clause reads as a continuation of the api one for mixed files. An in-house-only
+        // failure names no utils file to fix — its remediation is the in-house paragraph
+        // below, and sending the agent to "the utils file" there had it create one.
+        // The utils-file remedy is offered only when there IS a utils file. A mix of
+        // kinds — one in-house finding beside an assertion-loss — is the pilot's
+        // ordinary shape once STEP 5b is skipped, and `every` sent it to a remedy that
+        // names a file the run never wrote.
+        const remediation = unresolvedOnly || inHouseOnly || r.utilsFiles.length === 0
+            ? "Fix each finding as its own line, and the paragraphs below, say"
+            : `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`;
+        lines.push("", `${remediation}${ctx.embedded
             ? "."
             : ", 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" &&
-            v.kind !== "helper-redefined");
+        // Read off MARKERABLE_UTILS_KINDS, which is the one declaration of that set and
+        // is what the allow grammar itself is built from — a kind added to the gate
+        // therefore defaults to NOT offering a marker, instead of silently joining the
+        // wrong side of a list of exceptions kept here.
+        const canMark = new Set(MARKERABLE_UTILS_KINDS);
+        const markerable = r.violations.filter((v) => canMark.has(v.kind));
         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)}`);
-            if (!ctx.embedded)
-                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.`);
         }
+        // The round bound is stated for EVERY blocking failure, not only where a marker
+        // is offered. A failure whose only violation takes no marker — a `type-error` —
+        // otherwise handed the agent a demand to fix with no terminal state at all.
+        if (!ctx.embedded)
+            lines.push(markerable.length > 0
+                ? `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.`
+                : `Do not spend more than ${UTILS_VERIFY_MAX_ROUNDS} verify rounds on this file: none of these violations can be documented, so if one remains after round ${UTILS_VERIFY_MAX_ROUNDS}, stop and report it in your submission rather than verifying again.`);
         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 === "status-restated"))
+            lines.push("A `status-restated` finding is about the TEST file: the helper already asserts the status. When the helper takes the status as a parameter, delete the spec's status assertion on the response that call returned and keep the status as the call's argument; nothing in the utils file changes. When a helper THIS RUN WROTE pins a literal, first lift that literal into a required expected-status parameter and pass it at every call site, then delete the spec's assertion. When the helper is defined at HEAD, its signature is frozen (see `incumbent-signature` below) — leave the literal alone and only delete the spec's assertion. The finding's own text says which.");
         if (r.violations.some((v) => v.kind === "helper-redefined"))
             lines.push("A helper defined twice in one file cannot be documented away — the module does not load (TypeScript) or the second definition silently replaces the first (Python). Keep ONE definition, give every parameter the other had a default, update the call sites, then re-verify.");
+        if (r.violations.some((v) => v.kind === "stale-allow"))
+            lines.push("A `stale-allow` finding is about the marker line itself, not about a helper: the decline it states is not in the delivered files, so delete that line. Do not document it — a second marker would be stale in the same way.");
+        if (r.violations.some((v) => v.kind === "incumbent-signature"))
+            lines.push("An `incumbent-signature` finding cannot be documented away — a helper defined at HEAD keeps its parameter list, its defaults included, because callers this run cannot see depend on it. Restore the signature as it was at HEAD; add what you need as a new parameter with a default or as a new helper; then re-verify.");
         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.violations.some((v) => v.kind === "unresolved-module"))
+            lines.push("An `unresolved-module` finding is about a module this TEST IMPORTS that the pass could not recognise — not about a utils-file invariant. Its line names the one thing to do: make the module's first line the exact `// Generated by Skyramp on <timestamp>` header shown (the `on <timestamp>` part is required — a bare `Generated by Skyramp` is what every generated test carries and is not a module header), or fix an import that resolves to no file. Then re-verify. Until then the pass cannot verify or stage the module and skyramp_execute_test refuses this test. No marker documents it.");
+        if (r.violations.some((v) => v.kind.startsWith("in-house-")))
+            lines.push("An `in-house-…` finding is about the repository's OWN helper module, which this run may only ADD to: `in-house-unresolved` and `in-house-arity` are fixed in the TEST (call a helper the module defines, with an argument count its signature accepts) or by adding a helper or a defaulted parameter to the module; `in-house-modified` is fixed by restoring the existing helper or line exactly as it was at HEAD (`git diff HEAD -- <module>` shows the change) and putting what you needed in a new helper or a new defaulted parameter. Never write a `reuse-verify` marker or a Skyramp header into that file — it is the customer's.");
+        if (r.violations.some((v) => v.kind === "type-error"))
+            lines.push("A `type-error` cannot be documented away — it was found with every strictness flag OFF, so it fails under every compiler configuration and the customer's own `tsc` is the next thing to report it (the executor transpiles without typechecking, which is why the tests still ran). Fix the type at the line named — a parameter typed by what the SDK call accepts (never `unknown` or `any`), request options as ONE object literal passed straight to `sendRequest` (never a `Record<string, unknown>` filled in afterwards) — 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 ${MARKERABLE_UTILS_KINDS.join(" / ")}, 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>\` on a LINE OF ITS OWN, with nothing before it and nothing after it, 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) +
         unextractedDuplicatesAdvisory(r) +
         duplicateActionAdvisory(r) +
+        fixedSleepAdvisory(r) +
+        inHouseAdvisories(r) +
         singleImporterAdvisory(r));
 }
+/** What the in-house checks read and established, on a PASSED: which of the
+ *  repository's own modules the spec calls, how many calls resolved, what this run
+ *  added to or widened in them, and whether the additive gate ran — stated, because
+ *  a gate that could not run must never read as one that found nothing. */
+function inHouseSummary(r) {
+    const h = r.inHouse;
+    const mods = h.modules.map((m) => path.basename(m)).join(", ");
+    const parts = [
+        `${h.modules.length} in-house module${h.modules.length === 1 ? "" : "s"} (${mods}): ${h.resolved.length} imported helper${h.resolved.length === 1 ? "" : "s"} resolved`,
+    ];
+    if (h.unverifiable.length > 0)
+        parts.push(`${h.unverifiable.length} import${h.unverifiable.length === 1 ? "" : "s"} not readable as a helper (${h.unverifiable.join(", ")}) — a class, a re-export or a constant; not checked`);
+    if (h.added.length > 0)
+        parts.push(`${h.added.length} helper${h.added.length === 1 ? "" : "s"} added by this run (${h.added.map((a) => a.helper).join(", ")})`);
+    if (h.widened.length > 0)
+        parts.push(`${h.widened.length} widened with a defaulted parameter (${h.widened.map((a) => a.helper).join(", ")})`);
+    parts.push(h.additiveGateRan
+        ? "additive gate ran"
+        : "additive gate DID NOT RUN (HEAD's copy of a module could not be read) — say so in the report; nothing here confirms the module was changed additively");
+    return parts.join("; ") + ".";
+}
+/** A helper this run added to the customer's module that repeats one it already
+ *  held. Advisory, like `duplicate-action`, and for the same reason. */
+function inHouseAdvisories(r) {
+    const dups = r.advisories.filter((v) => v.kind === "in-house-duplicate");
+    if (dups.length === 0)
+        return "";
+    const n = dups.length;
+    return [
+        "",
+        "",
+        `ADVISORY — ${n} helper${n === 1 ? "" : "s"} this run added to an in-house module repeat${n === 1 ? "s" : ""} an action sequence that module already holds (does not block):`,
+        ...dups.map((v) => `- ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`),
+        "Putting the duplicate inside the customer's file is worse than beside it. Call the existing helper instead and delete the one you added; if a value differs, lift it into a defaulted parameter of the existing helper. Then re-verify. Advisory only: do NOT write a `reuse-verify` marker for it.",
+    ].join("\n");
+}
 /** A PASSED that ran the baseline assertion check says what that check measured. It
  *  is a count: a swapped assertion (one removed, one added) holds the count, so the
  *  line names the pass that compares subjects rather than letting "PASSED" claim it.
@@ -118,6 +219,9 @@ function moduleLabel(r) {
         ? utilsFileLabel(r.utilsFiles)
         : "the shared utils file";
 }
+/** The half of the sibling call-site advisory both families share: a site inside
+ *  the sibling's own helper, the execution owed, and that nothing blocks. */
+const inlineSiteTail = (localCopy) => `For a site in a local helper, replace ${localCopy} inside the local helper with a call to the shared helper and keep the local helper's other statements; delete the local helper only if it then does nothing but forward, moving the import and the differing literals to its call sites. 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.`;
 /** 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
  *  reaches. Advisory — the sibling is a pre-existing test the maintenance flow owns, so
@@ -130,12 +234,22 @@ function inlineCallSitesAdvisory(r) {
     const labels = new Map(r.utilsFiles.map((f) => [f, utilsFileLabel([f])]));
     const labelOf = (f) => labels.get(f) ?? utilsFileLabel([f]);
     const n = r.inlineCallSites.length;
+    // One family per pass: the sites' kind decides the family half of the text.
+    const family = r.inlineCallSites[0].kind === "sequence"
+        ? HELPER_FAMILIES.browser
+        : HELPER_FAMILIES.api;
+    const lines = (c) => c.kind === "sequence" && c.endLine !== c.line
+        ? `${c.line}-${c.endLine}`
+        : `${c.line}`;
+    const what = (c) => c.kind === "sequence"
+        ? describeActionKey(c.actionKey)
+        : `${c.method} ${c.path}`;
     return [
         "",
         "",
-        `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.localHelper ? ` (in local helper ${c.localHelper})` : ""} · ${c.method} ${c.path} · ${labelOf(c.utilsFile)}.${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). For a site in a local helper, replace that request inside the local helper with a call to the shared helper and keep the local helper's other statements; delete the local helper only if it then does nothing but forward, moving the import and the differing literals to its call sites. 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.`,
+        `ADVISORY — ${n} ${family.inlineSite.noun}${n === 1 ? "" : "s"} in other Skyramp-generated tests that a shared helper already ${family.inlineSite.already}:`,
+        ...r.inlineCallSites.map((c) => `- ${show(c.file, r)}:${lines(c)}${c.localHelper ? ` (in local helper ${c.localHelper})` : ""} · ${what(c)} · ${labelOf(c.utilsFile)}.${c.helper}`),
+        `${family.inlineSite.instruction} ${inlineSiteTail(family.inlineSite.localCopy)}`,
     ].join("\n");
 }
 /** Operations written in two or more sibling generated tests with no shared helper —
@@ -183,11 +297,34 @@ function singleImporterAdvisory(r) {
     return lines.join("\n");
 }
 function unstagedTail(r, ctx) {
-    if (!ctx.unstaged || ctx.unstaged.length === 0)
+    let out = "";
+    if (ctx.unstaged && ctx.unstaged.length > 0)
+        out +=
+            `\n\nVERIFICATION FAILED — ${ctx.unstaged.length === 1 ? "this utils file" : "these utils files"} could not be staged for the output commit: ` +
+                ctx.unstaged.map((f) => show(f, r)).join(", ") +
+                `. The tests importing it will fail for everyone else. Usually the file is gitignored (check \`git check-ignore -v <path>\`) or lies outside the repository; fix that (move the file, or un-ignore it) and re-verify.`;
+    if (ctx.unstagedInHouse && ctx.unstagedInHouse.length > 0)
+        out +=
+            `\n\nVERIFICATION FAILED — the repository's own module${ctx.unstagedInHouse.length === 1 ? "" : "s"} this run added to could not be staged for the output commit: ` +
+                ctx.unstagedInHouse.map((f) => path.basename(f)).join(", ") +
+                `. The helper you added will not reach the pull request, and the test importing it will fail for everyone else. Read the staging error (\`git add -- <path>\`; \`git check-ignore -v <path>\`) and resolve it if it is this run's doing, then re-verify. Do not move, rename or un-ignore the customer's module: if it cannot be staged as it is, restore it to HEAD, leave the step inline, and say so in the report.`;
+    return out;
+}
+/** Specifiers this pass could not resolve. Stated, never blocked on: the resolver
+ *  knows a fixed set of module extensions and an index file, and the customer's
+ *  toolchain knows more. The wording says what this PASS did not do, never that the
+ *  file is absent. */
+function unresolvedImportsNote(r) {
+    const list = r.unresolvedImports ?? [];
+    if (list.length === 0)
         return "";
-    return (`\n\nVERIFICATION FAILED — ${ctx.unstaged.length === 1 ? "this utils file" : "these utils files"} could not be staged for the output commit: ` +
-        ctx.unstaged.map((f) => show(f, r)).join(", ") +
-        `. The tests importing it will fail for everyone else. Usually the file is gitignored (check \`git check-ignore -v <path>\`) or lies outside the repository; fix that (move the file, or un-ignore it) and re-verify.`);
+    const n = list.length;
+    return [
+        "",
+        "",
+        `NOTE — ${n} relative import${n === 1 ? "" : "s"} could not be resolved by this pass, so ${n === 1 ? "it was" : "they were"} neither checked nor staged: ${list.map((i) => `\`${i}\``).join(", ")}.`,
+        "This pass tries a fixed set of module extensions and an index file; your toolchain may resolve more (a component file, a data file, a path alias). If the file is there, nothing is wrong — continue. If one of these is a helper module this run wrote, give it the standard header so the pass can check and stage it.",
+    ].join("\n");
 }
 /** Naming is advised, never enforced: a heuristic that blocked execution on
  *  `create_test_case` or `list_expired_subscriptions` would be the worse outcome. */
@@ -204,21 +341,74 @@ function namingAdvisory(r) {
         "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. */
+/** A defaulted expected-status parameter. Advises for now — measured on most rows
+ *  of every cohort so far, so blocking would fail a whole cohort while the prompt
+ *  rule catches up; the verify pass routes the kind to `advisories` and this is
+ *  where it is shown. The remediation touches every call site, which is why it
+ *  names the re-execution rule for pre-existing tests. */
+function statusDefaultAdvisory(r) {
+    const defaulted = r.advisories.filter((v) => v.kind === "status-default");
+    if (defaulted.length === 0)
+        return "";
+    const n = defaulted.length;
+    return [
+        "",
+        "",
+        `ADVISORY — ${n} shared helper${n === 1 ? "" : "s"} default${n === 1 ? "s" : ""} the status its caller expects (does not block):`,
+        ...defaulted.map((v) => `- ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`),
+        // The rule, verbatim from the policy the prompt renders: one string, so the
+        // finding and the requirement cannot read as describing different helpers.
+        `Each helper above is one this run wrote. ${STATUS_ONCE_RULE.noDefault} A pre-existing test whose call site changed must be run with skyramp_execute_test. Advisory only: it never blocks, and continue without re-verifying.`,
+    ].join("\n");
+}
+/** TypeScript only. A static reading of the signature: whether an unannotated
+ *  parameter breaks the customer's build depends on their tsconfig reaching the tests
+ *  directory, and `any` breaks nothing, so this advises and never blocks. An `unknown`
+ *  parameter fails at its first use under every setting — that failure is the
+ *  compiler's to report, as a blocking `type-error`; this note names the cause. */
 function typingAdvisory(r) {
-    const typed = r.advisories.filter((v) => v.kind === "untyped-parameter");
+    const typed = r.advisories.filter((v) => v.kind === "unusable-parameter-type");
     if (typed.length === 0)
         return "";
     const n = typed.length;
     return [
         "",
         "",
-        `ADVISORY — ${n} helper${n === 1 ? " has" : "s have"} untyped parameters (does not block):`,
+        `ADVISORY — ${n} helper${n === 1 ? " has" : "s have"} parameters without a usable type (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.",
+        "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 the type the SDK call accepts (`client: SkyrampClient`, `headers: Record<string, string>`, a path parameter as `string | number`); never `any` or `unknown` — `unknown` is assignable to nothing but itself, so passing it to the request fails the customer's typecheck. Advisory only: continue without re-verifying, and do NOT write a `reuse-verify` marker for it.",
     ].join("\n");
 }
+/** What the compiler run over the delivered files has to add beyond its blocking
+ *  `type-error`s: errors only the repository's tsconfig raises (advised — whether that
+ *  tsconfig is the one their build runs is the customer's call), and the two ways
+ *  the run could fall short — it did not run at all, or an import resolved from
+ *  neither the repository nor the MCP's install, so what that module types went
+ *  unchecked. Both are stated, because a PASSED that says nothing reads as a clean
+ *  compile. Nothing for Python and JavaScript, where `typecheck` is absent. */
+function typecheckAdvisory(r) {
+    const tc = r.typecheck;
+    if (!tc)
+        return "";
+    const lines = [];
+    if (!tc.ran)
+        lines.push("", "", `NOTE — the delivered files were NOT typechecked (${tc.reason ?? "unknown cause"}); only the static shape rules ran, so a type error can still reach the customer's own \`tsc\`. Read the signatures yourself: every parameter typed by what the SDK call accepts, the request options one object literal.`);
+    else if (tc.unresolved.length > 0)
+        lines.push("", "", `NOTE — the typecheck could not resolve ${tc.unresolved.map((m) => `\`${m}\``).join(", ")} from the repository or from the MCP's own install, so whatever those modules type was not checked. If a delivered file imports one of them, confirm the import path and that the package is installed in the repository.`);
+    const ambient = r.advisories.filter((v) => v.kind === "ambient-type-error");
+    if (ambient.length > 0) {
+        const n = ambient.length;
+        lines.push("", "", `ADVISORY — ${n} name${n === 1 ? "" : "s"} the compiler could not find (does not block):`, ...ambient.map((v) => `- ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`), "Each is a global (`process`, a test runner's `describe`, `Promise`) whose declarations come from a package the repository installs (`@types/node`, the runner's types) or from its `lib` setting. This run cannot see the repository's installed packages, so it cannot tell whether the name exists there; the repository's own `tsc` decides. Do NOT rewrite the code to dodge this note — never a `globalThis` cast or a hand-written declaration; a `process.env` read is the generated form and stays as it is. Advisory only: continue without re-verifying, and do NOT write a `reuse-verify` marker for it.");
+    }
+    else if (tc.tsconfigNotReaching)
+        lines.push("", "", `NOTE — the nearest tsconfig (${tc.tsconfigNotReaching}) does not include the delivered files, and nor does any project it references, so nothing was checked under the repository's own settings. The errors above are the ones that hold under every configuration. If this repository type-checks its tests, add them to that config's \`include\`.`);
+    const settings = r.advisories.filter((v) => v.kind === "tsconfig-type-error");
+    if (settings.length > 0) {
+        const n = settings.length;
+        lines.push("", "", `ADVISORY — ${n} error${n === 1 ? "" : "s"} under the repository's own tsconfig (${tc.tsconfig ?? "tsconfig.json"}) (does not block):`, ...settings.map((v) => `- ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`), "These compile with the strictness flags off and fail only under that tsconfig's settings (`noImplicitAny`, `strictNullChecks`, …). It includes the delivered files, so if the repository's build runs it, these are the errors it will report — fix them the same way as a type-error. Advisory only: continue without re-verifying, and do NOT write a `reuse-verify` marker for it.");
+    }
+    return lines.join("\n");
+}
 /** Browser helpers whose Playwright action sequences agree — one operation under two
  *  names, the drift a second run compounds. Rendered beside the other
  *  duplicate-detection advisories (inline call sites, un-extracted duplicates), after
@@ -238,6 +428,55 @@ function duplicateActionAdvisory(r) {
         "Two names for one action is how a shared module drifts on every later run. Keep ONE helper per action sequence, named for the user intent; lift the values that differ (a filled text, a quantity) into defaulted parameters; update the call sites and delete the other. Skip only if the two act on genuinely different elements. If you edit the utils file or a call site, re-verify; a pre-existing test whose call site changed must also be run with skyramp_execute_test. Advisory only: it never blocks, and do NOT write a `reuse-verify` marker for it.",
     ].join("\n");
 }
+/** A shared helper that waits for a DURATION — a `waitForTimeout`, a `time.sleep`, a
+ *  promise-wrapped `setTimeout`, or one of those as a retry loop's backoff. Every test
+ *  importing the helper pays it and the call site cannot see it. Advisory for its
+ *  first cohort: the predicate is lexical over two languages, and review found three
+ *  shapes it read wrongly, so the false-hit rate is measured before it blocks. */
+function fixedSleepAdvisory(r) {
+    const sleeps = r.advisories.filter((v) => v.kind === "fixed-sleep");
+    if (sleeps.length === 0)
+        return "";
+    const n = sleeps.length;
+    return [
+        "",
+        "",
+        `ADVISORY — ${n} shared helper${n === 1 ? "" : "s"} wait${n === 1 ? "s" : ""} for a fixed DURATION rather than for a condition (does not block):`,
+        ...sleeps.map((v) => `- ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`),
+        "A wait written into a shared helper is inherited by every test that imports it, is paid on every run, and is invisible at the call site — and where it is a retry loop's backoff, an iteration count hides what it really costs. Advisory only: it never blocks, and do NOT write a `reuse-verify` marker for it.",
+    ].join("\n");
+}
+/** The module the run created did not take the name its language prescribes, so a
+ *  later run finds nothing and writes a second module beside it. Advisory for its
+ *  first cohort: the prompt states the rule, and what this adds now is a count. */
+function moduleNameAdvisory(r) {
+    const named = r.advisories.filter((v) => v.kind === "module-name");
+    if (named.length === 0)
+        return "";
+    const n = named.length;
+    return [
+        "",
+        "",
+        `ADVISORY — ${n} shared module${n === 1 ? "" : "s"} this run created ${n === 1 ? "does" : "do"} not carry the prescribed name (does not block):`,
+        ...named.map((v) => `- ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`),
+        "Rename the file and fix the imports in the tests this run wrote; nothing inside the module changes. A module that already existed keeps the name it has — never rename one you did not create. Advisory only: it never blocks, and do NOT write a `reuse-verify` marker for it.",
+    ].join("\n");
+}
+/** One request body reached through two parameters. Advisory for its first cohort,
+ *  for the reason recorded in UTILS_ADVISORY_KINDS. */
+function duplicateBodyReachAdvisory(r) {
+    const found = r.advisories.filter((v) => v.kind === "duplicate-body-reach");
+    if (found.length === 0)
+        return "";
+    const n = found.length;
+    return [
+        "",
+        "",
+        `ADVISORY — ${n} helper${n === 1 ? "" : "s"} reach${n === 1 ? "es" : ""} the request body through two parameters (does not block):`,
+        ...found.map((v) => `- ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`),
+        "Keep ONE of the two — the body parameter, or the override — delete the other from the signature and from the request call, and update the call sites. Which one to keep is the body-shape rule's question: the override where every caller changes only values the generated body already carries, the body parameter where one does not. If you edit the utils file or a call site, re-verify. Advisory only: it never blocks, and do NOT write a `reuse-verify` marker for it.",
+    ].join("\n");
+}
 function verdictTail(ctx) {
     if (ctx.recorded !== false)
         return "";

package/build/tools/code-refactor/verify-gates.d.ts

@@ -36,7 +36,21 @@ export declare function infraGateFailure(params: VerifyTarget, r: VerifyResult):
  * was skipped, not unavailable. Returns undefined when the gate doesn't apply or doesn't fire;
  * scoping errors (or a legitimately POM-less repo, tier1 === []) also return undefined: this gate
  * must never turn an infra error into a false compliance failure. */
-export declare function zeroReuseGateFailure(params: VerifyTarget, r: VerifyResult): Promise<string | undefined>;
+export declare function zeroReuseGateFailure(params: VerifyTarget, r: VerifyResult, 
+/** Candidate file names this run documented in the spec and then removed from it
+ *  before delivery. Read exactly like a marker still in the spec — see
+ *  stripDeliveredGateMarkers. Per RUN only. */
+carriedKeptInline?: string[], 
+/** Filled with what this gate DID. `ran` says the candidate walk happened, so a
+ *  carried decline missing from `covered` is missing for want of a FAULT rather than
+ *  for want of a reading — the only state on which a caller may retire it. The gate
+ *  declines to judge on several paths (the target is not POM-aware, the result is
+ *  not clean-but-empty, discovery fell back to selector-grep, the scoping threw) and
+ *  each leaves `covered` empty while classifying nothing. */
+classification?: {
+    covered: Set<string>;
+    ran: boolean;
+}): Promise<string | undefined>;
 /** Composes the verify response text from an (optional) fired gate and the verification result.
  * When a gate fires on a spec that also has mapping violations, the normal report is appended so
  * both are actionable in one pass — the zero-reuse gate only fires on clean results, so the

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

@@ -24,7 +24,7 @@ export function formatVerifyReport(r) {
     if (r.parseError) {
         lines.push(`Parse error (fix the syntax and re-verify): ${r.parseError}`);
     }
-    lines.push("Each violation may be remapped AT MOST ONCE, and only to a member listed above. If it is flagged again, or you are not confident, restore the raw inline sequence (from your mapping table or `<testFile>.raw.bak`) with a `// kept inline: <POM file basename> — no matching POM method` comment naming the file you demoted from. Re-run this verification after every fix pass. Do not finish until it reports PASSED.");
+    lines.push("Each violation may be remapped AT MOST ONCE, and only to a member listed above. If it is flagged again, or you are not confident, restore the raw inline sequence (from your mapping table or `<testFile>.raw.bak`) and put a `// kept inline: <POM file basename> — no matching POM method` comment naming the file you demoted from ON A LINE OF ITS OWN above it, with nothing before it and nothing after it. Re-run this verification after every fix pass. Do not finish until it reports PASSED.");
     return lines.join("\n\n");
 }
 /** Renders the infrastructure-gate failure: a POM-aware spec whose Skyramp runtime imports
@@ -63,7 +63,7 @@ function malformedMarkerLines(unparsable) {
     return [
         "Also fix these `kept inline:` lines — they satisfy this gate but the report cannot read them, so their declines would be dropped silently:",
         ...unparsable.map((line) => `    ${line}`),
-        "The reason must be separated by an em dash, or by a hyphen with a space on BOTH sides: `// kept inline: <file basename> — <reason>`.",
+        "Write each one on a LINE OF ITS OWN, with nothing before it and nothing after it, and separate the reason with an em dash or with a hyphen that has a space on BOTH sides: `// kept inline: <file basename> — <reason>`.",
     ];
 }
 /** Renders the malformed-marker failure on its own — every candidate is documented, so the
@@ -154,7 +154,21 @@ export async function infraGateFailure(params, r) {
  * was skipped, not unavailable. Returns undefined when the gate doesn't apply or doesn't fire;
  * scoping errors (or a legitimately POM-less repo, tier1 === []) also return undefined: this gate
  * must never turn an infra error into a false compliance failure. */
-export async function zeroReuseGateFailure(params, r) {
+export async function zeroReuseGateFailure(params, r, 
+/** Candidate file names this run documented in the spec and then removed from it
+ *  before delivery. Read exactly like a marker still in the spec — see
+ *  stripDeliveredGateMarkers. Per RUN only. */
+carriedKeptInline = [], 
+/** Filled with what this gate DID. `ran` says the candidate walk happened, so a
+ *  carried decline missing from `covered` is missing for want of a FAULT rather than
+ *  for want of a reading — the only state on which a caller may retire it. The gate
+ *  declines to judge on several paths (the target is not POM-aware, the result is
+ *  not clean-but-empty, discovery fell back to selector-grep, the scoping threw) and
+ *  each leaves `covered` empty while classifying nothing. */
+classification = {
+    covered: new Set(),
+    ran: false,
+}) {
     if (!isCleanButEmpty(r) ||
         !isPomAwareTarget(params.language, params.framework, params.testType))
         return undefined;
@@ -168,8 +182,26 @@ export async function zeroReuseGateFailure(params, r) {
         // discovery fallback also matches ordinary in-repo frontend source (app components
         // legitimately contain the spec's test-ids by construction), which is not evidence of
         // skipped reuse in a POM-less repo.
+        // An empty `tier1` is an ANSWER: the walk ran and found no candidate, so a carried
+        // decline covers nothing. Only the selector-grep fallback leaves this unjudged.
+        if (diagnostics.discovery === "globs")
+            classification.ran = true;
         if (diagnostics.discovery === "globs" && tier1.length > 0) {
-            const undocumented = tier1.filter((p) => !isKeptInlineDocumented(specContent, p.file));
+            // `isKeptInlineDocumented` accepts the STEM as well as the basename, so a
+            // decline carried from `// kept inline: loginPage — …` is the string
+            // `loginPage` while the candidate is `loginPage.js`. Both spellings are
+            // compared, and whichever one the decline used is what is recorded as covered.
+            const carried = new Set(carriedKeptInline);
+            const undocumented = tier1.filter((p) => {
+                if (isKeptInlineDocumented(specContent, p.file))
+                    return false;
+                const base = path.basename(p.file);
+                const spelling = [base, base.replace(/\.[^.]+$/, "")].find((n) => carried.has(n));
+                if (spelling === undefined)
+                    return true;
+                classification.covered.add(spelling);
+                return false;
+            });
             // A marker this gate accepts but `parseKeptInline` cannot read clears the escape
             // hatch while its decline never reaches the report — the silent loss this feature
             // exists to close. Caught here rather than only logged at report time: the agent is

package/build/tools/enrichTestWithMocksTool.d.ts

@@ -25,4 +25,4 @@ type MockEntry = {
     protocol: MockProtocol;
 };
 declare function buildMockImportBlock(testFile: string, scenarioName: string, mockFiles: string[], traceComments?: string[], language?: ProgrammingLanguage, mockEntries?: MockEntry[]): string;
-export { injectMockImports, buildMockImportBlock, isSupportedMockEnrichmentLanguage };
+export { injectMockImports, buildMockImportBlock, isSupportedMockEnrichmentLanguage, };

package/build/tools/enrichTestWithMocksTool.js

@@ -196,7 +196,9 @@ function buildMockEntries(testFile, mockFiles, language) {
     });
 }
 function buildImportPath(relativePath, language) {
-    const normalized = relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+    const normalized = relativePath.startsWith(".")
+        ? relativePath
+        : `./${relativePath}`;
     if (language === ProgrammingLanguage.TYPESCRIPT) {
         return normalized.replace(/\.(ts|tsx|js|jsx)$/i, "");
     }
@@ -231,7 +233,7 @@ function prepareMockFileForLanguageImport(mockFile, relativePath, language, clas
 function disableNodeMockAutoApply(source) {
     if (source.includes("skyramp-enrich disabled auto-apply"))
         return source;
-    return source.replace(/\nmain\(\)\.catch\(\s*\(?\s*\w+\s*\)?\s*=>\s*\{[\s\S]*?\n\}\);\s*$/, '\n// skyramp-enrich disabled auto-apply: imported integration tests call getAllMocks() directly.\n');
+    return source.replace(/\nmain\(\)\.catch\(\s*\(?\s*\w+\s*\)?\s*=>\s*\{[\s\S]*?\n\}\);\s*$/, "\n// skyramp-enrich disabled auto-apply: imported integration tests call getAllMocks() directly.\n");
 }
 function replaceGeneratedMockBlock(source, generatedBlock) {
     const existingBlockRange = findGeneratedMockBlockRange(source);
@@ -261,9 +263,11 @@ function findTopLevelBlockInsertionIndex(lines, language) {
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i].trim();
         const isImportLine = language === ProgrammingLanguage.PYTHON
-            ? line.startsWith("import ") || line.startsWith("from ") || line.startsWith("# Import")
+            ? line.startsWith("import ") ||
+                line.startsWith("from ") ||
+                line.startsWith("# Import")
             : line.startsWith("import ") ||
-                line.startsWith("const ") && line.includes("require(") ||
+                (line.startsWith("const ") && line.includes("require(")) ||
                 line.startsWith("// Import");
         if (isImportLine ||
             (line === "" &&
@@ -723,4 +727,4 @@ function normalizeMockCommandTarget(target) {
     return /^[A-Za-z0-9_.-]+:\d+$/.test(target) ? target : undefined;
 }
 // Exported for testing
-export { injectMockImports, buildMockImportBlock, isSupportedMockEnrichmentLanguage };
+export { injectMockImports, buildMockImportBlock, isSupportedMockEnrichmentLanguage, };