@skyramp/mcp 0.3.6 → 0.3.8

package/build/utils/planOnlyMode.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Plan-only mode capture for `skyramp_submit_report` (SKYR-4250).
+ *
+ * A plan-only eval run (SKYR-3879) writes no test files: `newTestsCreated`
+ * DECLARES the approved GENERATE selection instead of recording generated
+ * files, and the declaration itself is the deliverable. The SKYR-3883 guard
+ * (`findUnchangedFileClaims`) verifies every `newTestsCreated` claim against
+ * the working tree, so in that lane EVERY declaration is unbacked by
+ * construction and the report is rejected.
+ *
+ * That rejection is not evenly distributed. `findUnchangedFileClaims` exempts a
+ * claim attributed to a non-primary repo, so on a cross-repo fixture the
+ * related repo's declarations pass and only the primary repo's are checked.
+ * On a frontend-primary pair that makes the mandatory UI item (SKYR-4204's
+ * floor) the one claim that always fails, and the agent's only compliant move
+ * is to demote it to `additionalRecommendations` — which is exactly the
+ * under-declaration SKYR-4250 exists to fix (run 32903633247).
+ *
+ * `planOnly` reaches the server only as a testbot prompt/resource arg, so this
+ * mirrors the SKYR-4185 report-language capture: the prompt render is the
+ * single capture point, and the report tool reads the captured mode later in
+ * the same process.
+ *
+ * Capture is fail-open by design: if the testbot prompt was never served, the
+ * mode stays false and the guard behaves exactly as it does today.
+ */
+/** Capture plan-only mode at prompt-serve time. Last render wins: a later
+ *  non-plan-only render disarms a mode captured earlier in a long-lived server
+ *  process, so an ordinary run never silently skips the guard. */
+export declare function setPlanOnlyMode(planOnly: boolean): void;
+export declare function isPlanOnlyMode(): boolean;
+/** Test isolation only — module state persists across tests in one process. */
+export declare function resetPlanOnlyMode(): void;

package/build/utils/planOnlyMode.js

@@ -0,0 +1,40 @@
+/**
+ * Plan-only mode capture for `skyramp_submit_report` (SKYR-4250).
+ *
+ * A plan-only eval run (SKYR-3879) writes no test files: `newTestsCreated`
+ * DECLARES the approved GENERATE selection instead of recording generated
+ * files, and the declaration itself is the deliverable. The SKYR-3883 guard
+ * (`findUnchangedFileClaims`) verifies every `newTestsCreated` claim against
+ * the working tree, so in that lane EVERY declaration is unbacked by
+ * construction and the report is rejected.
+ *
+ * That rejection is not evenly distributed. `findUnchangedFileClaims` exempts a
+ * claim attributed to a non-primary repo, so on a cross-repo fixture the
+ * related repo's declarations pass and only the primary repo's are checked.
+ * On a frontend-primary pair that makes the mandatory UI item (SKYR-4204's
+ * floor) the one claim that always fails, and the agent's only compliant move
+ * is to demote it to `additionalRecommendations` — which is exactly the
+ * under-declaration SKYR-4250 exists to fix (run 32903633247).
+ *
+ * `planOnly` reaches the server only as a testbot prompt/resource arg, so this
+ * mirrors the SKYR-4185 report-language capture: the prompt render is the
+ * single capture point, and the report tool reads the captured mode later in
+ * the same process.
+ *
+ * Capture is fail-open by design: if the testbot prompt was never served, the
+ * mode stays false and the guard behaves exactly as it does today.
+ */
+let sessionPlanOnly = false;
+/** Capture plan-only mode at prompt-serve time. Last render wins: a later
+ *  non-plan-only render disarms a mode captured earlier in a long-lived server
+ *  process, so an ordinary run never silently skips the guard. */
+export function setPlanOnlyMode(planOnly) {
+    sessionPlanOnly = planOnly;
+}
+export function isPlanOnlyMode() {
+    return sessionPlanOnly;
+}
+/** Test isolation only — module state persists across tests in one process. */
+export function resetPlanOnlyMode() {
+    sessionPlanOnly = false;
+}

package/build/utils/reportVerification.d.ts

