@skyramp/mcp 0.4.0 → 0.4.1-rc.2

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

@@ -3,6 +3,8 @@ import { readFile, stat } from "fs/promises";
 import { logger } from "../logger.js";
 import { strippedSources } from "./strip-dispatch.js";
 import { identifierRe } from "./lint-types.js";
+import { blankCommentsAndStrings, parseUtilsFile, } from "../utils-verify/parse.js";
+import { utilsSpecFor } from "../utils-verify/language-spec.js";
 import { computeAssertionMetrics, detectAssertionLanguage, subjectOf, } from "./metrics.js";
 /**
  * Read-only scan of the spec's locally imported AND CALLED modules (the
@@ -14,12 +16,21 @@ import { computeAssertionMetrics, detectAssertionLanguage, subjectOf, } from "./
  * - One-directional — helper assertions can only EXCUSE removals, never add
  *   to the spec's count or strength score: a shared utils file is imported by
  *   many specs, and crediting its assertions to each one would inflate every
- *   baseline comparison.
+ *   baseline comparison. And each excuse is BOUNDED: a helper assertion
+ *   excuses one removal per call site of that helper, so a single
+ *   `verifyStatus()` call cannot clear three deleted status checks.
  * - CALLED, not merely imported — an import statement plus a dead helper file
  *   would otherwise turn a correctly-blocked gutting into a PASS (same
  *   call-position requirement as the reuse gate's call-site matching). Only
- *   helpers whose imported bindings appear at a call position in the spec
- *   contribute subjects.
+ *   helpers whose imported bindings appear at a call position in the spec are
+ *   read, and within such a file only the FUNCTIONS the spec calls through
+ *   that import's bindings contribute subjects: an uncalled sibling in a
+ *   shared utils file asserts nothing on this spec's behalf. A call through an
+ *   import alias (`{ x as y }`, `{ x: y }`, python `x as y`) IS a call of the
+ *   declared helper — the binding is resolved, not dropped. An assertion the
+ *   utils parser cannot place in a function (module level, `export default
+ *   function`, `exports.x = function`) falls back to the file-level rule: it
+ *   counts when any binding of the import is called, bounded by those calls.
  *
  * Helpers are never modified.
  */
