@skyramp/mcp 0.3.2-rc.pom-4 → 0.3.3

package/build/utils/httpMethodValidation.js

@@ -0,0 +1,15 @@
+import { HttpMethod } from "../types/TestTypes.js";
+export const REST_MOCK_HTTP_METHODS = Object.values(HttpMethod);
+export function normalizeRestMockMethod(method) {
+    return method ? method.trim().toUpperCase() : "";
+}
+export function getRestMockMethodValidationError(method) {
+    if (!method)
+        return null;
+    const normalized = normalizeRestMockMethod(method);
+    if (!normalized)
+        return null; // whitespace-only → treated as empty (valid)
+    if (REST_MOCK_HTTP_METHODS.includes(normalized))
+        return null;
+    return `REST mock method must be one of ${REST_MOCK_HTTP_METHODS.join(", ")} or empty string (got "${method}")`;
+}

package/build/utils/logger.js

@@ -22,7 +22,7 @@ export class McpLogger {
         try {
             console.error(JSON.stringify(logEntry));
         }
-        catch (error) {
+        catch (_error) {
             // silently ignore
         }
     }

package/build/utils/mockCompatibility.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Mock Compatibility Pre-flight Check
+ *
+ * Validates mock protocol combinations BEFORE deployment to surface
+ * known incompatibilities early rather than at test execution time.
+ */
+import { MockProtocol } from "../types/TestTypes.js";
+export { MockProtocol };
+/** Narrow view of a mock spec used only for protocol compatibility checking. */
+export interface MockCompatibilitySpec {
+    protocol: MockProtocol;
+    endpointURL: string;
+    method?: string;
+    grpcServiceName?: string;
+    kafkaTopic?: string;
+}
+export interface CompatibilityWarning {
+    code: string;
+    message: string;
+    suggestion: string;
+    affectedMocks: string[];
+    /** When true, the affected mocks cannot intercept traffic and must not be generated or deployed. */
+    blocking?: boolean;
+}
+export interface CompatibilityResult {
+    compatible: boolean;
+    /** True when at least one warning is blocking — those mocks must be skipped entirely. */
+    hasBlockers: boolean;
+    warnings: CompatibilityWarning[];
+}
+export interface MockCompatibilityOptions {
+    /** Enable Docker local-dev checks that require mocks to intercept service DNS aliases. */
+    dockerLocalDev?: boolean;
+}
+/**
+ * Validates a set of mock specs for known protocol compatibility issues.
+ *
+ * Rules:
+ * - Any gRPC mock present → GRPC_PERSISTENT_CONN warning (DNS hijacking skips persistent conns)
+ * - Docker local-dev REST mock using loopback/host.docker.internal → REST_LOOPBACK_URL blocking warning
+ *
+ * REST mocks work correctly in Docker local-dev mode only when the mock URL uses
+ * the real Docker service hostname (e.g. "billing" from "http://billing:5001").
+ * The worker adds that hostname as a Docker network alias so DNS resolves to the mock server.
+ *
+ * `compatible` is false when any warning is blocking and the mock cannot intercept traffic.
+ * `hasBlockers` is true when at least one warning is blocking (mock must not be generated/deployed).
+ */
+export declare function validateMockCompatibility(mocks: MockCompatibilitySpec[], options?: MockCompatibilityOptions): CompatibilityResult;

package/build/utils/mockCompatibility.js

@@ -0,0 +1,82 @@
+/**
+ * Mock Compatibility Pre-flight Check
+ *
+ * Validates mock protocol combinations BEFORE deployment to surface
+ * known incompatibilities early rather than at test execution time.
+ */
+import { MockProtocol } from "../types/TestTypes.js";
+export { MockProtocol };
+function parseRestHostname(endpointURL) {
+    try {
+        const hostname = new URL(endpointURL).hostname.toLowerCase();
+        return hostname.startsWith("[") && hostname.endsWith("]")
+            ? hostname.slice(1, -1)
+            : hostname;
+    }
+    catch {
+        return null;
+    }
+}
+function isLoopbackRestEndpoint(endpointURL) {
+    const hostname = parseRestHostname(endpointURL);
+    return (hostname === "localhost" ||
+        hostname === "127.0.0.1" ||
+        hostname === "0.0.0.0" ||
+        hostname === "::1" ||
+        hostname === "host.docker.internal");
+}
+/**
+ * Validates a set of mock specs for known protocol compatibility issues.
+ *
+ * Rules:
+ * - Any gRPC mock present → GRPC_PERSISTENT_CONN warning (DNS hijacking skips persistent conns)
+ * - Docker local-dev REST mock using loopback/host.docker.internal → REST_LOOPBACK_URL blocking warning
+ *
+ * REST mocks work correctly in Docker local-dev mode only when the mock URL uses
+ * the real Docker service hostname (e.g. "billing" from "http://billing:5001").
+ * The worker adds that hostname as a Docker network alias so DNS resolves to the mock server.
+ *
+ * `compatible` is false when any warning is blocking and the mock cannot intercept traffic.
+ * `hasBlockers` is true when at least one warning is blocking (mock must not be generated/deployed).
+ */
+export function validateMockCompatibility(mocks, options = {}) {
+    const warnings = [];
+    const restMocks = mocks.filter((m) => m.protocol === MockProtocol.Rest);
+    const grpcMocks = mocks.filter((m) => m.protocol === MockProtocol.Grpc);
+    const loopbackRestMocks = options.dockerLocalDev
+        ? restMocks.filter((m) => isLoopbackRestEndpoint(m.endpointURL))
+        : [];
+    if (loopbackRestMocks.length > 0) {
+        warnings.push({
+            code: "REST_LOOPBACK_URL",
+            message: "REST mocks for Docker local-dev must use the original Docker service hostname. " +
+                "Loopback hosts such as localhost, 127.0.0.1, 0.0.0.0, ::1, or host.docker.internal " +
+                "do not give the Skyramp worker the downstream service DNS alias it needs to intercept traffic.",
+            suggestion: "Use the real Docker service origin in endpointURL, for example http://ams:4000 or " +
+                "http://billing:5001. Do not use localhost, host.docker.internal, or the Skyramp worker address " +
+                "for deployable REST mocks.",
+            affectedMocks: loopbackRestMocks.map((m) => m.endpointURL),
+            blocking: true,
+        });
+    }
+    // Rule: gRPC mocks use DNS hijacking that doesn't intercept persistent connections
+    if (grpcMocks.length > 0) {
+        warnings.push({
+            code: "GRPC_PERSISTENT_CONN",
+            message: "gRPC mocks use DNS hijacking which does not intercept persistent connections. " +
+                "If the service under test establishes a gRPC connection before mocks are applied, " +
+                "the existing connection will bypass the mock.",
+            suggestion: "Apply gRPC mocks before the service under test starts, or restart " +
+                "the service after applying mocks so it establishes a new connection through the mock DNS. " +
+                "For Docker local-dev, also verify the worker has the original downstream hostname alias " +
+                "from endpointURL (for example, partner-accounts for partner-accounts:50051).",
+            affectedMocks: grpcMocks.map((m) => m.grpcServiceName || m.endpointURL),
+        });
+    }
+    const hasBlockers = warnings.some((w) => w.blocking);
+    return {
+        compatible: !hasBlockers,
+        hasBlockers,
+        warnings,
+    };
+}

package/build/utils/pom-catalog.d.ts

@@ -0,0 +1,23 @@
+export declare const POM_CATALOG_FILENAME = "skyramp-pom-catalog.md";
+/**
+ * The one canonical path for a test file's `skyramp-pom-catalog.md`:
+ * `<repoRoot>/.skyramp/skyramp-pom-catalog.md`.
+ *
+ * The catalog is cross-run state, and one path per repository is what keeps it
+ * usable — two runs writing at different depths fork the cache so neither finds
+ * the other's. It sits beside `workspace.yml` rather than in the customer's test
+ * directory because it is generated tooling state, not a deliverable, and
+ * delivery stages it by name (SKYR-4125).
+ *
+ * The root is resolved in priority order:
+ * 1. `getTestsRepoDir()` — the test-repo clone root set by `skyramp_analyze_changes`
+ *    when `testsRepoDir` is provided. In cross-repo delivery testbot commits ONLY
+ *    to this clone, so the catalog must anchor here or it is never staged and the
+ *    cache dies silently.
+ * 2. `detectGitRoot` — the fallback for same-repo runs (where nothing sets the
+ *    tests-repo dir) and for the NL path, where a developer drives
+ *    `skyramp_ui_test_generation`/`skyramp_reuse_code` directly without ever
+ *    calling `skyramp_analyze_changes`.
+ * 3. The test file's own directory, for a path in no repository at all.
+ */
+export declare function resolvePomCatalogPath(testFile: string): string;

package/build/utils/pom-catalog.js

@@ -0,0 +1,30 @@
+import path from "path";
+import { getTestsRepoDir } from "./AnalysisStateManager.js";
+import { detectGitRoot } from "./gitStaging.js";
+export const POM_CATALOG_FILENAME = "skyramp-pom-catalog.md";
+/**
+ * The one canonical path for a test file's `skyramp-pom-catalog.md`:
+ * `<repoRoot>/.skyramp/skyramp-pom-catalog.md`.
+ *
+ * The catalog is cross-run state, and one path per repository is what keeps it
+ * usable — two runs writing at different depths fork the cache so neither finds
+ * the other's. It sits beside `workspace.yml` rather than in the customer's test
+ * directory because it is generated tooling state, not a deliverable, and
+ * delivery stages it by name (SKYR-4125).
+ *
+ * The root is resolved in priority order:
+ * 1. `getTestsRepoDir()` — the test-repo clone root set by `skyramp_analyze_changes`
+ *    when `testsRepoDir` is provided. In cross-repo delivery testbot commits ONLY
+ *    to this clone, so the catalog must anchor here or it is never staged and the
+ *    cache dies silently.
+ * 2. `detectGitRoot` — the fallback for same-repo runs (where nothing sets the
+ *    tests-repo dir) and for the NL path, where a developer drives
+ *    `skyramp_ui_test_generation`/`skyramp_reuse_code` directly without ever
+ *    calling `skyramp_analyze_changes`.
+ * 3. The test file's own directory, for a path in no repository at all.
+ */
+export function resolvePomCatalogPath(testFile) {
+    const abs = path.resolve(testFile);
+    const root = getTestsRepoDir() ?? detectGitRoot(abs) ?? path.dirname(abs);
+    return path.join(root, ".skyramp", POM_CATALOG_FILENAME);
+}

package/build/utils/pom-scope/pom-files.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Spec/test basenames. POM discovery excludes them; {@link globSpecFiles}
+ * targets them.
+ */
+export declare const SPEC_BASENAME: RegExp;
 export declare function globPomFiles(root: string): Promise<string[]>;
+/**
+ * Spec files anywhere under `root`, by basename rather than by directory.
+ *
+ * Suites are often grouped by feature or customer rather than under `tests/`
+ * (e.g. `box/workflow.spec.ts`), so the directory name gives nothing away — but
+ * the filename always does. Keeps the cypress/`__tests__` trees that POM
+ * discovery skips: here the tests are the subject, not the thing to skip past.
+ */
+export declare function globSpecFiles(root: string): Promise<string[]>;
 /** Fallback discovery for repos whose POM layer doesn't match the conventional glob patterns. */
 export declare function globAllSourceFiles(root: string): Promise<string[]>;

package/build/utils/pom-scope/pom-files.js

@@ -16,18 +16,24 @@ const POM_GLOBS = [
     "**/{test,tests,e2e,playwright}/**/{lib,utils,helpers,support}/**/*.{ts,js}",
     "**/{testUtils,test-utils,testHelpers,test-helpers}.{ts,js}",
 ];
-const EXCLUDED_BASENAME = /\.(spec|test|cy)\.(ts|js|tsx|jsx|mjs|cjs)$/;
+/**
+ * Spec/test basenames. POM discovery excludes them; {@link globSpecFiles}
+ * targets them.
+ */
+export const SPEC_BASENAME = /\.(spec|test|cy)\.(ts|js|tsx|jsx|mjs|cjs)$/;
 const ALL_SOURCE_GLOBS = ["**/*.{ts,js,tsx,jsx,mjs,cjs}"];
-const ALL_SOURCE_IGNORE = [
+/** Never source: dependencies, build output, VCS metadata. */
+const BUILD_IGNORE = [
     "**/node_modules/**",
     "**/dist/**",
     "**/build/**",
     "**/coverage/**",
     "**/.git/**",
     "**/vendor/**",
-    "**/cypress/**",
-    "**/__tests__/**",
 ];
+/** Test trees a POM is not expected to live in. Not skipped when the tests themselves are the subject. */
+const TEST_TREE_IGNORE = ["**/cypress/**", "**/__tests__/**"];
+const ALL_SOURCE_IGNORE = [...BUILD_IGNORE, ...TEST_TREE_IGNORE];
 export async function globPomFiles(root) {
     const matches = await fg(POM_GLOBS, {
         cwd: root,
@@ -37,7 +43,27 @@ export async function globPomFiles(root) {
         followSymbolicLinks: false,
     });
     return [...new Set(matches)]
-        .filter((f) => !EXCLUDED_BASENAME.test(path.basename(f)))
+        .filter((f) => !SPEC_BASENAME.test(path.basename(f)))
+        .sort();
+}
+/**
+ * Spec files anywhere under `root`, by basename rather than by directory.
+ *
+ * Suites are often grouped by feature or customer rather than under `tests/`
+ * (e.g. `box/workflow.spec.ts`), so the directory name gives nothing away — but
+ * the filename always does. Keeps the cypress/`__tests__` trees that POM
+ * discovery skips: here the tests are the subject, not the thing to skip past.
+ */
+export async function globSpecFiles(root) {
+    const matches = await fg(ALL_SOURCE_GLOBS, {
+        cwd: root,
+        absolute: true,
+        ignore: BUILD_IGNORE,
+        suppressErrors: true,
+        followSymbolicLinks: false,
+    });
+    return [...new Set(matches)]
+        .filter((f) => SPEC_BASENAME.test(path.basename(f)))
         .sort();
 }
 /** Fallback discovery for repos whose POM layer doesn't match the conventional glob patterns. */
@@ -50,6 +76,6 @@ export async function globAllSourceFiles(root) {
         followSymbolicLinks: false,
     });
     return [...new Set(matches)]
-        .filter((f) => !EXCLUDED_BASENAME.test(path.basename(f)))
+        .filter((f) => !SPEC_BASENAME.test(path.basename(f)))
         .sort();
 }

package/build/utils/pom-scope/testIdDiscovery.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Which attribute does this repository use for test ids?
+ *
+ * The blueprint capture anchors every element's xpath on a test-id attribute
+ * when it can find one, and assumes Playwright's `data-testid` otherwise. A repo
+ * using anything else gets no anchor and a positional xpath instead — which
+ * resolves at capture time and breaks later, so the miss is invisible.
+ *
+ * Enumerating popular names (`data-test`, `data-qa`, ...) only covers the repos
+ * someone thought of. The repository already answers the question itself: its
+ * page objects and specs name the attribute every time they select on it. So
+ * read the answer out of the selectors rather than guessing at it.
+ */
+export type AttributeCount = {
+    attribute: string;
+    count: number;
+};
+export type TestIdDiscovery = {
+    /** Most-used qualifying attribute, or undefined when nothing qualified. */
+    attribute?: string;
+    /** Every qualifying attribute with its selector count, most-used first. */
+    counts: AttributeCount[];
+    /**
+     * Most-used attributes overall, qualifying or not.
+     *
+     * The point of reporting these is the case no name rule can reach: a suite
+     * selecting on something arbitrary like `xyz-id` produces no qualifying
+     * candidate, and the miss is otherwise invisible. Printed on a miss, this names
+     * the attribute an operator would set explicitly.
+     */
+    observed: AttributeCount[];
+    filesScanned: number;
+};
+/**
+ * Report which test-id attribute this repository's page objects and specs use.
+ *
+ * Never throws: an unreadable tree yields no attribute, which leaves the capture
+ * on Playwright's default.
+ */
+export declare function discoverTestIdAttribute(root: string): Promise<TestIdDiscovery>;

package/build/utils/pom-scope/testIdDiscovery.js

@@ -0,0 +1,104 @@
+/**
+ * Which attribute does this repository use for test ids?
+ *
+ * The blueprint capture anchors every element's xpath on a test-id attribute
+ * when it can find one, and assumes Playwright's `data-testid` otherwise. A repo
+ * using anything else gets no anchor and a positional xpath instead — which
+ * resolves at capture time and breaks later, so the miss is invisible.
+ *
+ * Enumerating popular names (`data-test`, `data-qa`, ...) only covers the repos
+ * someone thought of. The repository already answers the question itself: its
+ * page objects and specs name the attribute every time they select on it. So
+ * read the answer out of the selectors rather than guessing at it.
+ */
+import { readFile } from "fs/promises";
+import { globPomFiles, globSpecFiles } from "./pom-files.js";
+import { DEFAULT_TESTID_ATTRS } from "./selector-extractor.js";
+/** Bound the read — a monorepo scan must not delay server startup. */
+const MAX_FILES = 400;
+const MAX_BYTES_PER_FILE = 256 * 1024;
+/**
+ * Attribute name inside an attribute selector: `[data-test="x"]`, `[qa-id='y']`.
+ *
+ * Deliberately open-ended, which is why it cannot reuse `selector-extractor`'s
+ * pattern: that one is built from a known attribute list to *extract values for
+ * attributes we already named*, whereas this has to surface names nobody listed.
+ */
+const ATTR_SELECTOR_RE = /\[\s*([A-Za-z][A-Za-z0-9_:-]*)\s*[~^$*|]?=\s*["']/g;
+/**
+ * Tokens by which an attribute name declares itself to be about testing.
+ *
+ * Matched as whole tokens, never as prefixes. `auto` is deliberately absent —
+ * it admitted `data-auto-play` and `data-auto-height`, and `automation` already
+ * covers the convention it was there for (`data-automation-id`).
+ */
+const TEST_TOKENS = new Set(["test", "testid", "tests", "qa", "cy", "cypress", "e2e", "automation"]);
+/**
+ * Whether a name plausibly denotes a test id.
+ *
+ * A name heuristic, safe only because of what it is applied to: an attribute the
+ * repository's own tests already select on. A name that is both used as a
+ * selector and self-describes as test-related is not going to be
+ * `data-testimonial`. Applied to raw DOM attributes the same rule would be
+ * reckless.
+ *
+ * Requiring a token is also what keeps the standard attributes out — `type`,
+ * `role`, `href`, `aria-label`, `placeholder` and the rest carry no such token,
+ * so no exclusion list is needed alongside this. (`autocomplete` tokenises as one
+ * word, so it does not match `auto`.)
+ */
+function looksLikeTestId(attr) {
+    const lower = attr.toLowerCase();
+    if (DEFAULT_TESTID_ATTRS.includes(lower))
+        return true;
+    const tokens = lower.split(/[^a-z0-9]+/).filter(Boolean);
+    if (tokens.some((t) => TEST_TOKENS.has(t)))
+        return true;
+    // Glued forms like `datatestid`. Anchored at the end on purpose: a
+    // `startsWith("test")` catch-all also admits `data-testimonial`, and since
+    // candidates are ranked by use count, a false positive used more often than
+    // the real attribute becomes the anchor for the whole repo.
+    return tokens.some((t) => t.endsWith("testid"));
+}
+const OBSERVED_REPORT_LIMIT = 5;
+/**
+ * Report which test-id attribute this repository's page objects and specs use.
+ *
+ * Never throws: an unreadable tree yields no attribute, which leaves the capture
+ * on Playwright's default.
+ */
+export async function discoverTestIdAttribute(root) {
+    let files;
+    try {
+        const [poms, specs] = await Promise.all([globPomFiles(root), globSpecFiles(root)]);
+        files = [...new Set([...poms, ...specs])].slice(0, MAX_FILES);
+    }
+    catch {
+        return { counts: [], observed: [], filesScanned: 0 };
+    }
+    const all = new Map();
+    for (const file of files) {
+        let content;
+        try {
+            content = (await readFile(file, "utf8")).slice(0, MAX_BYTES_PER_FILE);
+        }
+        catch {
+            continue;
+        }
+        for (const match of content.matchAll(ATTR_SELECTOR_RE)) {
+            const attr = match[1];
+            all.set(attr, (all.get(attr) ?? 0) + 1);
+        }
+    }
+    // Count first; name as a tiebreak so the result never depends on walk order.
+    const ranked = [...all.entries()]
+        .map(([attribute, count]) => ({ attribute, count }))
+        .sort((a, b) => b.count - a.count || a.attribute.localeCompare(b.attribute));
+    const counts = ranked.filter((c) => looksLikeTestId(c.attribute));
+    return {
+        attribute: counts[0]?.attribute,
+        counts,
+        observed: ranked.slice(0, OBSERVED_REPORT_LIMIT),
+        filesScanned: files.length,
+    };
+}

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

@@ -10,5 +10,10 @@ export type VerifyResult = {
     unverifiable: string[];
     parseError?: string;
     checkedCalls: number;
+    /** Every POM call found in the spec, verifiable or not. NOT checkedCalls +
+     *  unverifiable.length: `unverifiable` also absorbs `unrecognized` bindings,
+     *  which are not calls at all, so that sum overcounts. This is the count of
+     *  POM members the delivered spec actually reuses. */
+    reusedCalls: number;
 };
 export declare function verifyReuse(testFile: string, language: string): Promise<VerifyResult>;

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

@@ -182,5 +182,6 @@ export async function verifyReuse(testFile, language) {
         unverifiable,
         parseError,
         checkedCalls,
+        reusedCalls: calls.length,
     };
 }

package/build/utils/progress.js

@@ -10,11 +10,16 @@ export function makeProgressReporter(extra) {
     return async (progress, total, message) => {
         const progressToken = extra._meta?.progressToken;
         if (progressToken !== undefined) {
-            const notification = {
-                method: "notifications/progress",
-                params: { progressToken, progress, total, message },
-            };
-            await extra.sendNotification(notification);
+            try {
+                const notification = {
+                    method: "notifications/progress",
+                    params: { progressToken, progress, total, message },
+                };
+                await extra.sendNotification(notification);
+            }
+            catch {
+                // Progress is best-effort; a disconnected client should not fail the tool.
+            }
         }
     };
 }

package/build/utils/proxy-terminal.js

@@ -334,7 +334,7 @@ export async function closeProxyTerminal() {
                             terminalPID,
                         });
                     }
