@skyramp/mcp 0.3.5 → 0.3.6-rc.1

package/build/utils/subjectEndpoints.js

@@ -0,0 +1,98 @@
+import { findStepOnChangedRoute } from "./changedRoutes.js";
+import { extractResourceFromPath, isParamSegment } from "./routeParsers.js";
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/**
+ * A final-position DELETE that removes a resource an earlier POST created is
+ * cleanup, not the subject. SKYR-4214 measured the cost of counting it: the
+ * same fixture keyed as POST::flows on one run and DELETE::flows on the next,
+ * decided only by whether the model appended a cleanup step.
+ *
+ * The step count matters. A two-step POST-then-DELETE has no room for a
+ * verification step, so the DELETE is what the test is about; the cleanup shape
+ * always has a step between the create and the delete. A scenario that asserts
+ * the delete worked (…DELETE, then GET 404) leaves the DELETE off the final
+ * position, so it is not excluded either.
+ */
+function isTeardownStep(steps, index) {
+    const step = steps[index];
+    if (index !== steps.length - 1)
+        return false;
+    if ((step.method ?? "").toUpperCase() !== "DELETE")
+        return false;
+    if (steps.length < 3)
+        return false;
+    const resource = extractResourceFromPath(step.path ?? "");
+    // "unknown" is the sentinel for a path that names no resource, so comparing
+    // it by equality makes any two unidentifiable paths look like the same
+    // resource: `POST /` … `DELETE /{id}` read as create-then-cleanup and the
+    // DELETE — the real subject — got skipped. Only a named resource can pair.
+    if (resource === "unknown")
+        return false;
+    return steps.slice(0, index).some((earlier) => (earlier.method ?? "").toUpperCase() === "POST" &&
+        extractResourceFromPath(earlier.path ?? "") === resource);
+}
+/**
+ * A route declaration made only of parameter segments (or none at all, e.g.
+ * "/" or "") names no resource, so it cannot tell one endpoint from another —
+ * every step's path ends in the same param segment. SKYR-4214: a changed
+ * `@router.delete("/{id}")` line matched a step's trailing DELETE cleanup
+ * step just as well as the step it was actually meant to catch, which
+ * reinstated the bug this file exists to fix. Rule 1 only accepts a route
+ * that contributes at least one non-parameter segment.
+ */
+function routeIdentifiesResource(routePath) {
+    return routePath.split("/").filter(Boolean).some((segment) => !isParamSegment(segment));
+}
+/**
+ * The endpoints a scenario tests, in step order.
+ *
+ * 1. Every step on a changed diff line that names a resource. A test written
+ *    for a pull request is about what the pull request changed, and a
+ *    scenario can exercise more than one changed endpoint.
+ * 2. If no step matches: the last mutating step that is not a teardown step.
+ *    Earlier mutations are usually setup (POST /products before PATCH /orders).
+ * 3. If no mutating step remains: the last step.
+ *
+ * Returns an empty list only for a scenario with no steps. Every caller must
+ * treat an empty list as "no information", never as "covered".
+ */
+export function resolveSubjectEndpoints(scenario, opts) {
+    const steps = scenario.steps ?? [];
+    if (steps.length === 0)
+        return [];
+    const changedRoutes = (opts.changedRoutes ?? []).filter((route) => routeIdentifiesResource(route.path));
+    if (changedRoutes.length > 0) {
+        // Attribute PER ROUTE, not per step. A diff-extracted route is local to its
+        // own router declaration — the mount prefix lives in another file, so a bare
+        // `POST /items` suffix-matches a step on `/orders/{id}/items` and one on
+        // `/products/{id}/items` equally. Recording both would invent a subject the
+        // diff does not name, and dedup then needs every unrelated key covered
+        // before the candidate can be removed.
+        //
+        // A route matching exactly one step names that step. A route matching
+        // several names none of them: there is no evidence for choosing, and a
+        // guess is worse than an omission. Other routes still contribute, so a
+        // scenario that genuinely tests two changed endpoints keeps both subjects.
+        const attributed = [];
+        for (const route of changedRoutes) {
+            const matches = steps.filter((step) => findStepOnChangedRoute([step], [route]));
+            const distinct = new Map(matches.map((step) => [`${step.method} ${step.path}`, step]));
+            if (distinct.size === 1)
+                attributed.push([...distinct.values()][0]);
+        }
+        // Keep step order and drop the duplicates two routes can both name.
+        const onChanged = steps.filter((step) => attributed.includes(step));
+        if (onChanged.length > 0) {
+            return onChanged.map((step) => ({ method: step.method, path: step.path }));
+        }
+    }
+    for (let i = steps.length - 1; i >= 0; i--) {
+        if (!MUTATING_METHODS.has((steps[i].method ?? "").toUpperCase()))
+            continue;
+        if (isTeardownStep(steps, i))
+            continue;
+        return [{ method: steps[i].method, path: steps[i].path }];
+    }
+    const last = steps[steps.length - 1];
+    return [{ method: last.method, path: last.path }];
+}