@@ -36,8 +47,13 @@ const JS_IMPORT_RES = [
     /(?:const|let|var)\s+([^=]+?)\s*=\s*require\s*\(\s*['"](\.{1,2}\/[^'"]+)['"]\s*\)/g,
 ];
 const PY_IMPORT_RES = [
-    // from .x import a, b as c   |   from x import a
-    /^[ \t]*from\s+(\.*[\w.]+)\s+import\s+([^\n#]+)/gm,
+    // from .x import a, b as c   |   from x import (\n a,\n b as c,\n)   |
+    // from x import a, \<newline> b. The bodies are separate alternatives: a body
+    // that stops at the newline bound nothing on a wrapped import (the `(` fell to
+    // the name filter), so the helper was never read and every moved assertion
+    // became a false removal. A backslash continuation is consumed with its
+    // newline for the same reason. Runs on comment-stripped source.
+    /^[ \t]*from\s+(\.*[\w.]+)\s+import\s+(?:\(([^)]*)\)|((?:[^\n#\\]|\\\r?\n)+))/gm,
     // import x   (module itself becomes the callable namespace)
     /^[ \t]*import\s+([\w.]+)(?:\s+as\s+([\w]+))?/gm,
 ];
@@ -58,18 +74,20 @@ function pyCandidates(specDir, specifier) {
     const moduleName = specifier.replace(/^\.+/, "").split(".")[0];
     return moduleName ? [path.resolve(specDir, `${moduleName}.py`)] : [];
 }
-/** Local names bound by a JS import/require clause ("d, { a, b as c }"). */
-function jsBoundNames(clause) {
-    const names = [];
+/** Bindings of a JS import/require clause ("d, { a, b as c }" / "{ a: b }"). */
+function jsBindings(clause) {
+    const bindings = [];
     const star = /\*\s*as\s+([\w$]+)/.exec(clause);
     if (star)
-        names.push(star[1]);
+        bindings.push({ local: star[1] });
     const braces = /\{([^}]*)\}/.exec(clause);
     if (braces) {
         for (const part of braces[1].split(",")) {
-            const name = (part.split(/\s+as\s+|\s*:\s*/).pop() ?? "").trim();
-            if (/^[\w$]+$/.test(name))
-                names.push(name);
+            const [declared, local = declared] = part
+                .split(/\s+as\s+|\s*:\s*/)
+                .map((n) => n.trim());
+            if (/^[\w$]+$/.test(declared) && /^[\w$]+$/.test(local))
+                bindings.push({ declared, local });
         }
     }
     const bare = clause
@@ -78,8 +96,8 @@ function jsBoundNames(clause) {
         .replace(/,/g, " ")
         .trim();
     if (/^[\w$]+$/.test(bare))
-        names.push(bare);
-    return names;
+        bindings.push({ local: bare });
+    return bindings;
 }
 /** Relative/local imports with the names they bind. */
 function localImports(content, language) {
@@ -90,15 +108,20 @@ function localImports(content, language) {
         fromRe.lastIndex = 0;
         let m;
         while ((m = fromRe.exec(commentless)) !== null) {
-            const names = m[2]
-                .split(",")
-                .map((part) => (part.split(/\s+as\s+/).pop() ?? "").trim())
-                .filter((n) => /^\w+$/.test(n));
-            imports.push({ specifier: m[1], localNames: names });
+            const bindings = [];
+            // A continuation's backslash-newline is whitespace between names.
+            for (const part of (m[2] ?? m[3]).replace(/\\\r?\n/g, " ").split(",")) {
+                const [declared, local = declared] = part
+                    .split(/\s+as\s+/)
+                    .map((n) => n.trim());
+                if (/^\w+$/.test(declared) && /^\w+$/.test(local))
+                    bindings.push({ declared, local });
+            }
+            imports.push({ specifier: m[1], bindings });
         }
         importRe.lastIndex = 0;
         while ((m = importRe.exec(commentless)) !== null) {
-            imports.push({ specifier: m[1], localNames: [m[2] ?? m[1]] });
+            imports.push({ specifier: m[1], bindings: [{ local: m[2] ?? m[1] }] });
         }
         return imports;
     }
@@ -106,7 +129,7 @@ function localImports(content, language) {
         re.lastIndex = 0;
         let m;
         while ((m = re.exec(commentless)) !== null) {
-            imports.push({ specifier: m[2], localNames: jsBoundNames(m[1]) });
+            imports.push({ specifier: m[2], bindings: jsBindings(m[1]) });
         }
     }
     return imports;
@@ -119,13 +142,60 @@ function anyNameCalled(strippedSpec, names) {
     // the suffix requires a CALL position — `name(...)` or `name.member(...)`.
     return names.some((name) => new RegExp(`(?<!\\.)${identifierRe(name).source}\\s*(?:\\(|\\.\\s*[\\w$]+\\s*\\()`).test(strippedSpec));
 }
+/** Number of call sites of the helper declared as `fnName` through this
+ *  import's bindings: bare calls of the LOCAL name bound to it (the declared
+ *  name itself, or its alias) plus member calls on a namespace binding
+ *  (`ns.fnName(`). A namespace-style binding may itself BE a helper — a
+ *  default import or whole-module require of `export default checkStatus` /
+ *  `module.exports = checkStatus` — so its bare calls count as calls of
+ *  `defaultName`. With `fnName` undefined, counts every call through any of
+ *  the bindings (the file-level fallback). The `(?<!\.)` guards keep a
+ *  same-named member of some other object (`other.ns.fn(`) from counting.
+ *  Comment/string-stripped source. */
+function callSitesThroughImport(strippedSpec, bindings, fnName, defaultName) {
+    const fn = fnName === undefined ? "[\\w$]+" : identifierRe(fnName).source;
+    let count = 0;
+    for (const b of bindings) {
+        const local = identifierRe(b.local).source;
+        const bare = new RegExp(`(?<!\\.)${local}\\s*\\(`, "g");
+        if (b.declared === undefined) {
+            count +=
+                strippedSpec.match(new RegExp(`(?<!\\.)${local}\\s*\\.\\s*${fn}\\s*\\(`, "g"))?.length ?? 0;
+            if (fnName === undefined || fnName === defaultName)
+                count += strippedSpec.match(bare)?.length ?? 0;
+        }
+        else if (fnName === undefined || b.declared === fnName) {
+            count += strippedSpec.match(bare)?.length ?? 0;
+        }
+    }
+    return count;
+}
+/** The name a helper module exports as its default / whole export
+ *  (`export default checkStatus`, `module.exports = checkStatus`), on
+ *  comment/string-stripped source; undefined when there is none or it is not
+ *  a bare identifier. */
+function defaultExportName(strippedHelper) {
+    const m = /(?:^|\n)\s*export\s+default\s+([A-Za-z_$][\w$]*)\s*;?\s*(?:\n|$)/.exec(strippedHelper) ??
+        /(?:^|\n)\s*module\.exports\s*=\s*([A-Za-z_$][\w$]*)\s*;?\s*(?:\n|$)/.exec(strippedHelper);
+    return m?.[1];
+}
 /**
  * Assertion SUBJECTS found in the spec's locally imported, actually-called
  * helper files. Strict-by-default failure direction: an unreadable/oversized/
  * uncalled helper is skipped, so its subjects don't excuse anything.
  */
 export async function importedHelperSubjects(testFile, content) {
-    const subjects = new Set();
+    return new Set((await importedHelperSubjectCapacities(testFile, content)).keys());
+}
+/**
+ * The same subjects with their CAPACITY — how many removals each may excuse:
+ * one per call site of the helper function that asserts it (an assertion the
+ * parser cannot place in a function gets one per call through the import).
+ * The removal gate consumes this budget per removed baseline subject.
+ */
+export async function importedHelperSubjectCapacities(testFile, content) {
+    const subjects = new Map();
+    const add = (subject, n) => subjects.set(subject, (subjects.get(subject) ?? 0) + n);
     const language = detectAssertionLanguage(testFile);
     // Not a no-op: an empty subject set means NO removal gets excused by a
     // helper — the strict direction. Unknown languages have no import scanner;
@@ -136,7 +206,8 @@ export async function importedHelperSubjects(testFile, content) {
     const strippedSpec = strippedSources(content, language).stripped;
     const specDir = path.dirname(testFile);
     let scanned = 0;
-    for (const { specifier, localNames } of localImports(content, language)) {
+    for (const { specifier, bindings } of localImports(content, language)) {
+        const localNames = bindings.map((b) => b.local);
         if (scanned >= MAX_HELPER_FILES) {
             logger.warning("Assertion verification scanned the maximum number of imported helper files — remaining imports ignored", { testFile, max: MAX_HELPER_FILES });
             break;
@@ -160,11 +231,32 @@ export async function importedHelperSubjects(testFile, content) {
                 if (helperLanguage === undefined)
                     continue;
                 const helperContent = await readFile(candidate, "utf8");
-                for (const fp of computeAssertionMetrics(helperContent, helperLanguage)
-                    .fingerprints) {
-                    const subject = subjectOf(fp);
+                // Attribute each assertion to the helper function whose body holds it
+                // (utils-verify's line-range parser, on a string-blanked copy so a
+                // brace inside a literal cannot end a body early; line count is
+                // preserved). A function's sites count once per call of that function
+                // THROUGH THIS IMPORT — a bare call of a binding it declares, or a
+                // member call on one of its bindings (`ns.fn(`); a same-named function
+                // called via another module's binding does not count. A site in no
+                // parsed function falls back to the import's total call count.
+                const utilsSpec = utilsSpecFor(helperLanguage);
+                const helpers = utilsSpec
+                    ? parseUtilsFile(blankCommentsAndStrings(helperContent, utilsSpec), utilsSpec)
+                    : [];
+                const defaultName = defaultExportName(strippedSources(helperContent, helperLanguage).stripped);
+                const callsOf = new Map(helpers.map((h) => [
+                    h,
+                    callSitesThroughImport(strippedSpec, bindings, h.name, defaultName),
+                ]));
+                const fallbackCalls = callSitesThroughImport(strippedSpec, bindings);
+                for (const site of computeAssertionMetrics(helperContent, helperLanguage).sites) {
+                    const owner = helpers.find((h) => site.line >= h.line && site.line <= h.endLine);
+                    const calls = owner === undefined ? fallbackCalls : (callsOf.get(owner) ?? 0);
+                    if (calls === 0)
+                        continue;
+                    const subject = subjectOf(site.fingerprint);
                     if (subject !== undefined)
-                        subjects.add(subject);
+                        add(subject, calls);
                 }
                 scanned++;
                 break;

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

@@ -14,12 +14,41 @@ export interface LintFinding {
     remediation: string;
 }
 export interface LintOptions {
-    /** Maintenance scope: line numbers of assertion sites ADDED since the baseline.
+    /** Maintenance scope: the lines of every test function the agent TOUCHED —
+     *  each function containing an assertion added since the baseline, whole.
      *  When set, site-scoped lints only report findings on these lines and
      *  structural (whole-file) lints — including the import lint — are skipped:
-     *  they would flag pre-existing customer code the agent was told not to touch. */
+     *  they would flag pre-existing customer code the agent was told not to touch.
+     *
+     *  Scoped to the touched FUNCTION, not to the added lines alone, because
+     *  MAINTENANCE_SCOPE_NOTE holds a touched test to the same standard as a new
+     *  one. Under line-scoping, the pre-existing `is not None` the note tells the
+     *  agent to upgrade sat outside the scope of every lint, so nothing could
+     *  ever report it (SKYR-4310). Functions the agent left alone stay out —
+     *  that is what the scope is still for. */
     scopeLines?: Set<number>;
 }
+/** Starts of test bodies: JS/TS `it(` / `test(` (with `.only`/`.skip`/`.each`
+ *  modifiers) and Python `def test_`. Two assertions belong to the same test
+ *  only when no such start lies between them — a `const r = …` re-bound in the
+ *  next `it` block is a different response, not the same one. */
+export declare const TEST_START_RE: RegExp;
+/** Offsets of every test-body start in a comment-stripped source, ascending. */
+export declare function testStartOffsets(commentless: string): number[];
+/** Index of the test block an offset falls in — 0 for anything before the
+ *  first start (file preamble), otherwise the 1-based ordinal of the enclosing
+ *  start. Two offsets share a block exactly when this returns the same value. */
+export declare function testBlockIndex(starts: number[], offset: number): number;
+/** Widen a set of individual lines to every line of each test function one of
+ *  them falls in.
+ *
+ *  Two cases deliberately do NOT widen, and both keep their original line:
+ *  a file with no recognizable test start at all (widening would put the whole
+ *  file in scope — the pre-existing customer code the scope exists to keep
+ *  out), and a line before the first test start (module preamble or shared
+ *  setup, which is not a test function and is not what
+ *  `MAINTENANCE_SCOPE_NOTE` holds to the new-test standard). */
+export declare function expandToTestBlocks(commentless: string, lines: Set<number>): Set<number>;
 export declare function lineOfOffset(src: string, offset: number): number;
 /** `\b` breaks on `$`-names, so identifier boundaries use lookarounds. Single
  *  home for the pattern — it is subtle enough that hand-inlined copies drifted

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

@@ -1,4 +1,70 @@
 import { escapeRegExp } from "../regex.js";
+/** Starts of test bodies: JS/TS `it(` / `test(` (with `.only`/`.skip`/`.each`
+ *  modifiers) and Python `def test_`. Two assertions belong to the same test
+ *  only when no such start lies between them — a `const r = …` re-bound in the
+ *  next `it` block is a different response, not the same one. */
+export const TEST_START_RE = /(?<![\w$.])(?:it|test)(?:\s*\.\s*\w+)*\s*\(|^[ \t]*(?:async\s+)?def\s+test_/gm;
+/** Offsets of every test-body start in a comment-stripped source, ascending. */
+export function testStartOffsets(commentless) {
+    const starts = [];
+    TEST_START_RE.lastIndex = 0;
+    let m;
+    while ((m = TEST_START_RE.exec(commentless)) !== null)
+        starts.push(m.index);
+    return starts;
+}
+/** Index of the test block an offset falls in — 0 for anything before the
+ *  first start (file preamble), otherwise the 1-based ordinal of the enclosing
+ *  start. Two offsets share a block exactly when this returns the same value. */
+export function testBlockIndex(starts, offset) {
+    let lo = 0;
+    let hi = starts.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (starts[mid] <= offset)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+/** Widen a set of individual lines to every line of each test function one of
+ *  them falls in.
+ *
+ *  Two cases deliberately do NOT widen, and both keep their original line:
+ *  a file with no recognizable test start at all (widening would put the whole
+ *  file in scope — the pre-existing customer code the scope exists to keep
+ *  out), and a line before the first test start (module preamble or shared
+ *  setup, which is not a test function and is not what
+ *  `MAINTENANCE_SCOPE_NOTE` holds to the new-test standard). */
+export function expandToTestBlocks(commentless, lines) {
+    if (lines.size === 0)
+        return lines;
+    const startLines = testStartOffsets(commentless).map((o) => lineOfOffset(commentless, o));
+    if (startLines.length === 0)
+        return lines;
+    const totalLines = commentless.split("\n").length;
+    const expanded = new Set();
+    const seen = new Set();
+    for (const line of lines) {
+        // startLines is ascending, so the enclosing function is the last start at
+        // or before this line; 0 means the line precedes every test.
+        let block = 0;
+        while (block < startLines.length && startLines[block] <= line)
+            block++;
+        if (block === 0) {
+            expanded.add(line);
+            continue;
+        }
+        if (seen.has(block))
+            continue;
+        seen.add(block);
+        const last = block < startLines.length ? startLines[block] - 1 : totalLines;
+        for (let l = startLines[block - 1]; l <= last; l++)
+            expanded.add(l);
+    }
+    return expanded;
+}
 // One-entry memo of a source's newline offsets: every scanner asks for line
 // numbers of many offsets in the SAME string (assertion sites, lint findings),
 // so counting newlines from index 0 per call was O(n × sites). The memo is

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

@@ -27,4 +27,17 @@ export declare function detectAssertionLanguage(testFile: string): AssertionLang
  * truncated fingerprint) — callers treat that conservatively.
  */
 export declare function subjectOf(fingerprint: string): string | undefined;
+/**
+ * The comparison key for matching a baseline subject against an imported
+ * helper's subject: the property path with the leading receiver identifier
+ * removed (`recordGetResponse.statusCode` and `response.statusCode` both
+ * become `.statusCode`; so does `response?.statusCode`, the optional-chaining
+ * spelling). A helper renames the receiver by construction — the spec names
+ * the response after the call it came from, the helper names it by its own
+ * parameter — so exact subject equality never matched a moved assertion. A
+ * bare identifier, or a subject that does not start with one, is returned
+ * unchanged. Used ONLY for the helper excuse in the removal gate; the in-spec
+ * replaced/removed correlation keeps exact subjects.
+ */
+export declare function helperSubjectKey(subject: string): string;
 export declare function computeAssertionMetrics(content: string, language: AssertionLanguage): AssertionMetrics;

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

@@ -361,6 +361,22 @@ export function subjectOf(fingerprint) {
     }
     return undefined;
 }
+/**
+ * The comparison key for matching a baseline subject against an imported
+ * helper's subject: the property path with the leading receiver identifier
+ * removed (`recordGetResponse.statusCode` and `response.statusCode` both
+ * become `.statusCode`; so does `response?.statusCode`, the optional-chaining
+ * spelling). A helper renames the receiver by construction — the spec names
+ * the response after the call it came from, the helper names it by its own
+ * parameter — so exact subject equality never matched a moved assertion. A
+ * bare identifier, or a subject that does not start with one, is returned
+ * unchanged. Used ONLY for the helper excuse in the removal gate; the in-spec
+ * replaced/removed correlation keeps exact subjects.
+ */
+export function helperSubjectKey(subject) {
+    // `?.` before `[` is consumed whole so `res?.["x"]` keys like `res["x"]`.
+    return subject.replace(/^[A-Za-z_$][\w$]*(?:\?\.(?=\[)|\?)?(?=[.[])/, "");
+}
 export function computeAssertionMetrics(content, language) {
     let sites;
     const { stripped } = strippedSources(content, language);

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

@@ -1,5 +1,5 @@
 import { type AssertionMetrics } from "./metrics.js";
-import type { LintFinding } from "./lint-types.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 {
@@ -36,11 +36,16 @@ export interface AssertionVerifyResult {
     /** 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;
+    /** Assertions were added, but they are PREDOMINANTLY existence/visibility-tier
+     *  (mean weight below `MIN_MEAN_ADDED_WEIGHT`) — 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. */
+    weakAdditionsDominant: boolean;
+    /** Mean weight of the assertions added since the baseline; undefined when
+     *  there is no baseline diff or nothing was added. Reported so the agent can
+     *  see how far a failing file is from the bar. */
+    meanAddedWeight?: number;
     hardFindings: LintFinding[];
     warnings: LintFinding[];
     markerReason?: string;

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

@@ -1,11 +1,20 @@
 import { createHash } from "crypto";
 import { readFile } from "fs/promises";
-import { computeAssertionMetrics, detectAssertionLanguage, subjectOf, } from "./metrics.js";
+import { computeAssertionMetrics, detectAssertionLanguage, helperSubjectKey, subjectOf, } from "./metrics.js";
+import { expandToTestBlocks } from "./lint-types.js";
+import { strippedSources } from "./strip-dispatch.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";
+import { importedHelperSubjectCapacities } from "./helper-imports.js";
+/** The mean weight the assertions added since the baseline must reach.
+ *  Weights are 3 exact / 2 partial-or-format / 1 existence-tier, so 2 means
+ *  "on average at least a format check". A lean enhancement of exact values
+ *  plus a couple of format checks sits near 2.7; a file padded with
+ *  existence-tier assertions falls below 2 however many exact ones it also
+ *  carries. */
+const MIN_MEAN_ADDED_WEIGHT = 2;
 export function sha256Of(content) {
     return createHash("sha256").update(content).digest("hex");
 }
@@ -45,7 +54,7 @@ export async function verifyAssertionEnhancement(params) {
             baselinePresent: baseline !== undefined,
             hashUnchanged,
             strengthGateFailed: false,
-            weakAdditionsOnly: false,
+            weakAdditionsDominant: false,
             hardFindings: [],
             warnings: [],
         };
@@ -88,11 +97,28 @@ export async function verifyAssertionEnhancement(params) {
         });
         // Only pay the helper-file scan when something actually looks removed.
         if (removed.length > 0) {
-            const helperSubjects = await importedHelperSubjects(testFile, content);
+            const helperSubjects = await importedHelperSubjectCapacities(testFile, content);
             if (helperSubjects.size > 0) {
+                // Both sides go through the same key so a helper's renamed receiver
+                // (`response.statusCode` for the spec's `recordGetResponse.statusCode`)
+                // still matches — the exact-subject check above stays exact. Each key
+                // carries a budget (one per call site of the helper asserting it) so
+                // one helper call cannot excuse every removed subject on its path.
+                const budget = new Map();
+                for (const [subject, n] of helperSubjects) {
+                    const key = helperSubjectKey(subject);
+                    budget.set(key, (budget.get(key) ?? 0) + n);
+                }
                 const stillRemoved = removed.filter((fp) => {
                     const subject = subjectOf(fp);
-                    return subject === undefined || !helperSubjects.has(subject);
+                    if (subject === undefined)
+                        return true;
+                    const key = helperSubjectKey(subject);
+                    const left = budget.get(key) ?? 0;
+                    if (left === 0)
+                        return true;
+                    budget.set(key, left - 1);
+                    return false;
                 });
                 movedToHelperCount = removed.length - stillRemoved.length;
                 removed = stillRemoved;
@@ -110,10 +136,13 @@ export async function verifyAssertionEnhancement(params) {
     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.
+    // Maintenance scopes site lints to the test functions the agent TOUCHED —
+    // widened from the added lines to the whole enclosing function, because
+    // MAINTENANCE_SCOPE_NOTE holds a touched test to the same standard as a new
+    // one (SKYR-4310). The baseline fingerprints are what make that diff
+    // computable; functions with no added assertion stay out of scope.
     const scopeLines = enhanceType === "maintenance" && added !== undefined
-        ? new Set(added.map((s) => s.line))
+        ? expandToTestBlocks(strippedSources(content, language).commentless, 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
@@ -164,16 +193,27 @@ export async function verifyAssertionEnhancement(params) {
         strengthDelta !== undefined &&
         strengthDelta <= 0 &&
         !markerAccepted;
-    // Computed-values rubric: additions must not be exclusively existence/
+    // Computed-values rubric: additions must not be predominantly 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) &&
+    //
+    // The bar is the MEAN added weight, not "every addition is weak". The
+    // all-weak form let one exact assertion license unlimited padding: 5 exact
+    // + 40 `not.toBeNull()` passed, and scored HIGHER than the 5 alone, because
+    // strengthScore is a sum. That is a quota, and it points the opposite way
+    // from the rules the agent is handed, which ask it to assert the behaviour
+    // under test and leave the rest of the body alone (SKYR-4310). Averaging
+    // removes the payoff for padding without capping assertion count — a budget
+    // is not knowable from the file.
+    const meanAddedWeight = added !== undefined && added.length > 0
+        ? added.reduce((sum, s) => sum + s.weight, 0) / added.length
+        : undefined;
+    const weakAdditionsDominant = language !== "java" &&
+        meanAddedWeight !== undefined &&
+        meanAddedWeight < MIN_MEAN_ADDED_WEIGHT &&
         !markerAccepted;
     // The hash gate ("byte-identical → nothing applied") is generation-only: in
     // maintenance the file edits precede the enhance call, and "no assertion
@@ -194,7 +234,7 @@ export async function verifyAssertionEnhancement(params) {
             !removalGateFailed &&
             hardFindings.length === 0 &&
             !strengthGateFailed &&
-            !weakAdditionsOnly,
+            !weakAdditionsDominant,
         maintenanceNoAssertionChanges,
         enhanceType,
         baselinePresent: baseline !== undefined,
@@ -206,7 +246,8 @@ export async function verifyAssertionEnhancement(params) {
         baselineFilePath: baseline?.baselineFilePath,
         strengthDelta,
         strengthGateFailed,
-        weakAdditionsOnly,
+        weakAdditionsDominant,
+        meanAddedWeight,
         hardFindings,
         warnings: findings.filter((f) => f.severity === "warn"),
         markerReason: markerAccepted ? marker?.reason : undefined,

package/build/utils/canonicalJson.d.ts

@@ -0,0 +1,11 @@
+/** Whether a value is a plain object — not null, not an array — so its keys can
+ *  be read and sorted. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** One value as text with object keys sorted, so the same value written twice by
+ *  hand is not a difference merely because its keys are ordered differently. List
+ *  order still counts: two orders are two different lists.
+ *
+ *  UNDEFINED for a value `JSON.stringify` renders as nothing — `undefined` itself,
+ *  a function, a symbol. Callers that compare two results must know a pair of
+ *  those reads as equal. */
+export declare function canonicalJson(value: unknown): string | undefined;

package/build/utils/canonicalJson.js

@@ -0,0 +1,17 @@
+/** Whether a value is a plain object — not null, not an array — so its keys can
+ *  be read and sorted. */
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** One value as text with object keys sorted, so the same value written twice by
+ *  hand is not a difference merely because its keys are ordered differently. List
+ *  order still counts: two orders are two different lists.
+ *
+ *  UNDEFINED for a value `JSON.stringify` renders as nothing — `undefined` itself,
+ *  a function, a symbol. Callers that compare two results must know a pair of
+ *  those reads as equal. */
+export function canonicalJson(value) {
+    return JSON.stringify(value, (_key, entry) => isPlainObject(entry)
+        ? Object.fromEntries(Object.keys(entry).sort().map((key) => [key, entry[key]]))
+        : entry);
+}

package/build/utils/utils-verify/action-key.d.ts

@@ -0,0 +1,27 @@
+import type { UtilsLanguage } from "./language-spec.js";
+/**
+ * The comparison key of a browser helper: the analogue of `method + path` for a
+ * helper that sends no request. One step per action, in body order: the verb plus
+ * the LOCATOR CHAIN the action is called on, as written — the prompt's own
+ * definition of a browser duplicate is "same primitives in the same order,
+ * selectors identical", and that is a textual identity, not a set of tokens. So
+ * `getByRole("heading", { level: 1 })` and `{ level: 2 }` differ, `getByTestId("x")`
+ * and `getByText("x")` differ, `a.getByText("b")` and `b.getByText("a")` differ, and
+ * `.first()` / `.nth(2)` count. Formatting does not: whitespace and braces outside
+ * strings are dropped and quotes normalised, so a Prettier-wrapped chain and its
+ * one-line twin key the same. Argument VALUES are not part of the key, except a
+ * `goto` target and a `dragTo` destination, which are the identity of those steps.
+ * The legacy page-level form (`page.click("#save")`) is keyed on its selector
+ * argument.
+ *
+ * `undefined` when the helper performs no action, or when any action's locator is
+ * not built from plain string literals (a template literal, a variable, a regex, an
+ * f-string): a sequence with an unreadable step is not comparable. A `goto` target
+ * may be a template literal, keyed on its text with the interpolation kept: the
+ * generated `${baseUrl}/…` prefix names one module constant.
+ *
+ * `body` is the helper source with comments blanked and strings kept. Playwright for
+ * Python is read through the JavaScript spelling (see toPlaywrightJs), so the same
+ * helper in either language gets the same key.
+ */
+export declare function actionKeyOf(body: string, language?: UtilsLanguage): string | undefined;