@skyramp/mcp 0.3.5 → 0.3.6-rc.1

package/build/utils/reportVerification.js

@@ -1,4 +1,5 @@
 import path from "path";
+import * as fs from "fs/promises";
 import { execFile } from "child_process";
 import { promisify } from "util";
 import { testFileMatches } from "./utils.js";
@@ -72,8 +73,14 @@ export async function listChangedFiles(repoRoot) {
 }
 /**
  * Cross-check report claims against files that actually changed in the working
- * tree, returning a human-readable description for each claim NOT backed by a
- * real change. An empty result means every claim is backed.
+ * tree, returning a human-readable description for each claim whose file has no
+ * change. An empty result means every claim is backed.
+ *
+ * Not to be confused with `findInvalidSourceCitations` below. This one is about
+ * files the agent says IT wrote — a created test, a maintained test — so the test
+ * is "did this file change in this run". That one is about application code the
+ * agent POINTS AT as the home of a defect, which it never edits, so the test is
+ * "does this file and symbol exist in the checkout at all".
  *
  * The delivery path can only ship what the agent actually edited (SKYR-3883), so
  * a report must never claim file work the tree doesn't reflect. This is the
@@ -96,7 +103,7 @@ export async function listChangedFiles(repoRoot) {
  *  - Claims for files outside this checkout (cross-repo `repository`, or an
  *    absolute path resolving outside `repoRoot`) — a different checkout owns them.
  */