package/build/utils/testFileClassification.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The single definition of "discovery treats this path as a test file", shared by
+ * discovery itself and by callers that must agree with what discovery classified as
+ * external coverage. A narrower predicate silently disagrees: `tests/test_orders.py`
+ * is external coverage here but is not a test file to `isTestFile` in
+ * scopeAssessment.ts, which only knows the Skyramp and JS/TS spec spellings.
+ *
+ * Accepts absolute or repo-relative paths. The directory patterns need a leading
+ * separator, which a repo-relative path has not got, so one is prepended.
+ */
+export declare function isDiscoveredTestFile(filePath: string): boolean;

package/build/utils/testFileClassification.js

@@ -0,0 +1,47 @@
+import * as path from "path";
+// Test file naming patterns — match against basename.
+// Includes Skyramp-generated suffixes so that files like orders_smoke.py placed
+// outside a recognized test directory are still discovered.
+const TEST_FILE_PATTERNS = [
+    /^test_.*\.(py|js|ts|rb|go|php)$/, // test_*.py, test_*.rb, test_*.go
+    /.*_test\.(py|ts|js|go|rs)$/, // *_test.py, *_test.go, *_test.rs
+    /.*\.test\.(ts|js|tsx|jsx)$/, // *.test.ts, *.test.js, *.test.tsx
+    /.*\..*spec\.(ts|js|tsx|jsx|rb)$/, // *.spec.ts, *.e2e-spec.ts, *.unit-spec.ts
+    /.*Test\.(java|kt|kts|cs|scala|swift|m)$/, // *Test.java, *Test.kt, *Test.m (ObjC)
+    /.*Tests\.(cs|swift|m)$/, // *Tests.cs, *Tests.swift, *Tests.m (ObjC)
+    /.*_spec\.rb$/, // *_spec.rb (RSpec)
+    /.*\.test\.php$/, // *.test.php
+    /.*Test\.php$/, // *Test.php (PHPUnit)
+    // Skyramp-generated test suffixes — must be matched even outside test dirs
+    /.*_(?:smoke|contract|fuzz|integration|load|e2e|ui)\.(py|ts|js|java|rb|go|cs|kt|kts|scala|swift|php|rs)$/i,
+];
+// Directory patterns that signal test-owned files — works with both / and \ separators.
+// Includes standard test dirs, snapshot dirs, and common helper/fixture dirs used by
+// Playwright, Cypress, and other frameworks for page objects and support code.
+const TEST_DIR_PATTERNS = [
+    /[\\/]tests?[\\/]/,
+    /[\\/]__tests__[\\/]/,
+    /[\\/]__snapshots__[\\/]/, // Jest/Vitest snapshot directories
+    /[\\/]spec[\\/]/,
+    /[\\/]e2e[\\/]/,
+    /[\\/]cypress[\\/]/, // Cypress support, fixtures, plugins
+    /[\\/]playwright[\\/]/, // Playwright fixtures and helpers
+    /[\\/]page-?objects?[\\/]/, // page-objects/, page-object/, pageObjects/
+    /[\\/]fixtures[\\/](?!db[\\/]|seed[\\/]|migrations[\\/])/, // test fixture files (not db/seed/migration fixtures)
+    /[\\/]cypress[\\/]support[\\/]/, // Cypress support directory (scoped to avoid matching app support/ dirs)
+];
+/**
+ * The single definition of "discovery treats this path as a test file", shared by
+ * discovery itself and by callers that must agree with what discovery classified as
+ * external coverage. A narrower predicate silently disagrees: `tests/test_orders.py`
+ * is external coverage here but is not a test file to `isTestFile` in
+ * scopeAssessment.ts, which only knows the Skyramp and JS/TS spec spellings.
+ *
+ * Accepts absolute or repo-relative paths. The directory patterns need a leading
+ * separator, which a repo-relative path has not got, so one is prepended.
+ */
+export function isDiscoveredTestFile(filePath) {
+    if (TEST_FILE_PATTERNS.some((p) => p.test(path.basename(filePath))))
+        return true;
+    return TEST_DIR_PATTERNS.some((p) => p.test(`/${filePath}`));
+}