@@ -24,6 +24,10 @@ import { DriftAction } from "../types/TestAnalysis.js";
  * nothing rather than failing the whole check.
  */
 export declare function listChangedFilesAcross(roots: Array<string | undefined>): Promise<string[]>;
+/** Like listChangedFilesAcross, but ABSOLUTE: each changed path resolved against
+ *  the root it came from, so a consumer never has to guess which checkout a
+ *  repo-relative path belongs to. */
+export declare function listChangedFilesAbs(roots: Array<string | undefined>): Promise<string[]>;
 export declare function listChangedFiles(repoRoot: string): Promise<string[]>;
 export interface UnchangedFileClaimsInput {
     /** Absolute path of the primary repo checkout the report pertains to. */
@@ -46,6 +50,11 @@ export interface UnchangedFileClaimsInput {
     /** owner/repo of the primary repo — used to exempt cross-repo newTest claims
      *  whose files live in a different checkout. */
     primaryRepository?: string;
+    /** SKYR-4250: a plan-only eval run generates nothing — `newTestsCreated`
+     *  declares the approved GENERATE list — so no declaration can be backed by
+     *  a working-tree change. Exempts the declaration half only; a maintenance
+     *  UPDATE still claims a real edit and is still verified. */
+    planOnly?: boolean;
 }
 /**
  * Cross-check report claims against files that actually changed in the working

package/build/utils/reportVerification.js

@@ -51,6 +51,26 @@ export async function listChangedFilesAcross(roots) {
     }
     return files;
 }
+/** Like listChangedFilesAcross, but ABSOLUTE: each changed path resolved against
+ *  the root it came from, so a consumer never has to guess which checkout a
+ *  repo-relative path belongs to. */
+export async function listChangedFilesAbs(roots) {
+    const seenRoots = new Set();
+    const files = [];
+    for (const root of roots) {
+        if (!root || seenRoots.has(root))
+            continue;
+        seenRoots.add(root);
+        try {
+            for (const f of await listChangedFiles(root))
+                files.push(path.resolve(root, f));
+        }
+        catch {
+            // Non-git or missing tree — nothing to contribute.
+        }
+    }
+    return files;
+}
 export async function listChangedFiles(repoRoot) {
     const { stdout } = await execFileAsync("git", ["status", "--porcelain", "-z", "--untracked-files=all"], { cwd: repoRoot });
     const files = [];
@@ -104,7 +124,7 @@ export async function listChangedFiles(repoRoot) {
  *    absolute path resolving outside `repoRoot`) — a different checkout owns them.
  */
 export function findUnchangedFileClaims(input) {
-    const { repoRoot, changedFiles, newTests, verdicts, primaryRepository } = input;
+    const { repoRoot, changedFiles, newTests, verdicts, primaryRepository, planOnly, } = input;
     const unbacked = [];
     const isBacked = (claimedPath) => {
         let candidate = claimedPath;
@@ -117,7 +137,12 @@ export function findUnchangedFileClaims(input) {
         }
         return changedFiles.some((c) => testFileMatches(c, candidate));
     };
-    for (const t of newTests) {
+    // A plan-only run declares its GENERATE list instead of writing files, so
+    // skip the claim scan wholesale rather than per-claim: checking it rejects
+    // every declaration the guard can see, and the ones it CANNOT see (cross-repo
+    // claims, exempted below) would pass — demoting the primary repo's items
+    // alone. Uneven enforcement is worse than none here.
+    for (const t of planOnly ? [] : newTests) {
         if (!t.fileName)
             continue;
         // Cross-repo finding — its file lives in a different checkout, not this tree.
@@ -273,7 +298,9 @@ export async function findInvalidSourceCitations(input) {
                 continue; // Could not look — accept.
             const suggestions = await suggestSimilarPaths(roots, cited);
             invalid.push(`issuesFound[${i}] cites ${cited} but that file does not exist in the repository` +
-                (suggestions.length > 0 ? ` (closest matches: ${suggestions.join(", ")})` : "") +
+                (suggestions.length > 0
+                    ? ` (closest matches: ${suggestions.join(", ")})`
+                    : "") +
                 `. ${CITATION_REMEDY}`);
             continue;
         }
@@ -322,7 +349,9 @@ export async function findInvalidSourceCitations(input) {
  *  A checkout the run could not name contributes nothing: it can be neither
  *  stamped nor offered as a candidate. */
 function namesOf(resolved) {
-    return [...new Set(resolved.map((c) => c.repository).filter((r) => !!r))];
+    return [
+        ...new Set(resolved.map((c) => c.repository).filter((r) => !!r)),
+    ];
 }
 /**
  * Reconcile where a citation resolved with what the entry says about it, giving
@@ -339,7 +368,9 @@ function attributeCitation(args) {
         // than sent back for a rewrite that would change nothing.
         const match = resolved.find((c) => c.repository && c.repository.toLowerCase() === declared.toLowerCase());
         if (match)
-            return match.repository === declared ? {} : { repository: match.repository };
+            return match.repository === declared
+                ? {}
+                : { repository: match.repository };
         // It resolved somewhere else. Only say so when the run can name where —
         // otherwise there is nothing to correct the attribution to.
         if (names.length === 0)
@@ -362,5 +393,7 @@ function attributeCitation(args) {
     // Exactly one checkout. Stamp it unless it is the primary, whose findings are
     // identified downstream by having NO repository — see SourceCitationCheck.
     const [only] = resolved;
-    return only.primary || !only.repository ? {} : { repository: only.repository };
+    return only.primary || !only.repository
+        ? {}
+        : { repository: only.repository };
 }

package/build/utils/scenarioDrafting.d.ts

@@ -46,7 +46,7 @@ export declare function draftScenariosFromEndpoints(endpoints: Array<EndpointInp
 /**
  * Enforce a global cap on drafted scenarios while preserving category diversity.
  *
- * 1. CRITICAL (bug_caught) scenarios prioritized first.
+ * 1. CRITICAL (bug_caught, requirement_conflict) scenarios prioritized first.
  * 2. One scenario per non-empty category guaranteed (breadth).
  * 3. Remaining budget filled by priority tier (HIGH > MEDIUM > LOW).
  * 4. Hard cap at MAX_TOTAL_SCENARIOS — applied to the combined output.

package/build/utils/scenarioDrafting.js

@@ -226,7 +226,7 @@ const TIER_ORDER = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1 };
 /**
  * Enforce a global cap on drafted scenarios while preserving category diversity.
  *
- * 1. CRITICAL (bug_caught) scenarios prioritized first.
+ * 1. CRITICAL (bug_caught, requirement_conflict) scenarios prioritized first.
  * 2. One scenario per non-empty category guaranteed (breadth).
  * 3. Remaining budget filled by priority tier (HIGH > MEDIUM > LOW).
  * 4. Hard cap at MAX_TOTAL_SCENARIOS — applied to the combined output.

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

@@ -1,13 +1,31 @@
 import type { UtilsLanguageSpec } from "./language-spec.js";
-export type UtilsViolationKind = "duplicate-helper" | "body-assertion" | "scenario-name";
-export declare const UTILS_VIOLATION_KINDS: readonly UtilsViolationKind[];
+export type UtilsViolationKind = "duplicate-helper" | "body-assertion" | "scenario-name"
+/** The delivered spec (plus the helpers it imports) holds fewer assertions than at
+ *  the modularization hand-out. Marker-eligible: a deliberate consolidation is
+ *  legitimate once documented. */
+ | "assertion-loss"
+/** A page-error/console guard present at hand-out is gone. Not marker-eligible. */
+ | "guard-removed"
+/** Python only: the spec imports the shared module in a form that cannot resolve
+ *  in the customer's repo. Not marker-eligible — a broken import has no reason to
+ *  stay. */
+ | "import-form";
+/** Kinds that only ever advise. Kept OUT of UtilsViolationKind so that type keeps
+ *  meaning "a kind the allow grammar and the gate know about" — an advisory can
+ *  never fail a verify and never needs (or accepts) an allow marker. */
+export type UtilsAdvisoryKind = "untyped-parameter";
+export declare const MARKERABLE_UTILS_KINDS: readonly ["duplicate-helper", "body-assertion", "scenario-name", "assertion-loss"];
+/** A kind the allow grammar accepts. `guard-removed` is a gate kind but never
+ *  markerable — a guard is restored, not documented away — so the grammar itself
+ *  cannot spell it; the regex below is built from this list. */
+export type MarkerableUtilsKind = (typeof MARKERABLE_UTILS_KINDS)[number];
 export interface UtilsAllow {
-    kind: UtilsViolationKind;
+    kind: MarkerableUtilsKind;
     helper: string;
     reason: string;
 }
 /** The exact line to paste for a violation — what the failure text hands the agent. */
-export declare function allowMarkerLine(spec: UtilsLanguageSpec, kind: UtilsViolationKind, helper: string): string;
+export declare function allowMarkerLine(spec: UtilsLanguageSpec, kind: MarkerableUtilsKind, helper: string): string;
 export declare function parseUtilsAllows(content: string, spec: UtilsLanguageSpec): {
     allows: UtilsAllow[];
     /** Marker lines the loose pattern recognises but the grammar cannot read — a decline

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

@@ -1,8 +1,9 @@
 import { blankStrings } from "./parse.js";
-export const UTILS_VIOLATION_KINDS = [
+export const MARKERABLE_UTILS_KINDS = [
     "duplicate-helper",
     "body-assertion",
     "scenario-name",
+    "assertion-loss",
 ];
 /**
  * The documented-decline marker for a utils-file invariant, written in the utils file:
@@ -21,7 +22,7 @@ export const UTILS_VIOLATION_KINDS = [
  * paste-ready line from the failure text when it was pasted unedited: publishing the
  * placeholder as the stated reason is worse than no marker.
  */
-const ALLOW_RE = /reuse-verify:\s*allow\s+(duplicate-helper|body-assertion|scenario-name)\s+([A-Za-z_$][\w$]*)\s*(?:[—–]+|\s+-+\s+)\s*(?!<reason)(\S.*?)\s*$/;
+const ALLOW_RE = new RegExp(`reuse-verify:\\s*allow\\s+(${MARKERABLE_UTILS_KINDS.join("|")})\\s+([A-Za-z_$][\\w$]*)\\s*(?:[—–]+|\\s+-+\\s+)\\s*(?!<reason)(\\S.*?)\\s*$`);
 const ALLOW_LOOSE_RE = /reuse-verify:\s*allow\b/;
 /** The exact line to paste for a violation — what the failure text hands the agent. */
 export function allowMarkerLine(spec, kind, helper) {
@@ -55,6 +56,11 @@ export function parseUtilsAllows(content, spec) {
             .trim();
         const m = ALLOW_RE.exec(line);
         if (!m) {
+            // A marker naming an advisory kind is inert, not malformed: advisories never
+            // block, so "documenting" one must not fail the gate either (the agent sees
+            // the kind in a kind-shaped slot and reasonably tries).
+            if (/allow\s+untyped-parameter\b/.test(code))
+                continue;
             malformed.push(raw.trim());
             continue;
         }

package/build/utils/utils-verify/call-sites.d.ts

@@ -4,6 +4,23 @@ import { type UtilsLanguageSpec } from "./language-spec.js";
  *  Skyramp v<version>`), as opposed to the utils header (`Generated by Skyramp on …`).
  *  The same discriminator STEP 4 of the reuse prompt hands the agent. */
 export declare const CODEGEN_MARKER_RE: RegExp;
+/** One Skyramp-generated test beside the spec, read once. */
+export interface SiblingFile {
+    /** Absolute path. */
+    file: string;
+    content: string;
+}
+/**
+ * The Skyramp-generated tests in the spec's directory, each read once — THE sibling
+ * walk, shared by the inline-call-site scan (which excludes the spec itself) and the
+ * importer count (which includes it). Utils files carry no codegen version marker,
+ * so the marker check alone excludes them. Fails open to [] on any read error.
+ */
+export declare function generatedSiblings(testFile: string, spec: UtilsLanguageSpec, opts: {
+    includeSelf: boolean;
+}): Promise<SiblingFile[]>;
+/** An SDK request call. Global: clone with `new RegExp(...)` before `matchAll`. */
+export declare const REQUEST_CALL_RE: RegExp;
 export interface InlineCallSite {
     /** Absolute path of the sibling test. */
     file: string;
@@ -28,7 +45,29 @@ export interface InlineCallSite {
  * Advisory by design: it names a change to a PRE-EXISTING test, which the maintenance
  * flow owns, so it informs rather than gates. Never throws.
  */
-export declare function findSiblingInlineCallSites(testFile: string, utilsFiles: string[], _helpers: UtilsHelper[], spec: UtilsLanguageSpec): Promise<InlineCallSite[]>;
+export declare function findSiblingInlineCallSites(testFile: string, utilsFiles: string[], _helpers: UtilsHelper[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<InlineCallSite[]>;
+/** Lines after a call scanned for its schema assertion — the generated shape puts it
+ *  immediately after the status-code assertion. */
+export declare const SCHEMA_SCAN_LINES = 12;
+/** True when a `check_schema` / `checkSchema` assertion sits in the given 1-based line
+ *  range — the response-shape contract a status-only helper does not carry. */
+export declare function hasSchemaCheck(content: string, from: number, to: number): boolean;
+/**
+ * The request's body/override FIELD names — leaf names only, so a dotted override key
+ * (`posts.0.publish_at`) and the body literal it targets (`"publish_at":`) are one
+ * field. Reads the body through its variable: generated code assigns the template to
+ * an identifier and passes `body=<ident>`, so the fields live in the assignment, not
+ * in the call.
+ *
+ * `callAt` is the call's offset in `content`. The body variable resolves to the
+ * assignment NEAREST BEFORE it, because generated code reuses the name `body` per
+ * request: a file-wide first match gives every later request the first one's fields,
+ * so two different payloads compare equal. Omit it only when `content` holds a single
+ * request.
+ */
+export declare function requestFields(content: string, call: string, callAt?: number): Set<string>;
 /** The keyword names of a request call (`path=`, `method=`, `query_params=` … / TS
  *  object keys), less the liftable ones — a cheap normalised call shape. */
 export declare function shapeKeys(call: string): Set<string>;
+/** Text of the parenthesised argument list starting at the `(` at `open`. */
+export declare function callText(content: string, open: number): string;

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

@@ -4,12 +4,52 @@ import { SKYRAMP_UTILS_HEADER } from "../utils.js";
 import { parseUtilsFile } from "./parse.js";
 import { normalizePath } from "./language-spec.js";
 import { realpath } from "./locate.js";
+import { escapeRegExp } from "../regex.js";
 /** The codegen marker every Skyramp-GENERATED TEST carries on line 1 (`Generated by
  *  Skyramp v<version>`), as opposed to the utils header (`Generated by Skyramp on …`).
  *  The same discriminator STEP 4 of the reuse prompt hands the agent. */
 export const CODEGEN_MARKER_RE = new RegExp(`${SKYRAMP_UTILS_HEADER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s+v\\d`);
 const HEADER_SCAN_LINES = 5;
-const REQUEST_CALL_RE = /\b(?:send_request|sendRequest)\s*\(/g;
+/**
+ * The Skyramp-generated tests in the spec's directory, each read once — THE sibling
+ * walk, shared by the inline-call-site scan (which excludes the spec itself) and the
+ * importer count (which includes it). Utils files carry no codegen version marker,
+ * so the marker check alone excludes them. Fails open to [] on any read error.
+ */
+export async function generatedSiblings(testFile, spec, opts) {
+    let dir;
+    let entries;
+    let self;
+    try {
+        self = await realpath(testFile);
+        dir = path.dirname(self);
+        entries = await fs.promises.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries.sort()) {
+        const file = path.join(dir, name);
+        if (!spec.extensions.some((e) => name.toLowerCase().endsWith(e)))
+            continue;
+        if (!opts.includeSelf && path.resolve(file) === self)
+            continue;
+        let content;
+        try {
+            content = await fs.promises.readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!CODEGEN_MARKER_RE.test(content.split("\n").slice(0, HEADER_SCAN_LINES).join("\n")))
+            continue;
+        out.push({ file, content });
+    }
+    return out;
+}
+/** An SDK request call. Global: clone with `new RegExp(...)` before `matchAll`. */
+export const REQUEST_CALL_RE = /\b(?:send_request|sendRequest)\s*\(/g;
 /**
  * Inline request calls in OTHER Skyramp-generated tests beside `testFile` that a
  * utils helper already wraps — the reuse the prompt asks for and the agent does not
@@ -24,10 +64,12 @@ const REQUEST_CALL_RE = /\b(?:send_request|sendRequest)\s*\(/g;
  * Advisory by design: it names a change to a PRE-EXISTING test, which the maintenance
  * flow owns, so it informs rather than gates. Never throws.
  */
-export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers, spec) {
+export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers, spec, preReadSiblings) {
     // route → helper name + the keyword set of the helper's own request call, so a
     // sibling call is reported only when its SHAPE matches too (same keywords once the
     // liftable ones are set aside) — criterion 2 of the API near-duplicate definition.
+    // `fields` and `schemaChecked` carry the two things keyword shape cannot see; see
+    // substitutable().
     const byRoute = new Map();
     for (const utilsFile of utilsFiles) {
         let content;
@@ -50,39 +92,20 @@ export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers,
             byRoute.set(`${owner.method} ${owner.normalizedPath}`, {
                 helper: owner.name,
                 keys: shapeKeys(call),
+                fields: requestFields(content, call, start),
+                schemaChecked: hasSchemaCheck(content, owner.line, owner.endLine),
             });
         }
     }
     if (byRoute.size === 0)
         return [];
-    // Canonical, like the utils paths: otherwise a tool-supplied /tmp path and a
-    // realpath'd /private/tmp utils file look like different directories to the renderer.
-    const dir = path.dirname(await realpath(testFile));
-    // Canonical like `dir`, or a spec reached through a symlink is reported as its
-    // own sibling.
-    const exclude = new Set(await Promise.all([testFile, ...utilsFiles].map((f) => realpath(f))));
-    let entries;
-    try {
-        entries = await fs.promises.readdir(dir);
-    }
-    catch {
-        return [];
-    }
+    const utilsSet = new Set(await Promise.all(utilsFiles.map((f) => realpath(f))));
+    const siblings = (preReadSiblings ??
+        (await generatedSiblings(testFile, spec, { includeSelf: false }))).filter((sib) => !utilsSet.has(path.resolve(sib.file)));
+    const self = await realpath(testFile);
     const out = [];
-    for (const name of entries.sort()) {
-        const file = path.join(dir, name);
-        if (exclude.has(path.resolve(file)))
-            continue;
-        if (!spec.extensions.some((e) => name.toLowerCase().endsWith(e)))
-            continue;
-        let content;
-        try {
-            content = await fs.promises.readFile(file, "utf8");
-        }
-        catch {
-            continue;
-        }
-        if (!CODEGEN_MARKER_RE.test(content.split("\n").slice(0, HEADER_SCAN_LINES).join("\n")))
+    for (const { file, content } of siblings) {
+        if (path.resolve(file) === self)
             continue;
         // Line ranges of the sibling's own non-test helpers: calls inside them are not inline.
         const localHelpers = parseUtilsFile(content, spec).filter((h) => !/^test/i.test(h.name));
@@ -102,11 +125,154 @@ export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers,
                 continue;
             if (!sameShape(shapeKeys(call), match.keys))
                 continue;
+            if (!substitutable(match, {
+                fields: requestFields(content, call, start),
+                schemaChecked: hasSchemaCheck(content, line, line + SCHEMA_SCAN_LINES),
+            }))
+                continue;
             out.push({ file, line, method, path: p, helper: match.helper });
         }
     }
     return out;
 }
+/**
+ * Whether the helper can stand in for this call site with LITERALS as the only
+ * difference — the condition the advisory itself states. Keyword shape (`sameShape`)
+ * cannot see either of these, and both were measured naming sites an agent then
+ * correctly declined, which trains it to ignore the advisory:
+ *
+ *  - **Fields the site does not carry.** A helper whose body/override sets
+ *    `publish_at` cannot replace a POST whose body has only `status` and `title`:
+ *    substituting ADDS a field, changing the sibling's request. `body` and
+ *    `dataOverride` are liftable *keywords*, so their mere presence matched; their
+ *    contents never got compared. (ghost `pr-scheduled-publishing`: a scheduled-post
+ *    helper offered for a draft-post call, declined for exactly this reason.)
+ *  - **A schema-checked site.** When the site feeds its response to `check_schema`
+ *    against a per-file expected body and the helper wraps no such check, replacing
+ *    the block either drops the contract assertion or redesigns the file. That is a
+ *    structural difference, not a literal one. (demoshop `P08`: the contract-file
+ *    sites, declined as "a design change beyond this PR's scope".)
+ *
+ * Both directions are conservative — they only ever drop a candidate — so precision
+ * rises and the advisory cannot start over-reporting because of them.
+ */
+function substitutable(helper, site) {
+    for (const f of helper.fields)
+        if (!site.fields.has(f))
+            return false;
+    return helper.schemaChecked === site.schemaChecked;
+}
+/** Lines after a call scanned for its schema assertion — the generated shape puts it
+ *  immediately after the status-code assertion. */
+export const SCHEMA_SCAN_LINES = 12;
+/** True when a `check_schema` / `checkSchema` assertion sits in the given 1-based line
+ *  range — the response-shape contract a status-only helper does not carry. */
+export function hasSchemaCheck(content, from, to) {
+    const lines = content.split("\n").slice(Math.max(0, from - 1), to);
+    return /\bcheck_?[Ss]chema\s*\(/.test(lines.join("\n"));
+}
+/**
+ * The request's body/override FIELD names — leaf names only, so a dotted override key
+ * (`posts.0.publish_at`) and the body literal it targets (`"publish_at":`) are one
+ * field. Reads the body through its variable: generated code assigns the template to
+ * an identifier and passes `body=<ident>`, so the fields live in the assignment, not
+ * in the call.
+ *
+ * `callAt` is the call's offset in `content`. The body variable resolves to the
+ * assignment NEAREST BEFORE it, because generated code reuses the name `body` per
+ * request: a file-wide first match gives every later request the first one's fields,
+ * so two different payloads compare equal. Omit it only when `content` holds a single
+ * request.
+ */
+export function requestFields(content, call, callAt) {
+    const out = new Set();
+    const add = (raw) => {
+        const leaf = raw.split(".").pop() ?? "";
+        // Array indices are positions, not fields.
+        if (leaf && !/^\d+$/.test(leaf))
+            out.add(leaf);
+    };
+    // FIELDS COME FROM THE PAYLOAD ONLY. Every other liftable argument carries quoted
+    // keys of its own that are not body fields: `path_params={"orders": id}` names a
+    // placeholder (the same `{}` in the same normalised path), `headers={"Authorization":
+    // t}` names a header, `query_params={"page": 1}` a query key. Reading any of them as
+    // a field reports a correct retrofit as changing the request — measured on a demoshop
+    // DELETE whose helper labelled the path parameter `orders` where the baseline said
+    // `order_id`. shapeKeys already ignores these keywords; ignoring the keyword while
+    // reading its contents was the incoherence. `body` and `data_override` stay, because
+    // their keys ARE payload paths.
+    const body = call.replace(/\b(?:path_params|pathParams|query_params|queryParams|headers|url)\s*[=:]\s*\{[^{}]*\}/g, " ");
+    // Dotted override keys, and any body literal written inline in the call.
+    for (const m of body.matchAll(/["'`]([A-Za-z_][\w.]*)["'`]\s*:/g))
+        add(m[1]);
+    // TS shorthand inside an override object — `dataOverride: { status, title }` names
+    // the same fields as `{ "status": status }` but carries neither quotes nor a colon,
+    // so the pattern above cannot see it and the field would compare as absent.
+    for (const region of overrideObjects(body))
+        for (const m of region.matchAll(/(?:^|[{,])\s*([A-Za-z_$][\w$]*)\s*(?=[,}])/g))
+            add(m[1]);
+    // `body=IDENT` / `body: IDENT` → the identifier's assignment elsewhere in the file.
+    const ref = /\bbody\s*[=:]\s*([A-Za-z_$][\w$]*)/.exec(call);
+    if (ref) {
+        const assignRe = new RegExp(`\\b${escapeRegExp(ref[1])}\\b\\s*(?::[^=]*)?=`, "g");
+        // The last assignment before the call; the first in the file when the offset is
+        // unknown or nothing precedes it.
+        let assign = null;
+        for (const m of content.matchAll(assignRe)) {
+            if (callAt !== undefined && (m.index ?? 0) > callAt)
+                break;
+            assign = m;
+            if (callAt === undefined)
+                break;
+        }
+        if (assign) {
+            // From the assignment to the end of its braced literal — the template is one
+            // string, so the first balanced `{`…`}` after it is the body.
+            const tail = content.slice(assign.index + assign[0].length);
+            const open = tail.indexOf("{");
+            if (open !== -1) {
+                let depth = 0;
+                let end = tail.length;
+                for (let i = open; i < tail.length; i++) {
+                    if (tail[i] === "{")
+                        depth++;
+                    else if (tail[i] === "}") {
+                        depth--;
+                        if (depth === 0) {
+                            end = i + 1;
+                            break;
+                        }
+                    }
+                }
+                for (const m of tail
+                    .slice(open, end)
+                    .matchAll(/["'`]([A-Za-z_][\w.]*)["'`]\s*:/g))
+                    add(m[1]);
+            }
+        }
+    }
+    return out;
+}
+/** The `{…}` text of each `data_override` / `dataOverride` argument in a call. */
+function overrideObjects(call) {
+    const out = [];
+    for (const m of call.matchAll(/\b(?:data_override|dataOverride)\s*[=:]\s*\{/g)) {
+        const open = (m.index ?? 0) + m[0].length - 1;
+        let depth = 0;
+        for (let i = open; i < call.length; i++) {
+            if (call[i] === "{")
+                depth++;
+            else if (call[i] === "}") {
+                depth--;
+                if (depth === 0) {
+                    out.push(call.slice(open, i + 1));
+                    break;
+                }
+            }
+        }
+    }
+    return out;
+}
 /** Keywords whose presence differs legitimately between two versions of one request:
  *  the literals the merge rule lifts to parameters. Everything else is call shape. */
 const LIFTABLE_KEYS = new Set([
@@ -138,7 +304,7 @@ function sameShape(a, b) {
     return true;
 }
 /** Text of the parenthesised argument list starting at the `(` at `open`. */
-function callText(content, open) {
+export function callText(content, open) {
     let depth = 0;
     for (let i = open; i < content.length; i++) {
         const ch = content[i];

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

@@ -0,0 +1,31 @@
+import { type SiblingFile } from "./call-sites.js";
+import type { UtilsHelper } from "./parse.js";
+import type { UtilsLanguageSpec } from "./language-spec.js";
+/** A helper imported by at most one delivered test. */
+export interface SingleImporterHelper {
+    /** Absolute path of the utils file. */
+    file: string;
+    helper: string;
+    line: number;
+    /** Delivered tests importing it (0 or 1). */
+    importers: number;
+}
+/** The strings a sibling's source would contain if it imports the module at
+ *  `modulePath` (relative to the sibling's directory): the path form for TS/JS
+ *  specifiers, and the dotted Python form — `../shared/X` → `..shared.X`,
+ *  `shared/X` → `shared.X` / `.shared.X`. */
+export declare function moduleMentionCandidates(modulePath: string): string[];
+/**
+ * Count, per utils helper, how many Skyramp-generated tests in the spec's directory
+ * import it — the spec under verification included.
+ *
+ * Findings:
+ * - 0 importers: nothing imports the helper, not even the spec that wrote it — a
+ *   dead helper, actionable on any run.
+ * - 1 importer: not (yet) shared. Reported only when the directory holds at least
+ *   TWO delivered tests: on a first run every helper has exactly one importer by
+ *   construction (it seeds the utils file), so listing them would be guaranteed
+ *   noise on the most common path.
+ * Fails open to "no findings" on any read error.
+ */
+export declare function singleImporterHelpers(testFile: string, utilsFiles: string[], helpersByFile: ReadonlyMap<string, UtilsHelper[]>, spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<SingleImporterHelper[]>;