-export function findUnbackedClaims(input) {
+export function findUnchangedFileClaims(input) {
     const { repoRoot, changedFiles, newTests, verdicts, primaryRepository } = input;
     const unbacked = [];
     const isBacked = (claimedPath) => {
@@ -139,3 +146,221 @@ export function findUnbackedClaims(input) {
     }
     return unbacked;
 }
+/** Both ways out of a citation rejection, appended to every message so the agent
+ *  never has to guess that dropping the citation is allowed. */
+const CITATION_REMEDY = "Read the file you mean, correct sourceFile/sourceSymbol, and resubmit — or remove the citation if you cannot confirm it in source.";
+/** How many same-basename paths to offer for a missing file. Enough to converge in
+ *  one retry, few enough that the message stays readable. */
+const MAX_PATH_SUGGESTIONS = 3;
+/** True when `abs` names something strictly below `root`. */
+function isInsideRoot(root, abs) {
+    const rel = path.relative(root, abs);
+    return !!rel && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+/**
+ * Resolve a cited path under one checkout, or return null when it lands outside.
+ * A citation names a file INSIDE the repo, so `../../etc/passwd` and an absolute
+ * path from another tree are invalid citations — not files to go looking for.
+ */
+function resolveInRoot(root, cited) {
+    // The contract is a repository-relative path. An absolute one would slip past
+    // the containment check whenever it happens to sit under root, because
+    // path.resolve() discards root — and it is unusable as a review anchor.
+    if (path.isAbsolute(cited))
+        return null;
+    const abs = path.resolve(root, cited);
+    return isInsideRoot(root, abs) ? abs : null;
+}
+/**
+ * Repo-relative paths whose basename equals the cited file's basename, so a
+ * rejection can name the file the agent probably meant. `git ls-files` does the
+ * filtering (a pathspec, not a full listing) to stay cheap on a large repo; a
+ * non-git directory or missing git yields no suggestions rather than an error.
+ */
+async function suggestSimilarPaths(roots, cited) {
+    const base = path.basename(cited);
+    if (!base)
+        return [];
+    const matches = [];
+    for (const root of roots) {
+        try {
+            const { stdout } = await execFileAsync("git", ["ls-files", "-z", "--", `*${base}`, base], {
+                cwd: root,
+            });
+            for (const p of stdout.split("\0")) {
+                // The pathspec also matches "myproducts.py" for "products.py"; keep only
+                // an exact basename hit so a suggestion is a real alternative spelling.
+                if (p && path.basename(p) === base)
+                    matches.push(p);
+            }
+        }
+        catch {
+            // Not a git checkout, or git unavailable — no suggestions to offer.
+        }
+    }
+    return matches.slice(0, MAX_PATH_SUGGESTIONS);
+}
+/**
+ * Check every `sourceFile`/`sourceSymbol` citation on the submitted issuesFound
+ * entries against the repository, and say which repo each one belongs to.
+ * Returns one message per DEFINITE mismatch — an empty `invalid` means the report
+ * may be written — plus, per entry, the owner/repo the citation resolved in.
+ *
+ * The attribution is the reason this resolves against every checkout instead of
+ * the first hit: the consumer must not have to guess a cited file's repo from the
+ * path, which is what makes it link the primary repo's copy of a related repo's
+ * file. Where the citation resolves is the answer, so it is returned rather than
+ * discarded. Only a related repo is stamped: an absent `repository` already means
+ * the primary repo downstream, so a primary-repo citation ships as submitted.
+ *
+ * Rejects four things: a path that no known checkout contains, a symbol absent
+ * from the file that was found, an attribution that names a different repo than
+ * the one holding the code, and a file that resolves in several named checkouts
+ * with no attribution to choose between them. Everything uncertain is ACCEPTED —
+ * no checkout, an unreadable file, a checkout with no owner/repo, a directory
+ * listing that fails. The check must behave the same on any repo, in any
+ * language, at any size, and it must never become a loop the agent cannot exit.
+ * Symbol matching is a plain substring search for the same reason: no parser, so
+ * no language it silently mishandles.
+ */
+export async function findInvalidSourceCitations(input) {
+    const invalid = [];
+    const repository = [];
+    const checkouts = input.checkouts.filter((c) => c.root && c.root !== "unknown");
+    if (checkouts.length === 0)
+        return { invalid, repository }; // Cannot verify anything — accept.
+    const roots = checkouts.map((c) => c.root);
+    for (let i = 0; i < input.issues.length; i++) {
+        const cited = input.issues[i].sourceFile?.trim();
+        if (!cited)
+            continue; // No citation on this entry — nothing to check.
+        const candidates = [];
+        for (const checkout of checkouts) {
+            const abs = resolveInRoot(checkout.root, cited);
+            if (abs)
+                candidates.push({ checkout, abs });
+        }
+        if (candidates.length === 0) {
+            invalid.push(`issuesFound[${i}] cites ${cited}, which resolves outside every repository checkout in this run. ` +
+                `Cite a path inside the checkout, relative to the repository root. ${CITATION_REMEDY}`);
+            continue;
+        }
+        // One relative path can exist in several checkouts of a multi-repo run, and
+        // the citation does not say which one it means. Keep every hit, so the symbol
+        // below is looked for in all of them instead of only the first.
+        const found = [];
+        let unreadable = false;
+        for (const candidate of candidates) {
+            try {
+                if (!(await fs.stat(candidate.abs)).isFile())
+                    continue;
+                // stat() and readFile() both follow symlinks, so a link out of the tree
+                // would let a citation resolve against content outside the checkout.
+                // Compare the real paths before the file counts as found.
+                if (isInsideRoot(await fs.realpath(candidate.checkout.root), await fs.realpath(candidate.abs))) {
+                    found.push(candidate);
+                }
+            }
+            catch (err) {
+                // "Not there" is the answer we want. Any other error (permissions, I/O)
+                // means the check could not run, which is never grounds to reject.
+                if (err.code !== "ENOENT")
+                    unreadable = true;
+            }
+        }
+        if (found.length === 0) {
+            if (unreadable)
+                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(", ")})` : "") +
+                `. ${CITATION_REMEDY}`);
+            continue;
+        }
+        // The citation resolves in every checkout of `found`; a symbol narrows that to
+        // the copies that actually contain it, which is what the attribution below is
+        // taken from.
+        let resolved = found;
+        const symbol = input.issues[i].sourceSymbol?.trim();
+        if (symbol) {
+            const withSymbol = [];
+            let readAny = false;
+            for (const hit of found) {
+                try {
+                    const content = await fs.readFile(hit.abs, "utf8");
+                    readAny = true;
+                    if (content.includes(symbol))
+                        withSymbol.push(hit);
+                }
+                catch {
+                    // Could not read this copy — try the next one.
+                }
+            }
+            if (!readAny)
+                continue; // Could not read any of them — accept.
+            if (withSymbol.length === 0) {
+                invalid.push(`issuesFound[${i}] cites ${symbol} in ${cited}, but that text does not appear anywhere in the file. ` +
+                    CITATION_REMEDY);
+                continue;
+            }
+            resolved = withSymbol;
+        }
+        const attribution = attributeCitation({
+            entry: `issuesFound[${i}]`,
+            cited,
+            symbol,
+            declared: input.issues[i].repository?.trim(),
+            resolved: resolved.map((hit) => hit.checkout),
+        });
+        if (attribution.message)
+            invalid.push(attribution.message);
+        repository[i] = attribution.repository;
+    }
+    return { invalid, repository };
+}
+/** Distinct owner/repo names of the checkouts a citation resolved in, in order.
+ *  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))];
+}
+/**
+ * Reconcile where a citation resolved with what the entry says about it, giving
+ * back the owner/repo to stamp, a rejection message, or neither.
+ */
+function attributeCitation(args) {
+    const { entry, cited, symbol, declared, resolved } = args;
+    const names = namesOf(resolved);
+    const where = symbol ? `${cited} (${symbol})` : cited;
+    if (declared) {
+        // The entry names its repo, so the citation is checked against THAT checkout.
+        // owner/repo is case-insensitive on GitHub, so a differently-cased attribution
+        // is the same repo — accepted, and re-stamped in the run's own spelling rather
+        // 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 };
+        // 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)
+            return {};
+        return {
+            message: `${entry} is attributed to ${declared}, but ${where} resolves in ${names.join(", ")} — not in ${declared}. ` +
+                `Set repository to the repo that holds the code, or cite a file that exists in ${declared}.`,
+        };
+    }
+    if (resolved.length > 1) {
+        // Several checkouts hold this path, and the entry does not say which is meant.
+        if (names.length > 1) {
+            return {
+                message: `${entry} cites ${where}, which exists in more than one repository of this run (${names.join(", ")}), ` +
+                    `and the entry does not say which one it is about. Set repository to the owner/repo whose file you read.`,
+            };
+        }
+        return {}; // Cannot name the alternatives — accept, and stamp nothing.
+    }
+    // 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 };
+}

package/build/utils/reuseRouting.d.ts

@@ -0,0 +1,3 @@
+export declare function isBrowserTestType(testType?: string): boolean;
+export declare function isModularizeFirstTarget(testType?: string, language?: string): boolean;
+export declare function isPomAwareTarget(language: string, framework?: string, testType?: string): boolean;

package/build/utils/reuseRouting.js

@@ -0,0 +1,50 @@
+/**
+ * Routing predicates for the code-reuse flow. Kept apart from the prompt
+ * modules so the generation services can route on them without importing the
+ * prompt text and its POM-catalog dependencies.
+ */
+import { isPomReuseEnabled, isUtilsReuseEnabled } from "./featureFlags.js";
+// Page objects model browser pages — mapping an API-level test onto them is never
+// meaningful, so only browser test types (or an unspecified type, for backwards
+// compatibility) may take the POM path regardless of the feature flag.
+export function isBrowserTestType(testType) {
+    return testType === undefined || testType === "ui" || testType === "e2e";
+}
+// Modularize-first flows: fresh codegen output carries no helper functions, so
+// skyramp_modularization runs BEFORE skyramp_reuse_code and the reuse pass seeds
+// the shared utils file from the helpers it created. The utils flag is the
+// single gate for every test type — the modularization prompts' per-step
+// extraction reads the same predicate, so the hand-off, the extraction and the
+// seeding step agree on every codeReuse flow. Integration qualifies whenever the flag is on;
+// UI only while the POM path is off (POM refactoring supersedes modularization,
+// and the testbot UI flow asks for codeReuse unconditionally, so the flag is what
+// keeps the default-off behavior a no-op reuse pass). e2e and load are not
+// routed here: load has no modularization routing at all, e2e is deferred.
+// Deliberately keyed on the POM *flag*, not on isPomAwareTarget: with the flag
+// on, a UI target the POM path does not cover keeps today's plain reuse pass.
+// Composing utils reuse with the POM path is a separate change; this predicate
+// only decides the flag-off UI flow. The modularization prompts read it too, so
+// extraction and seeding agree for every codeReuse flow; a modularizeCode-only
+// call (no codeReuse) still receives the shared-helper rules — harmless without
+// a reuse pass, and the tool cannot see codeReuse.
+export function isModularizeFirstTarget(testType, language) {
+    if (!isUtilsReuseEnabled())
+        return false;
+    if (testType === "integration")
+        return true;
+    if (testType !== "ui" || isPomReuseEnabled())
+        return false;
+    // Shared browser helpers are Playwright TS/JS; other UI languages have no
+    // utils-file convention here and would fall through to a Python file name.
+    const lang = language?.toLowerCase();
+    return lang === "typescript" || lang === "javascript";
+}
+export function isPomAwareTarget(language, framework, testType) {
+    if (!isPomReuseEnabled())
+        return false;
+    if (!isBrowserTestType(testType))
+        return false;
+    const lang = language.toLowerCase();
+    return ((lang === "typescript" || lang === "javascript") &&
+        framework?.toLowerCase() === "playwright");
+}

package/build/utils/routeParsers.d.ts

@@ -35,6 +35,8 @@ export declare function parseRouteLine(line: string, sourceFile: string): Parsed
  * aggregator's `APIRouter(prefix="/api")` yields `/api/recipes`, not `/recipes`.
  */
 export declare function parseFileEndpoints(content: string, sourceFile: string, mountPrefixes?: Map<string, string>): ParsedDiffEndpoint[];
+export declare function isParamSegment(segment: string): boolean;
+export declare function isOpaqueIdSegment(segment: string): boolean;
 export declare const SKIP_PATH_SEGMENTS: Set<string>;
 /**
  * True for version/prefix path segments — "v1".."v99" and the literal "api".

package/build/utils/routeParsers.js

@@ -127,10 +127,27 @@ export function parseRouteLine(line, sourceFile) {
             };
         }
     }
-    // Go (Gin, Echo, Chi): <ident>.GET/POST/...("/path", handler)
-    const ginMatch = stripped.match(/(?:\w+)\.(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s*\(\s*["']([^"'?#]+)/i);
-    if (ginMatch && sourceFile.endsWith(".go")) {
-        return { method: ginMatch[1].toUpperCase(), path: ginMatch[2], sourceFile };
+    // Go (Gin, Echo, Chi): <ident>.GET/POST/...("path", handler)
+    //
+    // An all-caps method token (Gin/Echo convention: `g.GET(...)`, `r.POST(...)`)
+    // is unambiguously a route registration — nobody writes `query.GET(...)` — so
+    // it's accepted even without a leading slash (real Gin routes like
+    // `g.GET("ping", ...)` omit it). A CamelCase token (Chi's `r.Get`/`r.Post`)
+    // shares call syntax with a plain getter — `query.Get("term")`,
+    // `Header.Get("Accept-Version")` — so it only counts as a route when the
+    // captured path starts with "/", which every Chi route does and a getter's
+    // argument never does.
+    const ginUpperMatch = stripped.match(/\w+\.(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s*\(\s*["']([^"'?#]+)/);
+    if (ginUpperMatch && sourceFile.endsWith(".go")) {
+        return { method: ginUpperMatch[1], path: ginUpperMatch[2], sourceFile };
+    }
+    const ginCamelMatch = stripped.match(/\w+\.(Get|Post|Put|Patch|Delete|Head|Options)\s*\(\s*["'](\/[^"'?#]*)/);
+    if (ginCamelMatch && sourceFile.endsWith(".go")) {
+        return {
+            method: ginCamelMatch[1].toUpperCase(),
+            path: ginCamelMatch[2],
+            sourceFile,
+        };
     }
     // Go stdlib: http.HandleFunc/Handle
     const goHandleMatch = stripped.match(/(?:HandleFunc|Handle)\s*\(\s*["']([^"'?#]+)/);
@@ -490,6 +507,45 @@ export function parseFileEndpoints(content, sourceFile, mountPrefixes) {
         path: ep.path && !ep.path.startsWith("/") ? `/${ep.path}` : ep.path,
     }));
 }
+/**
+ * One path segment that names a parameter rather than a resource, in any route
+ * syntax the scanners read: OpenAPI "{id}", Express/NestJS ":id", and Next.js
+ * "[id]" / "[...id]" / "[[...id]]" (the double-bracket form needs its own
+ * alternative — it contains an inner "]", which the single-bracket form's
+ * [^\]]+ can never span).
+ */
+// The colon form may carry an Express/Fastify constraint or modifier —
+// `:id(\d+)`, `:id?`, `:id*`, `:id+`. Those are still parameters, and a
+// resource name is never one, so the predicate has to accept them or
+// extractResourceFromPath returns the whole segment as the resource.
+const PARAM_SEGMENT_RE = /^\{[^}]+\}$|^:[A-Za-z_]\w*(?:\([^)]*\))?[?*+]?$|^\[\[[^\]]+\]\]$|^\[[^\]]+\]$/;
+export function isParamSegment(segment) {
+    return PARAM_SEGMENT_RE.test(segment);
+}
+/**
+ * One path segment that is an id VALUE rather than a name: a UUID, digits only,
+ * or a long hex run (a Mongo ObjectId is 24). A caller writes a literal id in a
+ * path where the route declares a parameter, and an id can never be a resource
+ * name, so resource derivation must skip it exactly as it skips a parameter.
+ * SKYR-4214: an accepted UUID produced the key
+ * "DELETE::a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11::integration", which matches
+ * nothing, so the candidate escaped dedup entirely.
+ *
+ * The 16-character floor on the hex rule keeps real resource names safe: a name
+ * built only from the letters a-f and digits, 16 characters or longer, is not a
+ * word.
+ */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isOpaqueIdSegment(segment) {
+    // The sign belongs to the value: an edge-case step writes `/orders/-1` to
+    // probe a negative id, and without the sign that segment became the resource
+    // name, so the key could never match real order coverage.
+    return UUID_RE.test(segment) || /^-?\d+$/.test(segment) || /^[0-9a-f]{16,}$/i.test(segment);
+}
+/** A segment that names neither a resource nor a sub-resource. */
+function isNonResourceSegment(segment) {
+    return isParamSegment(segment) || isOpaqueIdSegment(segment);
+}
 export const SKIP_PATH_SEGMENTS = new Set(["api", "v1", "v2", "v3", "public"]);
 /**
  * True for version/prefix path segments — "v1".."v99" and the literal "api".
@@ -510,14 +566,15 @@ export function isVersionLikeSegment(segment) {
  */
 export function extractResourceFromPath(endpointPath) {
     const segments = endpointPath.split("/").filter(Boolean);
-    const meaningful = segments.filter((s) => !s.startsWith("{") && !SKIP_PATH_SEGMENTS.has(s));
+    const meaningful = segments.filter((s) => !isNonResourceSegment(s) && !SKIP_PATH_SEGMENTS.has(s));
     if (meaningful.length === 0)
         return "unknown";
-    // Sub-resource pattern: /…/<parent>/{param}/<child>
-    // Detected when the last raw segment is non-param and the second-to-last is a param.
+    // Sub-resource pattern: /…/<parent>/<id>/<child>
+    // Detected when the last raw segment names a resource and the one before it
+    // does not — an id in any spelling, not only "{param}".
     const last = segments[segments.length - 1];
     const secondLast = segments.length >= 2 ? segments[segments.length - 2] : "";
-    if (!last.startsWith("{") && secondLast.startsWith("{") && meaningful.length >= 2) {
+    if (!isNonResourceSegment(last) && isNonResourceSegment(secondLast) && meaningful.length >= 2) {
         return `${meaningful[meaningful.length - 2]}_${meaningful[meaningful.length - 1]}`;
     }
     return meaningful[meaningful.length - 1];

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 (new_endpoint / diff-direct) scenarios prioritized first.
+ * 1. CRITICAL (bug_caught) 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

@@ -4,6 +4,8 @@ import { CATEGORY_PRIORITY, PriorityTier } from "../types/TestRecommendation.js"
 import { inferExpectedStatus } from "./httpDefaults.js";
 import { WorkspaceAuthType } from "./workspaceAuth.js";
 import { deriveResourceToken } from "./importerHop.js";
+import { isSegmentPrefix, pathSuffixMatches } from "./pathMatching.js";
+import { singularize } from "./pluralization.js";
 // Only tokens that are structurally non-testable (meta, infra, static assets).
 // Semantic tokens like login, search, webhook, payment are removed — the LLM
 // already knows how to handle them and the filter was suppressing valid surfaces.
@@ -19,35 +21,10 @@ function extractExecutionVerb(endpointPath) {
     const match = EXECUTION_SUFFIX.exec(endpointPath);
     return match ? match[1].toLowerCase() : "execute";
 }
-/**
- * Returns true when `a` starts with `b` at a path-segment boundary.
- * Plain `startsWith` is not sufficient — "/orders-archive".startsWith("/orders") is true
- * even though they are different resources. Requiring the next character to be "/" or
- * end-of-string ensures only genuine path prefixes are matched.
- */
-const isSegmentPrefix = (a, b) => a.startsWith(b) && (a[b.length] === "/" || a[b.length] === undefined);
 export function isRealResource(r) {
     return !ACTION_PATTERN.test(r) && !ACTION_VERB_HYPHEN.test(r);
 }
 const SKIP_SEGMENTS = new Set(["api", "v1", "v2", "v3", "public"]);
-/**
- * Convert a plural resource name to its singular form for use in field names
- * and step descriptions.
- *
- * Handles the most common irregular plurals found in REST API paths:
- *   -ies → -y  (categories → category, companies → company)
- *   -ses → -s  (statuses → status, classes → class)
- * Falls back to removing the trailing "s" for regular plurals.
- */
-function singularize(word) {
-    if (word.endsWith("ies") && word.length > 3) {
-        return word.slice(0, -3) + "y";
-    }
-    if (word.endsWith("ses") && word.length > 4) {
-        return word.slice(0, -2); // statuses → status
-    }
-    return word.endsWith("s") && word.length > 1 ? word.slice(0, -1) : word;
-}
 /**
  * Extract the primary resource name from an endpoint path.
  * E.g. "/api/v1/flow-costs/{cost_id}" → "flow-costs"
@@ -145,10 +122,38 @@ export function inferResourceRelationships(endpoints) {
 }
 export function draftScenariosFromEndpoints(endpoints, newEndpoints = [], wsAuthType, options = {}, removedEndpoints = []) {
     const scenarios = [];
+    // A drafted step path reaches the agent as the plan's `endpoint` and as the
+    // URL the generated test calls, so it has to be the spelling an HTTP client
+    // accepts. A route scanned from Express or NestJS source arrives as
+    // `/members/:uid`; the agent then spends one of its two repair attempts
+    // fixing the URL. Measured on eval run 32606742433, fixture
+    // cc15-org-reviewer-role: "2-attempt limit reached after URL fix", and the
+    // test failed on an unrelated assertion it had no attempt left to correct.
+    //
+    // Normalize here, at the one place the drafter reads an endpoint, rather than
+    // rewriting every stored route: `extractResourceFromPath` already treats both
+    // spellings as a parameter, so nothing else in the pipeline needs the change.
+    // Every path this function compares must be normalized together. Converting
+    // `endpoints` alone made the attack-surface sibling search compare a brace
+    // path against a colon `changedEndpoints` entry and find nothing.
+    endpoints = endpoints.map((ep) => ({ ...ep, path: toBraceParams(ep.path) }));
+    newEndpoints = newEndpoints.map((ep) => ({ ...ep, path: toBraceParams(ep.path) }));
+    removedEndpoints = removedEndpoints.map((ep) => ({ ...ep, path: toBraceParams(ep.path) }));
+    if (options.changedEndpoints) {
+        options = {
+            ...options,
+            changedEndpoints: options.changedEndpoints.map((ep) => ({ ...ep, path: toBraceParams(ep.path) })),
+        };
+    }
     const resourceGroups = new Map();
     for (const ep of endpoints) {
         const segments = ep.path.split("/").filter(Boolean);
-        const nonParamSegs = segments.filter(s => !s.startsWith("{") && !SKIP_SEGMENTS.has(s));
+        // Was `!s.startsWith("{")` — brace-only, so a colon-style segment became the
+        // resource and the drafted scenario was named ":uid-delete-auth-boundary".
+        // `isPathParam` is this file's own predicate and already accepts both forms;
+        // it deliberately does NOT reject a literal id (see its comment, SKYR-4229),
+        // so this changes the param spelling only.
+        const nonParamSegs = segments.filter(s => !isPathParam(s) && !SKIP_SEGMENTS.has(s));
         const resource = nonParamSegs[nonParamSegs.length - 1] || "unknown";
         const hasParam = /\{/.test(ep.path);
         const resourceSegIdx = segments.lastIndexOf(resource);
@@ -221,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 (new_endpoint / diff-direct) scenarios prioritized first.
+ * 1. CRITICAL (bug_caught) 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.
@@ -254,9 +259,13 @@ export function capScenarios(scenarios) {
 }
 // ── Diff-direct scenario drafting ──
 // Generates targeted scenarios for each new endpoint in the branch diff.
-// These get category "new_endpoint" which maps to the CRITICAL priority tier
-// in the scorer, so they always fill the GENERATE slots before any structural
-// scenario — aligning the plan with what the LLM naturally wants to do anyway.
+// These get category "new_endpoint", which maps to the MEDIUM priority tier in
+// the scorer — BELOW business_rule, security_boundary and the other categories
+// that state what a test proves. They compete for GENERATE slots on merit
+// rather than auto-filling ahead of everything else; CRITICAL is reserved for
+// bug_caught, which targets an actually identified flaw. Level with the
+// structural categories was still too high: the last rank key is the
+// candidateId, so among same-tier candidates the alphabet decided.
 /**
  * Build the minimum steps for a diff-direct integration scenario.
  * Prerequisite resources (e.g. POST /products before POST /orders) are NOT
@@ -525,9 +534,27 @@ const SOURCE_RESOURCE_SKIP_SEGMENTS = new Set([
     ...SKIP_SEGMENTS,
     "app", "apps", "handler", "handlers", "index", "page", "pages", "route", "routes", "router", "server", "src",
 ]);
+/**
+ * `:name` to `{name}`, including an Express/Fastify constraint or modifier
+ * (`:id(\d+)`, `:id?`). The match starts at a segment boundary and needs a
+ * letter or underscore first, so a port or a mid-segment colon is left alone.
+ * Next.js `[id]` stays as written — those mirror file paths.
+ */
+function toBraceParams(path) {
+    return (path ?? "").replace(/(^|\/):([A-Za-z_]\w*)(\([^)]*\))?[?*+]?/g, "$1{$2}");
+}
 function pathSegments(path) {
     return path.split("/").filter(Boolean);
 }
+/**
+ * Recognises a declared parameter, NOT a literal id value. A UUID, digits or a
+ * long hex segment reads as a resource name here, unlike routeParsers.ts's
+ * isParamSegment + isOpaqueIdSegment. So `collectionPathForChangedEndpoint`
+ * does not reduce `/orders/<uuid>` to `/orders`, and no attack-surface
+ * auth-boundary scenario is drafted for that endpoint. Left as-is on purpose:
+ * fixing it drafts MORE scenarios, which needs measurement. SKYR-4229 tracks
+ * it; pathSegmentClassification.characterization.test.ts pins today's answer.
+ */
 function isPathParam(segment) {
     return /^\{[^}]+\}$/.test(segment) ||
         /^:[A-Za-z_][A-Za-z0-9_]*$/.test(segment) ||
@@ -733,21 +760,6 @@ export function draftDiffDirectScenarios(newEndpoints, resourceGroups, wsAuthTyp
         methods.add(ep.method.toUpperCase());
         grouped.set(ep.path, methods);
     }
-    // Segment-boundary suffix match: avoids "/orders" matching "/preorders".
-    const pathSuffixMatches = (fullPath, suffix) => {
-        if (fullPath === suffix)
-            return true;
-        const fullSegs = fullPath.split("/").filter(Boolean);
-        const suffixSegs = suffix.split("/").filter(Boolean);
-        if (suffixSegs.length === 0 || suffixSegs.length > fullSegs.length)
-            return false;
-        const offset = fullSegs.length - suffixSegs.length;
-        for (let i = 0; i < suffixSegs.length; i++) {
-            if (fullSegs[offset + i] !== suffixSegs[i])
-                return false;
-        }
-        return true;
-    };
     for (const [epPath, methods] of grouped) {
         let resource = extractResourceName(epPath);
         let resolvedPath = epPath;

package/build/utils/subjectEndpoints.d.ts

@@ -0,0 +1,19 @@
+import { DraftedScenario, SubjectEndpoint } from "../types/RepositoryAnalysis.js";
+import { ChangedRoute } from "./changedRoutes.js";
+export type { SubjectEndpoint };
+/**
+ * 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 declare function resolveSubjectEndpoints(scenario: DraftedScenario, opts: {
+    changedRoutes?: ChangedRoute[];
+}): SubjectEndpoint[];