package/build/utils/uiPageEnumerator.d.ts

@@ -14,6 +14,12 @@
  *     Next.js (app/ and pages/), Nuxt / Vue Router file-based, and SvelteKit.
  *     Gated on detection of a framework config file in the repo.
  *
+ *   Strategy 1b — Import graph
+ *     For a changed file that is not itself a route (a component, a constants
+ *     module), map the production files that import it through the same
+ *     filesystem-route mapper. Uses the importer list the production-importer integration
+ *     check already computed. Merged with strategy 1 rather than tried after it.
+ *
  *   Strategy 2 — Source-grounded routes
  *     Walks router/App files with the TS Compiler API for code-defined
  *     route declarations like `<Route path="/cart" element={<Cart/>}>`.
@@ -26,16 +32,38 @@
  *   Strategy 3 — Root fallback
  *     Read the workspace's frontend baseUrl and treat it as the single
  *     candidate page. Always available when a frontend service is configured.
+ *
+ * When no frontend baseUrl can be resolved, strategies 1/1b still run and their
+ * results are returned as bare URL paths (`baseUrlResolved: false`) so the agent
+ * can prefix the base URL it discovers; strategies 2–3 need a host and are skipped.
  */
-export type CandidateUiPageStrategy = "framework-route-grep" | "source-grounded-routes" | "dart-go-router" | "root-fallback";
+import type { FrontendFileIntegration } from "../types/FrontendIntegration.js";
+export type CandidateUiPageStrategy = "framework-route-grep" | "import-graph" | "source-grounded-routes" | "dart-go-router" | "root-fallback";
 export interface CandidateUiPage {
-    /** Fully qualified URL (workspace baseUrl + framework-derived path). */
+    /**
+     * Fully qualified URL (workspace baseUrl + framework-derived path), or a bare
+     * URL path when `baseUrlResolved` is false.
+     */
     url: string;
     /** Source files that suggested this page (for traceability). */
     sourcedFrom: string[];
     /** Which strategy enumerated it. */
     strategy: CandidateUiPageStrategy;
+    /**
+     * Present (false) only when no frontend baseUrl could be resolved and `url`
+     * is a bare path the agent must prefix. Absent means `url` is complete.
+     */
+    baseUrlResolved?: false;
+    /** import-graph only: the route files that import `sourcedFrom` and produced this path. */
+    via?: string[];
 }
