@skyramp/mcp 0.3.6-rc.2.ac20 → 0.3.7

package/build/utils/assertion-verify/ui-lints.js

@@ -0,0 +1,244 @@
+import { escapeRegExp } from "../regex.js";
+import { strippedSources } from "./strip-dispatch.js";
+import { balancedCloseIndex, identifierRe, inScope, interpolationRe, lineOfOffset, } from "./lint-types.js";
+/**
+ * Deterministic UI (Playwright) lints — the machine-checkable slice of the D5
+ * rubric's UI dims:
+ *   critical_assertions → expect import source, pageerror listener asserted,
+ *                         dead response captures, repeated elements w/o count
+ *   computed_values     → tautologies here; exact-vs-visibility is enforced by
+ *                         the strength score + weak-additions gate in verify.ts
+ *   post_edit           → unasserted trailing state-changing action
+ */
+const PLAYWRIGHT_EXPECT_IMPORT_RES = [
+    /import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*['"]@playwright\/test['"]/g,
+    /(?:const|let|var)\s*\{([^}]*)\}\s*=\s*require\s*\(\s*['"]@playwright\/test['"]\s*\)/g,
+];
+/** `expect` imported from @playwright/test — banned flatly by the UI rules. */
+function lintPlaywrightExpectImport(commentless) {
+    for (const re of PLAYWRIGHT_EXPECT_IMPORT_RES) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(commentless)) !== null) {
+            if (/\bexpect\b/.test(m[1])) {
+                return [
+                    {
+                        rule: "expect-import-source",
+                        severity: "hard",
+                        line: lineOfOffset(commentless, m.index),
+                        message: "`expect` is imported from '@playwright/test'.",
+                        remediation: "Import `expect` from '@skyramp/skyramp' instead (keep `test` on the playwright line).",
+                    },
+                ];
+            }
+        }
+    }
+    return [];
+}
+// Any page-ish handle counts: specs keep a raw handle (`rawPage`) for
+// assertions because expect() rejects the SkyrampPage proxy.
+const PAGEERROR_LISTENER_RE = /[\w$]*[Pp]age\s*\.\s*on\s*\(\s*['"]pageerror['"]/;
+const ERRORS_LENGTH_ASSERT_RES = [
+    /toHaveLength\s*\(\s*0\s*\)/,
+    // `(?:,[^)]*)?` admits expect's optional message argument.
+    /\.length\s*(?:,[^)]*)?\)\s*\.\s*(?:toBe|toEqual|toStrictEqual)\s*\(\s*0\s*\)/,
+    /(?:toEqual|toStrictEqual)\s*\(\s*\[\s*\]\s*\)/,
+];
+/** pageerror listener registered but its errors array never asserted (hard);
+ *  listener absent entirely stays warn-only — helpers/fixtures may register it,
+ *  and forcing a structural insertion conflicts with autoApply's
+ *  only-add-assertion-lines constraint. Promotion pending run evidence. */
+function lintPageErrors(commentless) {
+    const listener = PAGEERROR_LISTENER_RE.exec(commentless);
+    if (!listener) {
+        return [
+            {
+                rule: "pageerror-listener-absent",
+                severity: "warn",
+                message: "No `page.on('pageerror', ...)` listener found in this file.",
+                remediation: "Register the listener before the first navigation and assert the collected errors array is empty at the end of the test.",
+            },
+        ];
+    }
+    if (ERRORS_LENGTH_ASSERT_RES.some((re) => re.test(commentless)))
+        return [];
+    return [
+        {
+            rule: "pageerror-unasserted",
+            severity: "hard",
+            line: lineOfOffset(commentless, listener.index),
+            message: "A `page.on('pageerror', ...)` listener collects errors, but the errors array is never asserted.",
+            remediation: "Add `expect(errors).toHaveLength(0)` (or equivalent) at the end of the test.",
+        },
+    ];
+}
+// Codegen emits BOTH shapes: direct (`const r = await page.waitForResponse(…)`)
+// and promise-then-await (`const p = page.waitForResponse(…); …; const r = await p;`).
+// Matching only the direct form made this lint a no-op on real codegen output.
+const DIRECT_RESPONSE_BINDING_RE = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*await\s+[\w$]*[Pp]age\s*\.\s*waitForResponse\s*\(/g;
+const PROMISE_BINDING_RE = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*[\w$]*[Pp]age\s*\.\s*waitForResponse\s*\(/g;
+/** A captured `waitForResponse` response that is never referenced again.
+ *  Takes the raw comment-stripped source too: template-literal interpolations
+ *  are blanked in `stripped`, so a use like `` `order-${resp.headers()...}` ``
+ *  is only visible there.
+ *
+ *  WARN, not hard — measured against skyramp's gen_reference UI goldens,
+ *  pristine codegen emits 3–9 unused `const rN = await rPromiseN` captures per
+ *  file (63 across the corpus): many are synchronization-only waits whose
+ *  bodies aren't meaningfully assertable, and a hard finding per capture would
+ *  dominate every UI verify loop with no marker escape. The rubric pressure to
+ *  assert captured responses stays via this warn plus the strength gate. */
+function lintDeadResponseCaptures(stripped, commentless) {
+    const findings = [];
+    // Response bindings from the direct shape…
+    const bindings = [];
+    let m;
+    DIRECT_RESPONSE_BINDING_RE.lastIndex = 0;
+    while ((m = DIRECT_RESPONSE_BINDING_RE.exec(stripped)) !== null) {
+        const close = balancedCloseIndex(stripped, m.index + m[0].length - 1);
+        bindings.push({
+            varName: m[1],
+            index: m.index,
+            end: close === -1 ? m.index + m[0].length : close + 1,
+        });
+    }
+    // …plus the promise-then-await shape: resolve `const r = await <promiseVar>`
+    // for every promise binding, and treat a promise that is never referenced at
+    // all as a dead capture itself.
+    // (The promise pattern cannot match the direct form — `await ` between `=`
+    // and the page handle breaks its contiguous match — so no overlap handling.)
+    PROMISE_BINDING_RE.lastIndex = 0;
+    while ((m = PROMISE_BINDING_RE.exec(stripped)) !== null) {
+        const promiseVar = m[1];
+        const close = balancedCloseIndex(stripped, m.index + m[0].length - 1);
+        const restStart = close === -1 ? m.index + m[0].length : close + 1;
+        const rest = stripped.slice(restStart);
+        const awaited = new RegExp(`(?:const|let|var)\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*await\\s+${escapeRegExp(promiseVar)}(?![\\w$])`).exec(rest);
+        if (awaited) {
+            bindings.push({
+                varName: awaited[1],
+                index: restStart + awaited.index,
+                end: restStart + awaited.index + awaited[0].length,
+            });
+        }
+        else if (!identifierRe(promiseVar).test(rest)) {
+            bindings.push({ varName: promiseVar, index: m.index, end: restStart });
+        }
+    }
+    for (const { varName, index, end } of bindings) {
+        const rest = stripped.slice(end);
+        const usedInInterpolation = interpolationRe(varName, "typescript").test(commentless.slice(end));
+        // Identifier-boundary lookarounds, not \b: `\b` breaks on `$`-prefixed
+        // names ($resp), silently turning this into a guaranteed false positive.
+        if (!identifierRe(varName).test(rest) && !usedInInterpolation) {
+            findings.push({
+                rule: "dead-response-capture",
+                severity: "warn",
+                line: lineOfOffset(stripped, index),
+                message: `\`${varName}\` captures a network response via waitForResponse but is never used.`,
+                remediation: `Assert at least one status, body, or header field on \`${varName}\` (e.g. \`expect(${varName}.status()).toBe(200)\`).`,
+            });
+        }
+    }
+    return findings;
+}
+// getByText('X') asserted toHaveText('X') with the identical literal. Restricted
+// to getByText — getByRole+name asserted with the same text is a sanctioned
+// pattern in the rules' own examples. Misses chains with links in between
+// (.first() etc.) by design: a miss is fine, a false positive is not.
+// The literal groups exclude `\` from the any-char alternative so the two
+// alternatives are disjoint — the ambiguous form backtracks exponentially on
+// escape-heavy literals (ReDoS that would hang the whole MCP server).
+const TAUTOLOGY_RE = /(?:getByText|get_by_text)\s*\(\s*(['"`])((?:\\.|(?!\1)[^\\\n])*)\1[^)]*\)\s*\)?\s*\.\s*(?:toHaveText|toContainText|to_have_text|to_contain_text)\s*\(\s*(['"`])((?:\\.|(?!\3)[^\\\n])*)\3/g;
+function lintTautologies(commentless, opts) {
+    const findings = [];
+    let m;
+    TAUTOLOGY_RE.lastIndex = 0;
+    while ((m = TAUTOLOGY_RE.exec(commentless)) !== null) {
+        const line = lineOfOffset(commentless, m.index);
+        if (m[2] === m[4] && inScope(line, opts)) {
+            findings.push({
+                rule: "tautological-assertion",
+                severity: "hard",
+                line,
+                message: `Tautology: element located by text ${JSON.stringify(m[2])} is asserted to have that same text.`,
+                remediation: "Assert a different knowable property (count, value, attribute), or locate the element by a structural selector and keep the text assertion.",
+            });
+        }
+    }
+    return findings;
+}
+// Signals that the page renders repeated elements (rows, list items, nth/first
+// access), which the rubric expects paired with an exact toHaveCount(N).
+const REPEATED_ELEMENT_RE = /getByRole\s*\(\s*['"](?:row|listitem|cell|option)['"]|\.\s*nth\s*\(|\.\s*first\s*\(\s*\)|\.\s*last\s*\(\s*\)/;
+const HAS_COUNT_RE = /toHaveCount\s*\(|to_have_count\s*\(/;
+/** Repeated/collection elements are exercised but no exact count is asserted.
+ *  Warn-only: whether a list truly renders is not knowable from the spec alone
+ *  (the D5 judge has a matching N/A condition for the same reason). */
+function lintRepeatedElementsWithoutCount(commentless) {
+    const repeated = REPEATED_ELEMENT_RE.exec(commentless);
+    if (!repeated || HAS_COUNT_RE.test(commentless))
+        return [];
+    return [
+        {
+            rule: "repeated-elements-without-count",
+            severity: "warn",
+            line: lineOfOffset(commentless, repeated.index),
+            message: "The test works with repeated/collection elements but never asserts an exact count.",
+            remediation: "Add `toHaveCount(N)` (N from the trace or rendered DOM) plus at least one per-item content assertion.",
+        },
+    ];
+}
+// State-changing interactions; a test whose LAST such action is never followed
+// by an assertion leaves the post-action state unverified (post_edit dim).
+const ACTION_RE = /\.\s*(?:click|fill|press|check|uncheck|selectOption|select_option|set_input_files|setInputFiles)\s*\(/g;
+const EXPECT_SITE_RE = /\bexpect(?:\s*\.\s*soft)?\s*\(/g;
+function lintUnassertedTrailingAction(stripped) {
+    let lastAction = -1;
+    let m;
+    ACTION_RE.lastIndex = 0;
+    while ((m = ACTION_RE.exec(stripped)) !== null)
+        lastAction = m.index;
+    if (lastAction === -1)
+        return [];
+    let lastExpect = -1;
+    EXPECT_SITE_RE.lastIndex = 0;
+    while ((m = EXPECT_SITE_RE.exec(stripped)) !== null)
+        lastExpect = m.index;
+    if (lastExpect > lastAction)
+        return [];
+    return [
+        {
+            rule: "unasserted-trailing-action",
+            severity: "warn",
+            line: lineOfOffset(stripped, lastAction),
+            message: "The test's final state-changing action is never followed by an assertion — the updated state goes unverified.",
+            remediation: "After the last action, assert the visible updated outcome (`toHaveText`/`toHaveValue`/`toBeChecked`/`toHaveCount`) reflecting the edit.",
+        },
+    ];
+}
+/** UI (Playwright) lints. Python (playwright-python) UI specs deliberately get
+ *  the site-scoped lints only: the structural rules' patterns and accept-lists
+ *  are JS/TS-specific (imports, waitForResponse shapes, expect matcher accept
+ *  forms), and porting them without a python golden corpus to validate against
+ *  would recreate the false-block class review round 2 removed. Pinned by test. */
+export function lintUiSpec(raw, language, opts) {
+    if (language === "java")
+        return [];
+    const maintenance = opts?.scopeLines !== undefined;
+    const { commentless, stripped } = strippedSources(raw, language);
+    const findings = [];
+    if (language !== "python" && !maintenance) {
+        // Import lint is generation-only too: maintenance updates existing customer
+        // specs, which legitimately import expect from @playwright/test (the repo
+        // may not even depend on @skyramp/skyramp), and the maintenance scope
+        // forbids touching imports.
+        findings.push(...lintPlaywrightExpectImport(commentless));
+        findings.push(...lintPageErrors(commentless));
+        findings.push(...lintDeadResponseCaptures(stripped, commentless));
+        findings.push(...lintRepeatedElementsWithoutCount(commentless));
+        findings.push(...lintUnassertedTrailingAction(stripped));
+    }
+    findings.push(...lintTautologies(commentless, opts));
+    return findings;
+}

package/build/utils/assertion-verify/verify.d.ts

@@ -0,0 +1,61 @@
+import { type AssertionMetrics } from "./metrics.js";
+import type { LintFinding } from "./lint-types.js";
+export type AssertionEnhanceType = "generation" | "maintenance";
+/** Snapshot taken when the enhancement instructions were handed out. */
+export interface AssertionBaseline {
+    fileSha256: string;
+    count?: number;
+    strengthScore?: number;
+    fingerprints?: string[];
+    /** Copy of the generated file at hand-out time (run artifact dir). */
+    baselineFilePath?: string;
+}
+export interface AssertionVerifyResult {
+    ok: boolean;
+    enhanceType: AssertionEnhanceType;
+    /** False when verifying stateless (no baseline) — differential gates skipped. */
+    baselinePresent: boolean;
+    /** Maintenance verified with an empty assertion diff — nothing was added,
+     *  changed, or removed, so there was nothing to verify. */
+    maintenanceNoAssertionChanges?: boolean;
+    hashUnchanged: boolean;
+    /** Baseline assertions whose SUBJECT lost all coverage — genuine removals
+     *  (sample of 5). Replaced assertions (subject still asserted) never appear. */
+    removedFingerprints?: string[];
+    /** Total genuine removals — lets the report say "showing 5 of N" so the
+     *  agent restores everything in ONE pass instead of discovering the rest
+     *  on the next verify round. */
+    removedCount?: number;
+    /** Baseline assertions superseded by a new assertion on the same subject. */
+    replacedCount?: number;
+    /** Baseline assertions whose subject now lives in a locally imported helper
+     *  file (modularization) — sanctioned, never counted as removed. */
+    movedToHelperCount?: number;
+    /** Copy of the generated file at hand-out time, for diff/restore remediation. */
+    baselineFilePath?: string;
+    /** Current − baseline strength score; undefined without a baseline. */
+    strengthDelta?: number;
+    strengthGateFailed: boolean;
+    /** Assertions were added, but every one is existence/visibility-tier — the
+     *  computed-values rubric wants exact matchers. Runs in generation AND
+     *  maintenance (it requires additions to exist, so value-only maintenance
+     *  fixes cannot trip it). Marker-clearable, like the strength gate. */
+    weakAdditionsOnly: boolean;
+    hardFindings: LintFinding[];
+    warnings: LintFinding[];
+    markerReason?: string;
+    currentMetrics?: AssertionMetrics;
+}
+export declare function sha256Of(content: string): string;
+/**
+ * Deterministic verification that the enhancement instructions were applied:
+ * hash delta, no assertions removed, rubric lints clean, and (generation only)
+ * strength strictly increased unless a documented `assertions complete` marker
+ * declines it. Reads the file as delivered — throws if it cannot be read.
+ */
+export declare function verifyAssertionEnhancement(params: {
+    testFile: string;
+    testType: string;
+    enhanceType: AssertionEnhanceType;
+    baseline?: AssertionBaseline;
+}): Promise<AssertionVerifyResult>;

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

@@ -0,0 +1,215 @@
+import { createHash } from "crypto";
+import { readFile } from "fs/promises";
+import { computeAssertionMetrics, detectAssertionLanguage, subjectOf, } from "./metrics.js";
+import { lintUiSpec } from "./ui-lints.js";
+import { lintIntegrationTest } from "./integration-lints.js";
+import { lintContractTest } from "./contract-lints.js";
+import { findAssertionsCompleteMarker, findUnparsableAssertionsComplete, markerCommentToken, } from "./marker.js";
+import { importedHelperSubjects } from "./helper-imports.js";
+export function sha256Of(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+/** Current sites whose fingerprint occurs more often now than in the baseline
+ *  multiset — the assertions ADDED since hand-out (includes the new side of a
+ *  replacement). Powers maintenance lint scoping and the weak-additions gate. */
+function addedSites(current, baselineFingerprints) {
+    const budget = new Map();
+    for (const fp of baselineFingerprints)
+        budget.set(fp, (budget.get(fp) ?? 0) + 1);
+    const added = [];
+    for (const site of current.sites) {
+        const left = budget.get(site.fingerprint) ?? 0;
+        if (left > 0)
+            budget.set(site.fingerprint, left - 1);
+        else
+            added.push(site);
+    }
+    return added;
+}
+/**
+ * Deterministic verification that the enhancement instructions were applied:
+ * hash delta, no assertions removed, rubric lints clean, and (generation only)
+ * strength strictly increased unless a documented `assertions complete` marker
+ * declines it. Reads the file as delivered — throws if it cannot be read.
+ */
+export async function verifyAssertionEnhancement(params) {
+    const { testFile, testType, enhanceType, baseline } = params;
+    const content = await readFile(testFile, "utf8");
+    const language = detectAssertionLanguage(testFile);
+    const hashUnchanged = baseline !== undefined && sha256Of(content) === baseline.fileSha256;
+    // Unknown language: only the hash gate is computable — everything else fails open.
+    if (language === undefined) {
+        return {
+            ok: !(hashUnchanged && enhanceType === "generation"),
+            enhanceType,
+            baselinePresent: baseline !== undefined,
+            hashUnchanged,
+            strengthGateFailed: false,
+            weakAdditionsOnly: false,
+            hardFindings: [],
+            warnings: [],
+        };
+    }
+    const metrics = computeAssertionMetrics(content, language);
+    const countDecreasedBy = baseline?.count !== undefined
+        ? Math.max(0, baseline.count - metrics.count)
+        : 0;
+    // Correlate what disappeared since the baseline. A missing fingerprint whose
+    // SUBJECT is still asserted (by any current site) was REPLACED — a sanctioned
+    // enhancement (usually weak matcher → strong). A subject asserted inside a
+    // locally imported helper file was MOVED (modularization) — also sanctioned.
+    // A KNOWN subject that lost all coverage counts as removed regardless of the
+    // raw count (a same-count remove-A-add-B edit must not slip through);
+    // unrecoverable subjects stay conservative and count only when the raw count
+    // actually decreased.
+    let removedFingerprints;
+    let removedCount;
+    let replacedCount;
+    let movedToHelperCount;
+    if (baseline?.fingerprints !== undefined) {
+        const current = new Map();
+        for (const fp of metrics.fingerprints) {
+            current.set(fp, (current.get(fp) ?? 0) + 1);
+        }
+        const missing = baseline.fingerprints.filter((fp) => {
+            const left = current.get(fp) ?? 0;
+            if (left > 0) {
+                current.set(fp, left - 1);
+                return false;
+            }
+            return true;
+        });
+        const currentSubjects = new Set(metrics.fingerprints.map(subjectOf).filter((s) => s !== undefined));
+        let removed = missing.filter((fp) => {
+            const subject = subjectOf(fp);
+            if (subject === undefined)
+                return countDecreasedBy > 0;
+            return !currentSubjects.has(subject);
+        });
+        // Only pay the helper-file scan when something actually looks removed.
+        if (removed.length > 0) {
+            const helperSubjects = await importedHelperSubjects(testFile, content);
+            if (helperSubjects.size > 0) {
+                const stillRemoved = removed.filter((fp) => {
+                    const subject = subjectOf(fp);
+                    return subject === undefined || !helperSubjects.has(subject);
+                });
+                movedToHelperCount = removed.length - stillRemoved.length;
+                removed = stillRemoved;
+            }
+        }
+        replacedCount = missing.length - removed.length - (movedToHelperCount ?? 0);
+        if (removed.length > 0) {
+            removedFingerprints = removed.slice(0, 5);
+            removedCount = removed.length;
+        }
+    }
+    const strengthDelta = baseline?.strengthScore !== undefined
+        ? metrics.strengthScore - baseline.strengthScore
+        : undefined;
+    const added = baseline?.fingerprints !== undefined
+        ? addedSites(metrics, baseline.fingerprints)
+        : undefined;
+    // Maintenance scopes site lints to assertions added since the baseline; the
+    // baseline fingerprints are what make that diff computable.
+    const scopeLines = enhanceType === "maintenance" && added !== undefined
+        ? new Set(added.map((s) => s.line))
+        : undefined;
+    const lintOpts = scopeLines !== undefined ? { scopeLines } : undefined;
+    // Per-test-type lints; Java is never linted or strength-gated — count+hash
+    // only. Test types with no lint module (smoke/fuzz/load/e2e — the hand-out
+    // path refuses them) get NO lints rather than silently inheriting
+    // integration's: those rules were not written for them.
+    const findings = testType === "ui"
+        ? lintUiSpec(content, language, lintOpts)
+        : testType === "contract"
+            ? lintContractTest(content, language, lintOpts)
+            : testType === "integration"
+                ? lintIntegrationTest(content, language, lintOpts)
+                : [];
+    const marker = findAssertionsCompleteMarker(content, testFile, language);
+    const hardFindings = findings.filter((f) => f.severity === "hard");
+    const commentToken = markerCommentToken(language);
+    for (const line of findUnparsableAssertionsComplete(content, language)) {
+        hardFindings.push({
+            rule: "malformed-assertions-complete-marker",
+            severity: "hard",
+            message: `Unreadable marker: \`${line}\``,
+            remediation: `Use \`${commentToken} assertions complete: <test-file basename> — <reason>\` (this language's comment token; em dash, or a hyphen with a space on BOTH sides), with a real reason.`,
+        });
+    }
+    // Removals are NEVER marker-clearable: a marker that excused them would let
+    // "delete the failing assertion + one comment line" verify green — the exact
+    // case this gate exists to catch. The sanctioned coverage-moves (verify
+    // before modularization per the mandated steps; passed-verdict skip at
+    // execute time) don't need the exemption, and a post-modularize failure is
+    // always fixable by re-adding direct assertions beside the helper calls.
+    // (Derived, not stored: removedFingerprints !== undefined IS the gate.)
+    const removalGateFailed = removedFingerprints !== undefined;
+    // A decline marker is accepted on a GENERATION file only when work
+    // actually happened (something added or replaced). Without this, a
+    // marker-only comment edit was a full bypass: the comment changes the hash,
+    // the marker cleared both strength-family gates, and an untouched file
+    // trips nothing else — the exact "tests already have the key assertions"
+    // no-op the gate exists to catch (review finding on ae8b397e). The marker
+    // can excuse INSUFFICIENT strengthening ("only existence is knowable"); it
+    // cannot excuse ABSENT strengthening. Maintenance keeps marker semantics
+    // unchanged (its strength gates don't run; value-only fixes are legitimate).
+    const markerAccepted = marker !== undefined &&
+        (enhanceType !== "generation" ||
+            (added?.length ?? 0) > 0 ||
+            (replacedCount ?? 0) > 0);
+    const strengthGateFailed = enhanceType === "generation" &&
+        language !== "java" &&
+        strengthDelta !== undefined &&
+        strengthDelta <= 0 &&
+        !markerAccepted;
+    // Computed-values rubric: additions must not be exclusively existence/
+    // visibility-tier. A replacement's new side counts as an added site, so a
+    // weak→strong upgrade satisfies this. Marker-clearable (strength family).
+    // Unlike the strength-increase gate this runs in MAINTENANCE too: it is
+    // conditional on additions existing, so a value-only drift fix (no added
+    // sites) can never trip it — only genuinely weak new assertions do.
+    const weakAdditionsOnly = language !== "java" &&
+        added !== undefined &&
+        added.length > 0 &&
+        added.every((s) => s.weight === 1) &&
+        !markerAccepted;
+    // The hash gate ("byte-identical → nothing applied") is generation-only: in
+    // maintenance the file edits precede the enhance call, and "no assertion
+    // changes needed" is a legitimate outcome — the assertion-diff below is what
+    // decides whether there is anything to verify at all.
+    const hashGateFailed = hashUnchanged && enhanceType === "generation";
+    // Maintenance with an EMPTY assertion diff (nothing added, changed, or
+    // removed since hand-out): there is no assertion work to verify — pass, and
+    // let the report say so honestly.
+    const maintenanceNoAssertionChanges = enhanceType === "maintenance" &&
+        baseline?.fingerprints !== undefined &&
+        (added?.length ?? 0) === 0 &&
+        replacedCount === 0 &&
+        (removedCount ?? 0) === 0 &&
+        (movedToHelperCount ?? 0) === 0;
+    return {
+        ok: !hashGateFailed &&
+            !removalGateFailed &&
+            hardFindings.length === 0 &&
+            !strengthGateFailed &&
+            !weakAdditionsOnly,
+        maintenanceNoAssertionChanges,
+        enhanceType,
+        baselinePresent: baseline !== undefined,
+        hashUnchanged,
+        removedFingerprints,
+        removedCount,
+        replacedCount,
+        movedToHelperCount,
+        baselineFilePath: baseline?.baselineFilePath,
+        strengthDelta,
+        strengthGateFailed,
+        weakAdditionsOnly,
+        hardFindings,
+        warnings: findings.filter((f) => f.severity === "warn"),
+        markerReason: markerAccepted ? marker?.reason : undefined,
+        currentMetrics: metrics,
+    };
+}

package/build/utils/executorWorkDir.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The executor's own working area inside a repo — run videos, trace zips and
+ * other per-run artefacts. Delivered test files do not belong here: the run
+ * cleans and rewrites it, and `git add -- <testDirectory>` on a directory that
+ * encloses it commits every .webm.
+ */
+export declare const EXECUTOR_WORK_DIR = ".skyramp";
+export declare const EXECUTOR_VIDEOS_DIR = ".skyramp/videos";
+/**
+ * Whether `p` is the executor's working area or sits inside it. Matches on whole
+ * path segments, so a sibling such as `.skyramp-tests` is not a hit, and on the
+ * canonical path, so a symlink pointing into `.skyramp` cannot spell its way past
+ * the check.
+ */
+export declare function isInsideExecutorWorkDir(p: string): boolean;
+/**
+ * Refusal text for a caller that asked for output inside the working area. Names
+ * the field and the replacement so the agent can correct itself without help.
+ */
+export declare function executorWorkDirRefusal(destination: string): string;
+/**
+ * Every path a generation call could write to, given an outputDir and an optional
+ * caller-supplied file name. `output` can carry `../` segments, so outputDir alone
+ * is not enough to judge.
+ *
+ * Two compositions, because the writers disagree on an ABSOLUTE `output`:
+ * `generateEnrichedIntegrationTestTool` joins it (`path.join(outputDir, output)`,
+ * which keeps outputDir as a prefix), while `path.resolve` discards outputDir
+ * entirely. A guard cannot pick one and be right for both, so it judges both and
+ * refuses if either lands in the working area.
+ *
+ * outputDir is always judged on its own as well. An `output` of `../tests/x.py`
+ * resolves clear of the working area while outputDir stays `.skyramp`, and
+ * outputDir is what codegen receives as the directory to work in.
+ */
+export declare function generationTargets(outputDir: string, output?: string): string[];

package/build/utils/executorWorkDir.js

@@ -0,0 +1,77 @@
+import fs from "fs";
+import path from "path";
+/**
+ * The executor's own working area inside a repo — run videos, trace zips and
+ * other per-run artefacts. Delivered test files do not belong here: the run
+ * cleans and rewrites it, and `git add -- <testDirectory>` on a directory that
+ * encloses it commits every .webm.
+ */
+export const EXECUTOR_WORK_DIR = ".skyramp";
+export const EXECUTOR_VIDEOS_DIR = `${EXECUTOR_WORK_DIR}/videos`;
+/**
+ * Canonical form of `p`, where `p` may not exist yet: the deepest ancestor that
+ * DOES exist is resolved through symlinks and the missing remainder is appended
+ * back.
+ *
+ * `utils-verify/locate.ts` (realpath) and `code-refactor/reuse-state.ts` (canon)
+ * both fall back to the lexical path when the target is missing. A generation
+ * outputDir usually IS missing, and the lexical path is what a symlinked parent
+ * hides behind — so neither is usable here.
+ */
+function realpathAllowingMissing(p) {
+    let current = path.resolve(p);
+    const missing = [];
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync(current), ...[...missing].reverse());
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return path.resolve(p);
+            missing.push(path.basename(current));
+            current = parent;
+        }
+    }
+}
+/**
+ * Whether `p` is the executor's working area or sits inside it. Matches on whole
+ * path segments, so a sibling such as `.skyramp-tests` is not a hit, and on the
+ * canonical path, so a symlink pointing into `.skyramp` cannot spell its way past
+ * the check.
+ */
+export function isInsideExecutorWorkDir(p) {
+    return realpathAllowingMissing(p).split(path.sep).includes(EXECUTOR_WORK_DIR);
+}
+/**
+ * Refusal text for a caller that asked for output inside the working area. Names
+ * the field and the replacement so the agent can correct itself without help.
+ */
+export function executorWorkDirRefusal(destination) {
+    return `Refusing to write into "${destination}": it is inside ${EXECUTOR_WORK_DIR}, the Skyramp executor's working area (run videos and trace zips). Files written there are not delivered as tests. Set outputDir — and any output file name — so the result lands in the testDirectory of the service under test, read from ${EXECUTOR_WORK_DIR}/workspace.yml, or tests/skyramp when that service declares none. If that testDirectory is itself inside ${EXECUTOR_WORK_DIR}, it is wrong: re-run skyramp_init_workspace with a corrected one.`;
+}
+/**
+ * Every path a generation call could write to, given an outputDir and an optional
+ * caller-supplied file name. `output` can carry `../` segments, so outputDir alone
+ * is not enough to judge.
+ *
+ * Two compositions, because the writers disagree on an ABSOLUTE `output`:
+ * `generateEnrichedIntegrationTestTool` joins it (`path.join(outputDir, output)`,
+ * which keeps outputDir as a prefix), while `path.resolve` discards outputDir
+ * entirely. A guard cannot pick one and be right for both, so it judges both and
+ * refuses if either lands in the working area.
+ *
+ * outputDir is always judged on its own as well. An `output` of `../tests/x.py`
+ * resolves clear of the working area while outputDir stays `.skyramp`, and
+ * outputDir is what codegen receives as the directory to work in.
+ */
+export function generationTargets(outputDir, output) {
+    const dir = path.resolve(outputDir);
+    if (!output)
+        return [dir];
+    return [
+        dir,
+        path.resolve(outputDir, output),
+        path.resolve(path.join(outputDir, output)),
+    ];
+}

package/build/utils/featureFlags.d.ts

@@ -4,7 +4,8 @@
  * Each helper in this module reads a `SKYRAMP_FEATURE_*` env var and returns
  * a boolean. These helpers treat a flag as ON only when the env var is
  * exactly `"1"`; anything else (unset, empty, "0", "true", "false", etc.) is
- * treated as OFF.
+ * treated as OFF. The utils-reuse flag is additionally ON for the orgs in
+ * `UTILS_REUSE_DEFAULT_ORGS` regardless of the env vars.
  */
 /**
  * Gates BOTH consumer-side contract tests AND the SDK's "default mode"
@@ -55,6 +56,14 @@ export declare function isOneClickEnabled(): boolean;
  * Gates the POM-aware path of `skyramp_reuse_code`
  * (SKYRAMP_FEATURE_POM_REUSE=1).
  *
+ * Deliberately NOT defaulted on for `UTILS_REUSE_DEFAULT_ORGS`: for UI tests
+ * the POM path supersedes the modularize-first flow (see
+ * `isModularizeFirstTarget` in utils/reuseRouting.ts), so an org-level POM
+ * default would stop those orgs' UI tests from ever seeding a SkyrampUtils
+ * file — the very thing the utils org default exists to provide (SKYR-4290).
+ * And an explicit-"0"-override escape hatch cannot work either, because
+ * testbot normalizes an unset flag to a literal "0" before forwarding.
+ *
  * When OFF (default), TypeScript/JavaScript + Playwright targets are treated
  * like every other target: `skyramp_reuse_code` returns the SkyrampUtils
  * consolidation prompt, and none of the POM machinery runs — no deterministic
@@ -68,7 +77,8 @@ export declare function isOneClickEnabled(): boolean;
 export declare function isPomReuseEnabled(): boolean;
 /**
  * Gates SkyrampUtils code reuse for integration tests on the testbot path, and
- * for UI tests whenever the POM path is off (SKYRAMP_FEATURE_UTILS_REUSE=1).
+ * for UI tests whenever the POM path is off (SKYRAMP_FEATURE_UTILS_REUSE=1,
+ * or a `UTILS_REUSE_DEFAULT_ORGS` org).
  *
  * When OFF (default), the testbot prompt does not set `codeReuse` on
  * `skyramp_integration_test_generation` and its post-generation