@skyramp/mcp 0.4.0 → 0.4.1-rc.2

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

@@ -10,9 +10,12 @@ import { verifyReuse, } from "../../utils/pom-verify/index.js";
 import { buildSkipped, findUnparsableKeptInline, flaggedFrom, mergeFlagged, verificationFrom, ReuseVerificationOutcome, HelperVerificationOutcome, } from "./reuse-outcome.js";
 import { verifyUtils, realpath, utilsSpecFor, countAssertions, hasPageErrorGuard, utilsSpecForFile, } from "../../utils/utils-verify/index.js";
 import { detectGitRoot } from "../../utils/gitStaging.js";
+import { formatUtilsVerifyText } from "./utils-verify-gates.js";
+import { composeVerifyText, infraGateFailure, zeroReuseGateFailure, } from "./verify-gates.js";
 const execFileAsync = promisify(execFile);
 import { resolvePomCatalogPath } from "../../utils/pom-catalog.js";
 import { parsePomCatalog, findMissedReuse, } from "../../utils/pom-catalog-parse.js";
+import { ProgrammingLanguage } from "../../types/TestTypes.js";
 /**
  * Persistence for the server-derived POM-reuse outcome, keyed by test-file
  * basename (what `newTestsCreated[].fileName` carries, so
@@ -75,7 +78,7 @@ async function readReuseRecord(testFile, explicitStateFile) {
  *
  * The identity is written here and not only by {@link recordVerifyOutcome} because
  * the verify pass is a call the agent decides whether to make. When it skips it,
- * a record holding the candidate count alone makes `rederiveReuseOutcome` bail out,
+ * a record holding the candidate count alone makes `rederiveReuse` bail out,
  * and the report states "N candidate POM files detected" with no reuse numbers —
  * indistinguishable from a run where reuse was measured and simply not summarized.
  * Recording it unconditionally is what makes the zero-reuse case reportable without
@@ -139,9 +142,11 @@ export async function recordVerifyOutcome(testFile, r, gateFired, language, expl
  * NOT terminal. A PASS is always reachable in one edit plus one call (substitute the
  * members, or document each candidate with a `// kept inline:` marker, which the gate
  * accepts), and an agent that resolves neither can still walk past these tools to
- * `skyramp_submit_report`, which does not block and reports the honest zero. So the
- * worst case degrades to the reporting half rather than to a run that produces
- * nothing — which is what a bound would have been protecting against.
+ * `skyramp_submit_report`. That tool refuses a blocking verdict on the delivered
+ * files too, but its refusal is BOUNDED (`REUSE_SUBMIT_MAX_REFUSALS`): past the bound
+ * it accepts the report with the fault recorded in the row. So the worst case still
+ * degrades to the reporting half rather than to a run that produces nothing — which
+ * is what a bound here would have been protecting against.
  */
 export async function pendingReuseVerification(testFile, explicitStateFile) {
     try {
@@ -246,9 +251,33 @@ export function samePath(a, b) {
 export function canonPath(p) {
     return canon(p);
 }
-/** The basename label a report row shows for a set of utils files. */
+/**
+ * The label a report row shows for a set of utils files: each file's path relative
+ * to its repository root, posix-separated, joined with `, `.
+ *
+ * Repository-relative, never absolute — an absolute path carries the runner's
+ * temporary directory and means nothing to a customer. Not a basename either: a
+ * fullstack delivery writes one module per test directory under the same
+ * conventional name, and two rows labelled `skyrampUtils.ts` cannot be told apart
+ * (a renderer keyed on the label then merges them into one aggregate). Outside a
+ * repository, or for a file the root does not contain, the basename stands in.
+ */
 export function utilsFileLabel(files) {
-    return files.map((f) => path.basename(f)).join(", ");
+    return files.map(repoRelativeLabel).join(", ");
+}
+function repoRelativeLabel(file) {
+    const root = detectGitRoot(file);
+    if (!root)
+        return path.basename(file);
+    // Both sides canonical: git reports the REAL root, and a path through a symlink
+    // (macOS /tmp → /private/tmp) would otherwise relativise to `../../…`.
+    const rel = path.relative(canon(root), canon(file));
+    // Outside the root means a leading `..` SEGMENT — not any name starting with two
+    // dots (`..generated/SkyrampUtils.py` is a valid in-repository path).
+    const outside = rel === ".." || rel.startsWith(`..${path.sep}`);
+    if (!rel || outside || path.isAbsolute(rel))
+        return path.basename(file);
+    return rel.split(path.sep).join("/");
 }
 function canon(p) {
     try {
@@ -261,11 +290,15 @@ function canon(p) {
 /** 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 async function recordUtilsVerifyOutcome(testFile, r, language, framework, testType, explicitStateFile) {
-    const verification = r.utilsFiles.length === 0
-        ? HelperVerificationOutcome.NoUtilsFile
-        : r.ok
-            ? HelperVerificationOutcome.Passed
-            : HelperVerificationOutcome.Failed;
+    // `ok` first: a baseline violation is a failed verify with or without a module
+    // beside the spec (the live text says FAILED), and recording NoUtilsFile there
+    // cleared the debt, let execution proceed, and left the fault to be refused first
+    // at submit — the recorded verdict was a stale positive.
+    const verification = !r.ok
+        ? HelperVerificationOutcome.Failed
+        : r.utilsFiles.length === 0
+            ? HelperVerificationOutcome.NoUtilsFile
+            : HelperVerificationOutcome.Passed;
     return updateReuseOutcome(testFile, (existing) => {
         const mine = owns(existing, testFile);
         const prior = mine ? existing.utils : undefined;
@@ -306,7 +339,9 @@ 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;
+    // The spec as it stands at the modularization call, before any code moves. For UI
+    // that is after the enhancer (enhance → modularize); for integration it is before
+    // it (modularize → reuse → verify → enhance), i.e. the generated spec. Taken once;
     // a second modularization call must not overwrite the true "before".
     let baseline;
     const spec = utilsSpecForFile(testFile);
@@ -626,40 +661,127 @@ function reuseRan(record) {
         record.candidatesDetected !== undefined ||
         record.verification !== undefined);
 }
+/**
+ * How many times skyramp_submit_report refuses a report over one spec's blocking
+ * verdict before accepting it with the fault recorded in the row.
+ *
+ * The refusal is a repair loop, and a repair loop at the last step of a run needs a
+ * terminal state (SKYR-4059: an unbounded loop destroyed verified work). Without one,
+ * an agent that cannot reach a pass — out of turns, or a `guard-removed` it cannot
+ * restore, which no marker documents away — delivers no report at all, and a
+ * customer with no pull request is a worse outcome than one with a disclosed fault.
+ * Two refusals cover the common case, where the repair is one edit and one verify
+ * call away; the third call ships the row with `verificationFailures` set.
+ */
+export const REUSE_SUBMIT_MAX_REFUSALS = 2;
 /**
  * Re-derive the shared-helper outcome from the delivered files. Everything is
  * measured now: the utils file is located by header, its invariants re-checked, the
  * imports re-counted — the recorded verdict is not consulted, so a utils file
- * rewritten after the verify pass is described as it stands. Returns `undefined`
- * (omit `helpers`) when no utils file exists for the spec.
+ * rewritten after the verify pass is described as it stands. Omits `helpers` when
+ * no utils file exists for the spec; the top-level un-extracted duplicate count is
+ * reported either way.
+ *
+ * The blocking verdict is `!r.ok` — exactly what the live pass fails on: the five
+ * blocking kinds after allow-marker filtering, plus a malformed allow marker. It is
+ * raised whether or not a utils file was located: a spec that drops below its
+ * modularization baseline is below it with or without a module beside it.
  */
 async function rederiveHelperOutcome(record) {
     const { testFilePath, language } = record;
     if (!testFilePath || !language)
-        return undefined;
+        return { outcome: undefined };
     const r = await verifyUtils({
         testFile: testFilePath,
         language,
         testType: record.utils?.testType,
         baseline: record.baseline,
     });
+    const failures = r.ok ? [] : verificationFailures(r);
+    const blocking = r.ok
+        ? undefined
+        : {
+            file: testFilePath,
+            failures,
+            // The live failure text: file and line per finding, the paste-ready allow
+            // line for each markerable kind, and the guard rule — minus this pass's own
+            // call-to-action and round budget, which the refusal supplies.
+            detail: formatUtilsVerifyText(r, { embedded: true }),
+            verifyCall: utilsVerifyCall(record, testFilePath),
+        };
+    // Counted before the no-utils-file return: the run that extracted nothing is the
+    // one this count exists for, and it needs no module to be true.
+    const unextracted = r.unextractedDuplicates.length > 0
+        ? {
+            unextractedDuplicateSites: r.unextractedDuplicates.reduce((n, d) => n + d.sites.length, 0),
+        }
+        : {};
     if (r.utilsFiles.length === 0)
-        return {};
-    const lost = r.violations.some((v) => v.kind === "assertion-loss" || v.kind === "guard-removed");
+        return { outcome: unextracted, blocking };
+    // Two faults, two fields: a deleted guard is not a lost assertion, and a reader
+    // acting on the row must not be sent after the wrong one. The count is MEASURED:
+    // a `reuse-verify: allow` marker documents a loss and clears the verdict, it does
+    // not put the assertions back, so an allowed loss still reads as not preserved.
+    // (A guard is never allowable, so `violations` alone is complete for it.)
+    const assertionLoss = [...r.violations, ...r.allowed].some((v) => v.kind === "assertion-loss");
+    const guardRemoved = r.violations.some((v) => v.kind === "guard-removed");
     return {
-        helpers: {
-            utilsFile: utilsFileLabel(r.utilsFiles),
-            helpersImported: r.imported,
-            ...(record.baseline ? { assertionsPreserved: !lost } : {}),
-            ...(r.inlineCallSites.length > 0
-                ? { siblingInlineCallSites: r.inlineCallSites.length }
-                : {}),
-            verification: r.ok
-                ? HelperVerificationOutcome.Passed
-                : HelperVerificationOutcome.Failed,
+        outcome: {
+            ...unextracted,
+            helpers: {
+                utilsFile: utilsFileLabel(r.utilsFiles),
+                helpersImported: r.imported,
+                helperNames: r.importedNames,
+                ...(record.baseline ? { assertionsPreserved: !assertionLoss } : {}),
+                // Absent only with no baseline, like `assertionsPreserved`: a baseline that
+                // recorded no guard had nothing to lose, so its guard is preserved.
+                ...(record.baseline
+                    ? {
+                        pageErrorGuardPreserved: record.baseline.pageErrorGuard
+                            ? !guardRemoved
+                            : true,
+                    }
+                    : {}),
+                ...(r.inlineCallSites.length > 0
+                    ? { siblingInlineCallSites: r.inlineCallSites.length }
+                    : {}),
+                verification: r.ok
+                    ? HelperVerificationOutcome.Passed
+                    : HelperVerificationOutcome.Failed,
+                ...(r.ok ? {} : { verificationFailures: failures }),
+            },
         },
+        blocking,
     };
 }
+/**
+ * The reason behind a failed shared-helper verdict, one entry per blocking kind in
+ * the order the verifier found them. The verify pass had these in hand and dropped
+ * them after computing `ok`; without them a `failed` row is a verdict nobody can act
+ * on. The detail text is the verifier's own — for an assertion loss it carries the
+ * counts (baseline, delivered, in the test, in the helpers) that decided the verdict.
+ */
+export function verificationFailures(r) {
+    const byKind = new Map();
+    for (const v of r.violations) {
+        const entry = byKind.get(v.kind) ?? { count: 0, details: [] };
+        entry.count++;
+        entry.details.push(v.detail);
+        byKind.set(v.kind, entry);
+    }
+    // A marker the grammar cannot read fails the verify on its own (the decline it
+    // documents would be dropped silently), so it is a reason like any other.
+    if (r.malformedAllows.length > 0)
+        byKind.set("malformed-allow-marker", {
+            count: r.malformedAllows.length,
+            details: r.malformedAllows.map((m) => `${path.basename(m.file)}: ${m.line}`),
+        });
+    return [...byKind].map(([kind, { count, details }]) => ({
+        kind,
+        count,
+        detail: details.join("; "),
+    }));
+}
 /**
  * Raw-locator coverage for the delivered spec, or `undefined` when it cannot be
  * established.
@@ -715,11 +837,18 @@ async function coverageFrom(testFilePath, specContent) {
  *
  * Returns the recorded outcome minus internals when re-derivation is impossible
  * (no path recorded — now only the no-POM-layer path, which has no spec to measure
- * and no candidates to contrast against), and `undefined` when it fails outright.
+ * and no candidates to contrast against), and no outcome when it fails outright.
  * Failing closed matters: falling back to the recorded counts is exactly the false
  * claim this exists to prevent.
+ *
+ * Beside the outcome comes the blocking verdict the delivered files earn under the
+ * live check — see {@link ReuseBlockingVerdict}. One measurement feeds both: the row
+ * the report publishes and the refusal `skyramp_submit_report` returns. That half
+ * fails OPEN like every reuse check: a re-derivation that throws yields no outcome
+ * and no verdict. A verifier that cannot run is not evidence against the file, and
+ * refusing a report on a malfunction would deliver nothing to the customer.
  */
-export async function rederiveReuseOutcome(record) {
+export async function rederiveReuse(record) {
     const { candidatesDetected, verification, flagged, testFilePath, language } = record;
     // A SkyrampUtils-path record has nothing for the POM verifier to measure; its
     // outcome is re-derived from the utils file instead.
@@ -729,7 +858,7 @@ export async function rederiveReuseOutcome(record) {
         }
         catch (err) {
             logger.warning("Could not re-derive the shared-helper outcome from the delivered files — omitting it rather than reporting a stale verdict", { testFile: testFilePath, error: String(err) });
-            return undefined;
+            return { outcome: undefined };
         }
     }
     // No spec identity was ever recorded, so there is nothing to measure — only the
@@ -737,10 +866,11 @@ export async function rederiveReuseOutcome(record) {
     // no-POM-layer path; a run that detected candidates always records the identity
     // (see recordCandidates), precisely so the zero-reuse case does not land here.
     if (!testFilePath || !language)
-        return { candidatesDetected, verification };
+        return { outcome: { candidatesDetected, verification } };
     try {
         const r = await verifyReuse(testFilePath, language);
         const specContent = await readFile(testFilePath, "utf8");
+        const blocking = await pomBlockingVerdict(testFilePath, language, r);
         // Diagnose the file the report is actually built from. A marker the zero-reuse
         // gate accepts but this cannot parse satisfies the escape hatch while its
         // decline never reaches the report — silent signal loss is the failure class
@@ -753,7 +883,7 @@ export async function rederiveReuseOutcome(record) {
         const skipped = buildSkipped(specContent, flagged);
         const coverage = await coverageFrom(testFilePath, specContent);
         const reuseHappened = r.reusedCalls > 0;
-        return {
+        const outcome = {
             candidatesDetected,
             callsReused: r.reusedCalls,
             // Only a POM call can be checked, so `checkedCalls` is a subset of
@@ -778,13 +908,88 @@ export async function rederiveReuseOutcome(record) {
             missedReuse: coverage && coverage.missed.length > 0 ? coverage.missed : undefined,
             // A PASSED verdict describes a spec that no longer exists once reuse is gone,
             // and pairing it with a zero count reads as though the empty result had been
-            // blessed.
-            verification: reuseHappened ? verification : undefined,
+            // blessed. And a spec that fails the live check NOW is failed, whatever the
+            // recorded verdict says — that is the row that ships past the refusal bound.
+            verification: blocking
+                ? ReuseVerificationOutcome.Failed
+                : reuseHappened
+                    ? verification
+                    : undefined,
+            ...(blocking ? { verificationFailures: blocking.failures } : {}),
             skipped: skipped.length > 0 ? skipped : undefined,
         };
+        return { outcome, blocking };
     }
     catch (err) {
         logger.warning("Could not re-derive the POM-reuse outcome from the delivered spec — omitting the reuse summary rather than reporting counts that may no longer hold", { testFile: testFilePath, error: String(err) });
+        return { outcome: undefined };
+    }
+}
+/**
+ * The page-object path's blocking verdict on the delivered spec: the live verify
+ * chain — POM calls resolved against source, then the infra gate, then the
+ * zero-reuse gate — re-run as it stands. The Ghost instance is the zero-reuse gate:
+ * a full-file rewrite after verification leaves raw selectors that match the page
+ * objects detection found, with no `// kept inline:` decline.
+ *
+ * Every POM record with a spec identity is measured, not only one that recorded a
+ * candidate count: selector-grep discovery withholds `candidatesDetected` (the count
+ * would claim a page-object layer that app markup only resembles) yet still hands
+ * the POMs to the reuse flow, and a member that no longer exists on such a spec fails
+ * the live verify too. The zero-reuse gate limits itself to glob discovery
+ * internally, so running the chain here adds no false zero-reuse refusal. The spec
+ * identity is written only by the POM-aware verify branch, whose predicate requires
+ * Playwright — which is why the framework can be stated here rather than read from a
+ * record that never held it. Fails open when a gate throws — a gate that cannot run
+ * is no evidence.
+ */
+async function pomBlockingVerdict(testFile, language, r) {
+    // The record's language was written from the reuse tool's validated `language`
+    // param, but the record type keeps it a string: a value outside the enum means a
+    // check that cannot run, and a check that cannot run does not block.
+    const known = Object.values(ProgrammingLanguage).includes(language);
+    if (!known) {
+        logger.warning("Report-time POM gate skipped — the record's language is not one the reuse tool accepts", { testFile, language });
         return undefined;
     }
+    const target = {
+        testFile,
+        language: language,
+        framework: "playwright",
+    };
+    let infra;
+    let zero;
+    try {
+        infra = await infraGateFailure(target, r);
+        zero =
+            infra === undefined ? await zeroReuseGateFailure(target, r) : undefined;
+    }
+    catch (err) {
+        logger.warning("Report-time POM gate threw — not refusing the report on a check that could not run", { testFile, error: String(err) });
+        return undefined;
+    }
+    const gate = infra ?? zero;
+    if (gate === undefined && r.ok)
+        return undefined;
+    const failures = [];
+    if (infra !== undefined)
+        failures.push({ kind: "skyramp-infra-missing", count: 1, detail: infra });
+    if (zero !== undefined)
+        failures.push({ kind: "zero-reuse", count: 1, detail: zero });
+    if (r.parseError)
+        failures.push({ kind: "parse-error", count: 1, detail: r.parseError });
+    if (r.violations.length > 0)
+        failures.push({
+            kind: "pom-member-missing",
+            count: r.violations.length,
+            detail: r.violations
+                .map((v) => `${v.binding}.${v.member} — not found in ${v.searched.join(", ")}`)
+                .join("; "),
+        });
+    return {
+        file: testFile,
+        failures,
+        detail: composeVerifyText(gate, r),
+        verifyCall: `skyramp_reuse_code with { testFile: "${testFile}", language: "${language}", framework: "playwright", verify: true }`,
+    };
 }

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

@@ -22,5 +22,10 @@ export interface UtilsVerifyContext {
     /** Whether the verdict reached run state. When it did not, the checkpoints fail
      *  open on the unwritable state file — the agent is told rather than left to loop. */
     recorded?: boolean;
+    /** The text is quoted inside skyramp_submit_report's refusal, which supplies its
+     *  own call-to-action and its own round bound. The findings and the paste-ready
+     *  allow lines stay; this pass's "call skyramp_reuse_code again" and its
+     *  `UTILS_VERIFY_MAX_ROUNDS` budget — which no counter at submit tracks — go. */
+    embedded?: boolean;
 }
 export declare function formatUtilsVerifyText(r: UtilsVerifyResult, ctx?: UtilsVerifyContext): string;

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

@@ -1,5 +1,6 @@
 import * as path from "path";
-import { allowMarkerLine, MARKERABLE_UTILS_KINDS, HELPER_FAMILIES, } from "../../utils/utils-verify/index.js";
+import { allowMarkerLine, describeAssertionCount, MARKERABLE_UTILS_KINDS, HELPER_FAMILIES, } from "../../utils/utils-verify/index.js";
+import { utilsFileLabel } from "./reuse-state.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
@@ -23,17 +24,21 @@ export function formatUtilsVerifyText(r, ctx = {}) {
     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);
+            tail +
+            unextractedDuplicatesAdvisory(r));
     }
     const files = r.utilsFiles.map((f) => show(f, r)).join(", ");
     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} ` +
+        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.` +
             tail +
             inlineCallSitesAdvisory(r) +
+            unextractedDuplicatesAdvisory(r) +
+            duplicateActionAdvisory(r) +
             singleImporterAdvisory(r));
     }
     const lines = [];
@@ -47,19 +52,26 @@ export function formatUtilsVerifyText(r, ctx = {}) {
         // 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.`);
+            : HELPER_FAMILIES.api.fixRule}), update any call site whose signature changed${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");
+        const markerable = r.violations.filter((v) => v.kind !== "guard-removed" &&
+            v.kind !== "import-form" &&
+            v.kind !== "helper-redefined");
         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.`);
+            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.`);
         }
         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 === "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 === "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.");
     }
@@ -71,8 +83,41 @@ export function formatUtilsVerifyText(r, ctx = {}) {
     return (lines.join("\n") +
         tail +
         inlineCallSitesAdvisory(r) +
+        unextractedDuplicatesAdvisory(r) +
+        duplicateActionAdvisory(r) +
         singleImporterAdvisory(r));
 }
+/** 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.
+ *  Empty when no baseline exists — an unmodularized spec never had one. Not appended
+ *  to the no-utils-file PASSED, whose text says nothing was verified. */
+function assertionCountNote(r) {
+    const c = r.assertionCount;
+    if (!c)
+        return "";
+    // The verdict is read from the numbers, not from `ok`: a PASSED can carry a
+    // documented assertion-loss (the marker moves it to `allowed`), and a rise
+    // (enhancement after the hand-out) is not "held" — eval readers took that
+    // word literally against a 0 → 54 pair.
+    const verdict = c.delivered < c.baseline
+        ? `Assertion count fell: ${describeAssertionCount(c)} — documented by an allow marker.`
+        : c.delivered === c.baseline
+            ? `Assertion count held: ${describeAssertionCount(c)}.`
+            : `Assertion count rose: ${describeAssertionCount(c)}.`;
+    return ` ${verdict} Count only — skyramp_execute_test compares assertion subjects against the generated spec.`;
+}
+/** How the un-extracted advisory names where a helper may go: every module in scope,
+ *  each as its repository-relative path, joined with `, ` — the label the report row
+ *  carries, so the text the agent edits from agrees with it. (The inline advisory
+ *  names ONE module per site: the one that defines the matched helper.) Runs `git
+ *  rev-parse` once per file: call it once per advisory, never inside a per-site loop.
+ *  Falls back to the generic name when no module exists yet (the no-utils-file path). */
+function moduleLabel(r) {
+    return r.utilsFiles.length > 0
+        ? utilsFileLabel(r.utilsFiles)
+        : "the shared utils file";
+}
 /** 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
@@ -80,16 +125,44 @@ export function formatUtilsVerifyText(r, ctx = {}) {
 function inlineCallSitesAdvisory(r) {
     if (r.inlineCallSites.length === 0)
         return "";
-    const utils = r.utilsFiles.length === 1
-        ? path.basename(r.utilsFiles[0])
-        : "the utils file";
+    // One label per utils FILE, computed once (utilsFileLabel runs git per call), so a
+    // site names the module that defines its helper rather than the list of all.
+    const labels = new Map(r.utilsFiles.map((f) => [f, utilsFileLabel([f])]));
+    const labelOf = (f) => labels.get(f) ?? utilsFileLabel([f]);
     const n = r.inlineCallSites.length;
     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.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 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.`,
+        ...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.`,
+    ].join("\n");
+}
+/** Operations written in two or more sibling generated tests with no shared helper —
+ *  the mirror of inlineCallSitesAdvisory: that names a helper not USED, this a helper
+ *  not CREATED. Every gate compares against a defined helper, so a run could leave the
+ *  operation its PR was about duplicated four times and report a clean pass. Advisory —
+ *  consolidation is a judgement, and a wrong block costs more than a wrong note. */
+function unextractedDuplicatesAdvisory(r) {
+    const dups = r.unextractedDuplicates;
+    if (dups.length === 0)
+        return "";
+    const utils = moduleLabel(r);
+    const n = dups.length;
+    return [
+        "",
+        "",
+        `ADVISORY — ${n} operation${n === 1 ? " is" : "s are"} written in two or more Skyramp-generated tests here and no shared helper wraps ${n === 1 ? "it" : "them"} (does not block):`,
+        ...dups.map((d) => `- ${d.method} ${d.path} · ${d.sites.length} copies: ` +
+            // Every site is in the spec's own directory by construction, so the basename
+            // is unambiguous — and show() has nothing to relativise against on the
+            // no-utils-file path, where it would print every site in full.
+            d.sites
+                .map((s) => `${path.basename(s.file)}:${s.line}${s.localHelper ? ` (${s.localHelper})` : ""}`)
+                .join(", ")),
+        // The remediation is the policy's own rule, not a restatement; extracting a helper
+        // writes to the utils file, which the blocking gates measure, so re-verify.
+        `Each is a candidate for one helper in ${utils} (${HELPER_FAMILIES.api.fixRule}); the literals that differ between the copies are its defaulted parameters. Then re-verify; a pre-existing test you edited must also run with skyramp_execute_test.`,
     ].join("\n");
 }
 /** Helpers only this test (or no test) imports. Advisory: on a first run every helper
@@ -146,6 +219,25 @@ function typingAdvisory(r) {
         "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");
 }
+/** 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
+ *  the per-helper naming and typing notes and before the importer counts. The key is read from selector literals,
+ *  so this advises where the api route key blocks: a wrong note costs a sentence, a
+ *  wrong block costs a run. */
+function duplicateActionAdvisory(r) {
+    const pairs = r.advisories.filter((v) => v.kind === "duplicate-action");
+    if (pairs.length === 0)
+        return "";
+    const n = pairs.length;
+    return [
+        "",
+        "",
+        `ADVISORY — ${n} pair${n === 1 ? "" : "s"} of browser helpers perform${n === 1 ? "s" : ""} the same action sequence (does not block):`,
+        ...pairs.map((v) => `- ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`),
+        "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");
+}
 function verdictTail(ctx) {
     if (ctx.recorded !== false)
         return "";

package/build/tools/generate-tests/generateBatchScenarioRestTool.js

@@ -243,7 +243,8 @@ Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\`
         if (params.authHeader === undefined) {
             try {
                 const repoPath = params.outputDir || process.cwd();
-                const resolved = await resolveAuthFromWorkspace(repoPath, params.authHeader, params.authScheme);
+                // The directory the test is written into names the service it is for.
+                const resolved = await resolveAuthFromWorkspace(repoPath, params.authHeader, params.authScheme, params.outputDir);
                 if (resolved) {
                     params.authHeader = resolved.authHeader;
                     if (resolved.authScheme !== undefined) {