+/**
+ * Upper bound on candidate pages. Strategy 1b is bounded by changed files ×
+ * importers, and every candidate costs the agent a navigate + a capture, so the
+ * list is cut here — direct route matches first, then import-graph pages that
+ * render the most changed files.
+ */
+export declare const MAX_CANDIDATE_PAGES = 10;
 /**
  * File-system → URL mapping for filesystem-routed frameworks.
  *
@@ -63,15 +91,7 @@ export declare function frameworkFileToUrlPath(filePath: string): string | null;
  * and the `frontendFiles[]`-derived candidate frontend roots.
  */
 export declare function detectsFilesystemRouting(repositoryPath: string): boolean;
-/**
- * Strategy 1 implementation. Filters frontend files through the framework
- * route mapper; collects the URL paths that mapped successfully.
- *
- * Suppressed when the repo doesn't have a recognized filesystem-routing
- * framework config — see `detectsFilesystemRouting`. Without that guard,
- * repos with conventional `pages/` directories but code-defined routes
- * (e.g. React with React Router) produce false-positive URLs.
- */
+/** Strategy 1 only (no import graph), joined to `baseUrl`. */
 export declare function findCandidatePagesByFrameworkRoute(frontendFiles: string[], baseUrl: string, repositoryPath?: string): CandidateUiPage[];
 /**
  * Strategy 2 implementation. Walks router/App files with the TS Compiler API
@@ -126,21 +146,27 @@ export declare function findRootFallbackPage(repositoryPath: string): Promise<Ca
  *      is the picked frontend service's serviceName, sanitized via
  *      `sanitizeServiceName`)
  *   2. Global override: `SKYRAMP_TEST_BASE_URL` (single service or all
- *      services share one URL)
+ *      services share one URL). Also honored when the workspace declares no
+ *      services at all — the action can know the URL without a workspace entry.
  *   3. Static workspace.yml value: `api.baseUrl` from the picked frontend
  *      service
  *
- * Returns null when no service has a usable URL.
+ * Returns null when neither the environment nor any service has a usable URL.
  *
  * Exported (vs private) so analyze_changes and future tools can reuse the
  * same selection without re-implementing it.
  */
 export declare function pickFrontendBaseUrl(repositoryPath: string): Promise<string | null>;
 /**
- * Run the strategy ladder in order: framework route grep (1) → source-grounded
- * routes (2) → root fallback (3). Each strategy is consulted only if the
- * previous one produced no candidates. Returns whatever the ladder produces
- * (possibly empty if the workspace has no frontend baseUrl AND none of the
- * earlier strategies matched).
+ * Run the strategy ladder: framework route grep + import graph (1/1b) →
+ * source-grounded routes (2) → Dart GoRouter (2.5) → root fallback (3). Each
+ * later strategy is consulted only if the earlier ones produced no candidates.
+ *
+ * `integration` is the production-importer check for the same files; when given,
+ * changed non-route files resolve to the pages that import them.
+ *
+ * Without a resolvable frontend baseUrl only strategies 1/1b can run; their
+ * paths are returned with `baseUrlResolved: false` for the agent to prefix.
+ * Returns empty only when nothing resolves at all.
  */
-export declare function enumerateCandidateUiPages(repositoryPath: string, frontendFiles: string[]): Promise<CandidateUiPage[]>;
+export declare function enumerateCandidateUiPages(repositoryPath: string, frontendFiles: string[], integration?: FrontendFileIntegration[]): Promise<CandidateUiPage[]>;

package/build/utils/uiPageEnumerator.js

@@ -14,6 +14,12 @@
  *     Next.js (app/ and pages/), Nuxt / Vue Router file-based, and SvelteKit.
  *     Gated on detection of a framework config file in the repo.
  *
+ *   Strategy 1b — Import graph
+ *     For a changed file that is not itself a route (a component, a constants
+ *     module), map the production files that import it through the same
+ *     filesystem-route mapper. Uses the importer list the production-importer integration
+ *     check already computed. Merged with strategy 1 rather than tried after it.
+ *
  *   Strategy 2 — Source-grounded routes
  *     Walks router/App files with the TS Compiler API for code-defined
  *     route declarations like `<Route path="/cart" element={<Cart/>}>`.