-                    catch (killErr) {
+                    catch (_killErr) {
                         // Process is already dead, which is what we want
                         logger.debug("Terminal process already terminated", {
                             terminalPID,
@@ -384,14 +384,14 @@ export async function closeProxyTerminal() {
                             terminalPID,
                         });
                     }
-                    catch (killErr) {
+                    catch (_killErr) {
                         // Process is already dead, which is what we want
                         logger.debug("Terminal process already terminated", {
                             terminalPID,
                         });
                     }
                 }
-                catch (pidErr) {
+                catch (_pidErr) {
                     // Fallback to regular process kill
                     try {
                         process.kill(terminalPID, "SIGTERM");

package/build/utils/reportVerification.d.ts

@@ -26,10 +26,12 @@ export interface UnbackedClaimsInput {
         fileName?: string;
         repository?: string;
     }[];
-    /** Maintenance verdicts (server-derived from skyramp_actions). */
+    /** Maintenance verdicts (server-derived from skyramp_actions). `pomFile`, when set, is
+     *  the file the edit actually lands in — see the UPDATE rule below. */
     verdicts: {
         action: DriftAction;
         testFilePath: string;
+        pomFile?: string;
     }[];
     /** owner/repo of the primary repo — used to exempt cross-repo newTest claims
      *  whose files live in a different checkout. */
@@ -46,7 +48,10 @@ export interface UnbackedClaimsInput {
  * edit (or drops the claim) rather than hallucinating it into the report.
  *
  * Only UPDATE verdicts are gated: an UPDATE is a targeted in-place edit that
- * reliably implies a working-tree change. Exemptions:
+ * reliably implies a working-tree change — in `pomFile` when the verdict names one,
+ * otherwise in `testFilePath`. For a POM-based test those are different files: the spec
+ * is what runs, the page object is what gets patched, so checking only `testFilePath`
+ * would reject maintenance that did land (SKYR-4129). Exemptions:
  *  - REGENERATE verdicts — on an EXTERNAL (user-authored Playwright/Cypress/RTL)
  *    test these are report-only (Skyramp can't auto-regenerate them; the developer
  *    acts manually), so no working-tree change is expected; and even an internal

package/build/utils/reportVerification.js

@@ -50,7 +50,10 @@ export async function listChangedFiles(repoRoot) {
  * edit (or drops the claim) rather than hallucinating it into the report.
  *
  * Only UPDATE verdicts are gated: an UPDATE is a targeted in-place edit that
- * reliably implies a working-tree change. Exemptions:
+ * reliably implies a working-tree change — in `pomFile` when the verdict names one,
+ * otherwise in `testFilePath`. For a POM-based test those are different files: the spec
+ * is what runs, the page object is what gets patched, so checking only `testFilePath`
+ * would reject maintenance that did land (SKYR-4129). Exemptions:
  *  - REGENERATE verdicts — on an EXTERNAL (user-authored Playwright/Cypress/RTL)
  *    test these are report-only (Skyramp can't auto-regenerate them; the developer
  *    acts manually), so no working-tree change is expected; and even an internal
@@ -96,8 +99,11 @@ export function findUnbackedClaims(input) {
         // change, and internal ones may regenerate to identical content.
         if (v.action !== DriftAction.Update)
             continue;
-        if (!isBacked(v.testFilePath)) {
-            unbacked.push(`testMaintenance ${v.action} claims an edit to "${path.basename(v.testFilePath)}", but that file has no working-tree change`);
+        // The edit target, not the spec: for a POM-based test the page object is what
+        // gets patched while testFilePath stays the spec (SKYR-4129).
+        const editTarget = v.pomFile ?? v.testFilePath;
+        if (!isBacked(editTarget)) {
+            unbacked.push(`testMaintenance ${v.action} claims an edit to "${path.basename(editTarget)}", but that file has no working-tree change`);
         }
     }
     return unbacked;

package/build/utils/routeParsers.d.ts

@@ -59,15 +59,9 @@ export declare function isRouteLikeFile(filePath: string): boolean;
  * route that existed in the base branch.
  */
 export declare function selectRemovalCandidateFiles(diffData: BranchDiffData): string[];
-/**
- * Recover endpoints as they existed in the base branch, for the given candidate
- * files. `fetchBaseContent` returns a file's base-branch content (e.g. via
- * `git show base:<file>`); files that throw are skipped. Returns every endpoint
- * found in the base versions — callers pass the result to
- * `classifyEndpointsByChangedFiles`, whose moved/still-present filter drops any
- * endpoint that survives in the current catalog, leaving only genuine removals.
- */
-export declare function recoverRemovedEndpointsFromBase(candidateFiles: string[], fetchBaseContent: (file: string) => Promise<string>): Promise<ScannedEndpoint[]>;
+export declare function recoverRemovedEndpointsFromBase(candidateFiles: string[], fetchBaseContent: (file: string) => Promise<string>, repositoryPath?: string, baseBranch?: string): Promise<ScannedEndpoint[]>;
+/** Strip git's `a/` / `b/` diff-path prefix and normalize separators. */
+export declare function normalizeDiffPath(spec: string): string;
 /**
  * Parse a unified diff into the set of new-side (post-change) line numbers that
  * were touched, keyed by normalized file path.