@@ -26,6 +32,10 @@
  *   Strategy 3 — Root fallback
  *     Read the workspace's frontend baseUrl and treat it as the single
  *     candidate page. Always available when a frontend service is configured.
+ *
+ * When no frontend baseUrl can be resolved, strategies 1/1b still run and their
+ * results are returned as bare URL paths (`baseUrlResolved: false`) so the agent
+ * can prefix the base URL it discovers; strategies 2–3 need a host and are skipped.
  */
 import * as fs from "fs";
 import * as path from "path";
@@ -33,6 +43,13 @@ import { extractDartRoutes } from "./dartRouteExtractor.js";
 import { extractSourceRoutes } from "./sourceRouteExtractor.js";
 import { hasFlutterSdkDep } from "../prompts/test-recommendation/scopeAssessment.js";
 import { readWorkspaceConfigRaw } from "./workspaceAuth.js";
+/**
+ * Upper bound on candidate pages. Strategy 1b is bounded by changed files ×
+ * importers, and every candidate costs the agent a navigate + a capture, so the
+ * list is cut here — direct route matches first, then import-graph pages that
+ * render the most changed files.
+ */
+export const MAX_CANDIDATE_PAGES = 10;
 // ── Strategy 1: framework route grep ────────────────────────────────────────
 /**
  * File-system → URL mapping for filesystem-routed frameworks.
@@ -61,8 +78,9 @@ export function frameworkFileToUrlPath(filePath) {
         return "/" + stripRouteGroups(nextAppMatch[1]).replace(/\[(\.\.\.)?(\w+)\]/g, ":$2");
     }
     // Next.js Pages Router: pages/foo.tsx → /foo, pages/index.tsx → /
-    // Excludes pages/api/* (those are API handlers, not UI pages).
-    const nextPagesMatch = normalized.match(/(?:^|\/)pages\/(?!api\/)(.+?)\.(tsx|jsx|ts|js)$/);
+    // Excludes pages/api/* (API handlers) and the framework files _app, _document,
+    // _error (they wrap every page and are not routes of their own).
+    const nextPagesMatch = normalized.match(/(?:^|\/)pages\/(?!api\/)(?!_(?:app|document|error)\.)(.+?)\.(tsx|jsx|ts|js)$/);
     if (nextPagesMatch) {
         let urlPath = nextPagesMatch[1];
         // /index → /, /foo/index → /foo
@@ -140,43 +158,64 @@ export function detectsFilesystemRouting(repositoryPath) {
     return false;
 }
 /**
- * Strategy 1 implementation. Filters frontend files through the framework
- * route mapper; collects the URL paths that mapped successfully.
+ * Strategies 1 + 1b: map changed route files (1) and the route files that import
+ * changed non-route files (1b) to URL paths. Deduped by path; when both name the
+ * same path the strategy-1 entry wins and the extra source is appended.
  *
  * Suppressed when the repo doesn't have a recognized filesystem-routing
  * framework config — see `detectsFilesystemRouting`. Without that guard,
  * repos with conventional `pages/` directories but code-defined routes
  * (e.g. React with React Router) produce false-positive URLs.
  */
-export function findCandidatePagesByFrameworkRoute(frontendFiles, baseUrl, repositoryPath) {
+function collectRoutePaths(frontendFiles, integration, repositoryPath) {
     // When repositoryPath is provided, gate on framework detection. When
     // omitted (e.g. older callers, unit tests), preserve original behavior.
     if (repositoryPath !== undefined && !detectsFilesystemRouting(repositoryPath)) {
         return [];
     }
-    const byUrl = new Map();
-    for (const file of frontendFiles) {
-        const urlPath = frameworkFileToUrlPath(file);
-        if (urlPath === null)
-            continue;
-        const normalizedBase = baseUrl.replace(/\/$/, "");
-        const fullUrl = normalizedBase + urlPath;
-        const existing = byUrl.get(fullUrl);
+    const byPath = new Map();
+    const add = (urlPath, sourceFile, strategy, via) => {
+        const existing = byPath.get(urlPath);
         if (existing) {
-            // Same URL surfaced by multiple files — track all sources.
-            if (!existing.sourcedFrom.includes(file)) {
-                existing.sourcedFrom.push(file);
-            }
+            // Same path surfaced by multiple files — track all sources.
+            if (!existing.sourcedFrom.includes(sourceFile))
+                existing.sourcedFrom.push(sourceFile);
+            if (via && existing.via && !existing.via.includes(via))
+                existing.via.push(via);
         }
         else {
-            byUrl.set(fullUrl, {
-                url: fullUrl,
-                sourcedFrom: [file],
-                strategy: "framework-route-grep",
-            });
+            byPath.set(urlPath, { path: urlPath, sourcedFrom: [sourceFile], strategy, ...(via ? { via: [via] } : {}) });
+        }
+    };
+    for (const file of frontendFiles) {
+        const urlPath = frameworkFileToUrlPath(file);
+        if (urlPath !== null)
+            add(urlPath, file, "framework-route-grep");
+    }
+    for (const entry of integration ?? []) {
+        if (!entry.integrated)
+            continue;
+        for (const importer of entry.importers) {
+            const urlPath = frameworkFileToUrlPath(importer);
+            if (urlPath !== null)
+                add(urlPath, entry.file, "import-graph", importer);
         }
     }
-    return Array.from(byUrl.values());
+    const all = Array.from(byPath.values());
+    const rank = (c) => (c.strategy === "framework-route-grep" ? 1 : 0) * 1000 + c.sourcedFrom.length;
+    return all.sort((a, b) => rank(b) - rank(a)).slice(0, MAX_CANDIDATE_PAGES);
+}
+function joinBaseUrl(baseUrl, candidate) {
+    return {
+        url: baseUrl.replace(/\/$/, "") + candidate.path,
+        sourcedFrom: candidate.sourcedFrom,
+        strategy: candidate.strategy,
+        ...(candidate.via ? { via: candidate.via } : {}),
+    };
+}
+/** Strategy 1 only (no import graph), joined to `baseUrl`. */
+export function findCandidatePagesByFrameworkRoute(frontendFiles, baseUrl, repositoryPath) {
+    return collectRoutePaths(frontendFiles, undefined, repositoryPath).map((c) => joinBaseUrl(baseUrl, c));
 }
 // ── Strategy 2: source-grounded routes ──────────────────────────────────────
 /**
@@ -302,13 +341,10 @@ export function findCandidatePagesByDartRoute(repositoryPath, baseUrl, frontendF
  */
 export async function findRootFallbackPage(repositoryPath) {
     const baseUrl = await pickFrontendBaseUrl(repositoryPath);
-    if (!baseUrl)
-        return null;
-    return {
-        url: baseUrl,
-        sourcedFrom: [],
-        strategy: "root-fallback",
-    };
+    return baseUrl ? rootFallbackPage(baseUrl) : null;
+}
+function rootFallbackPage(baseUrl) {
+    return { url: baseUrl, sourcedFrom: [], strategy: "root-fallback" };
 }
 /**
  * Mirror of testbot.git src/services.ts exportServiceBaseUrlEnvVars sanitize().
@@ -369,19 +405,21 @@ function pickFrontendService(services) {
  *      is the picked frontend service's serviceName, sanitized via
  *      `sanitizeServiceName`)
  *   2. Global override: `SKYRAMP_TEST_BASE_URL` (single service or all
- *      services share one URL)
+ *      services share one URL). Also honored when the workspace declares no
+ *      services at all — the action can know the URL without a workspace entry.
  *   3. Static workspace.yml value: `api.baseUrl` from the picked frontend
  *      service
  *
- * Returns null when no service has a usable URL.
+ * Returns null when neither the environment nor any service has a usable URL.
  *
  * Exported (vs private) so analyze_changes and future tools can reuse the
  * same selection without re-implementing it.
  */
 export async function pickFrontendBaseUrl(repositoryPath) {
     const config = await readWorkspaceConfigRaw(repositoryPath);
+    const global = process.env.SKYRAMP_TEST_BASE_URL?.trim();
     if (!config?.services || !Array.isArray(config.services))
-        return null;
+        return global || null;
     const picked = pickFrontendService(config.services);
     // 1. Per-service override (multi-service, distinct URLs).
     // readWorkspaceConfigRaw may fall back to unvalidated YAML, so serviceName
@@ -392,7 +430,6 @@ export async function pickFrontendBaseUrl(repositoryPath) {
             return perSvc;
     }
     // 2. Global override (single service / all services share a URL).
-    const global = process.env.SKYRAMP_TEST_BASE_URL?.trim();
     if (global)
         return global;
     // 3. Static workspace.yml value.
@@ -400,31 +437,38 @@ export async function pickFrontendBaseUrl(repositoryPath) {
 }
 // ── Composer ────────────────────────────────────────────────────────────────
 /**
- * Run the strategy ladder in order: framework route grep (1) → source-grounded
- * routes (2) → root fallback (3). Each strategy is consulted only if the
- * previous one produced no candidates. Returns whatever the ladder produces
- * (possibly empty if the workspace has no frontend baseUrl AND none of the
- * earlier strategies matched).
+ * Run the strategy ladder: framework route grep + import graph (1/1b) →
+ * source-grounded routes (2) → Dart GoRouter (2.5) → root fallback (3). Each
+ * later strategy is consulted only if the earlier ones produced no candidates.
+ *
+ * `integration` is the production-importer check for the same files; when given,
+ * changed non-route files resolve to the pages that import them.
+ *
+ * Without a resolvable frontend baseUrl only strategies 1/1b can run; their
+ * paths are returned with `baseUrlResolved: false` for the agent to prefix.
+ * Returns empty only when nothing resolves at all.
  */
-export async function enumerateCandidateUiPages(repositoryPath, frontendFiles) {
+export async function enumerateCandidateUiPages(repositoryPath, frontendFiles, integration) {
     if (frontendFiles.length === 0)
         return [];
     const baseUrl = await pickFrontendBaseUrl(repositoryPath);
-    // Strategy 1 needs a baseUrl to construct full URLs. Without one, the
-    // fallback path in strategy 3 also won't fire — return empty and let the
-    // caller decide what to do (typically: persist nothing, agent does its
-    // own enumeration via the existing prompt fallback).
-    if (!baseUrl)
-        return [];
-    const fromRoutes = findCandidatePagesByFrameworkRoute(frontendFiles, baseUrl, repositoryPath);
-    if (fromRoutes.length > 0)
-        return fromRoutes;
+    const routePaths = collectRoutePaths(frontendFiles, integration, repositoryPath);
+    if (!baseUrl) {
+        return routePaths.map((c) => ({
+            url: c.path,
+            sourcedFrom: c.sourcedFrom,
+            strategy: c.strategy,
+            baseUrlResolved: false,
+            ...(c.via ? { via: c.via } : {}),
+        }));
+    }
+    if (routePaths.length > 0)
+        return routePaths.map((c) => joinBaseUrl(baseUrl, c));
     const fromSource = findCandidatePagesBySourceRoute(frontendFiles, baseUrl, repositoryPath);
     if (fromSource.length > 0)
         return fromSource;
     const fromDart = findCandidatePagesByDartRoute(repositoryPath, baseUrl, frontendFiles);
     if (fromDart.length > 0)
         return fromDart;
-    const fallback = await findRootFallbackPage(repositoryPath);
-    return fallback ? [fallback] : [];
+    return [rootFallbackPage(baseUrl)];
 }

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

@@ -0,0 +1,16 @@
+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 interface UtilsAllow {
+    kind: UtilsViolationKind;
+    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 parseUtilsAllows(content: string, spec: UtilsLanguageSpec): {
+    allows: UtilsAllow[];
+    /** Marker lines the loose pattern recognises but the grammar cannot read — a decline
+     *  the gate would otherwise drop silently. Reported back so the agent fixes the line. */
+    malformed: string[];
+};

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

@@ -0,0 +1,68 @@
+import { blankStrings } from "./parse.js";
+export const UTILS_VIOLATION_KINDS = [
+    "duplicate-helper",
+    "body-assertion",
+    "scenario-name",
+];
+/**
+ * The documented-decline marker for a utils-file invariant, written in the utils file:
+ *
+ *     # reuse-verify: allow <kind> <helper> — <reason>      (Python)
+ *     // reuse-verify: allow <kind> <helper> — <reason>     (TS/JS)
+ *
+ * ONE grammar, used by both the gate and the report. The POM path's `// kept inline:`
+ * marker had two — the gate's regex and the report parser disagreed on the separator
+ * and on the file extension — and the gap was a run where the gate blocked execution
+ * on declines the report listed correctly (mcp#716, run 30965653402). Here the gate
+ * and the report call this one function.
+ *
+ * The separator is an em/en dash or a hyphen with whitespace on BOTH sides, so a
+ * hyphen inside a helper name cannot be mistaken for it. `(?!<reason)` rejects the
+ * 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_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) {
+    return `${spec.commentPrefix} reuse-verify: allow ${kind} ${helper} — <reason this helper must stay as it is>`;
+}
+export function parseUtilsAllows(content, spec) {
+    const allows = [];
+    const malformed = [];
+    // String contents are blanked first, so a marker (or a comment token) quoted in
+    // code can neither be read as a decline nor make one look like a comment.
+    const rawLines = content.split("\n");
+    const codeLines = blankStrings(content, spec).split("\n");
+    for (let n = 0; n < rawLines.length; n++) {
+        const raw = rawLines[n];
+        const code = codeLines[n] ?? "";
+        // The marker may sit in a trailing comment, a block comment or a JSDoc line — any
+        // comment form. Match from the marker itself, so the comment syntax around it does
+        // not decide whether a decline is read.
+        const at = code.search(ALLOW_LOOSE_RE);
+        if (at === -1)
+            continue;
+        const before = code.slice(0, at);
+        const inComment = spec.commentPrefix === "#"
+            ? /#/.test(before)
+            : /\/\/|\/\*|^\s*\*/.test(before);
+        if (!inComment)
+            continue;
+        const line = raw
+            .slice(at)
+            .replace(/\s*\*\/\s*$/, "")
+            .trim();
+        const m = ALLOW_RE.exec(line);
+        if (!m) {
+            malformed.push(raw.trim());
+            continue;
+        }
+        allows.push({
+            kind: m[1],
+            helper: m[2],
+            reason: m[3],
+        });
+    }
+    return { allows, malformed };
+}

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

@@ -0,0 +1,34 @@
+import { type UtilsHelper } from "./parse.js";
+import { type UtilsLanguageSpec } from "./language-spec.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 declare const CODEGEN_MARKER_RE: RegExp;
+export interface InlineCallSite {
+    /** Absolute path of the sibling test. */
+    file: string;
+    /** 1-based line of the request call. */
+    line: number;
+    method: string;
+    path: string;
+    /** The utils helper that wraps the same method+path. */
+    helper: string;
+}
+/**
+ * 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
+ * perform (measured 0/2 seeded eval runs with the rule as its own mandatory step).
+ *
+ * A call is INLINE when it sits in a test function, not in a module-level helper of
+ * the sibling's own: a sibling that defines `create_order` locally is STEP 4b's
+ * helper-vs-helper case, not a call site. Equivalence is `c3b9157b`'s: same method
+ * and same normalised path, nothing else — literals are what the call's arguments
+ * are for.
+ *
+ * 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[]>;
+/** 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>;