@skyramp/mcp 0.3.1 → 0.3.2-rc.pom-2

package/build/types/Recommendation.d.ts

@@ -0,0 +1,97 @@
+import { DraftedScenario } from "../types/RepositoryAnalysis.js";
+import { Novelty, PriorityTier } from "../types/TestRecommendation.js";
+/**
+ * The structural bug-shape a candidate claims to probe. Verified against the
+ * candidate's `steps[]` by `validateDiscriminator` (discriminators.ts); a claim
+ * that does not survive verification is demoted, never used to reject.
+ */
+export declare enum DiscriminatorKind {
+    BOUNDARY_EQUALITY = "boundary_equality",
+    MULTI_RECORD_AGGREGATE = "multi_record_aggregate",
+    STATE_TRANSITION = "state_transition",
+    NEGATIVE_MATCH = "negative_match"
+}
+/** Who drafted a candidate: the LLM loop, or the MCP server's own pre-ranking. */
+export declare enum CandidateSource {
+    AGENT = "agent",
+    SERVER = "server"
+}
+/**
+ * A ranked test candidate — the existing scored scenario plus the fields the
+ * budgeting stage reads. Matches the shape produced today by the scoring block
+ * in test-recommendation-prompt.ts (`{ scenario, priority, novelty }`), extended
+ * for the SKYR-3879 Path B register-plan checkpoint with provenance, a stable id
+ * and the verified-discriminator marker the ranker reads.
+ */
+export interface Candidate {
+    scenario: DraftedScenario;
+    priority: PriorityTier;
+    novelty: Novelty;
+    /** Who drafted this candidate: the LLM loop or the MCP server. */
+    source: CandidateSource;
+    /**
+     * Stable, deterministic id: slugified `scenarioName` + short content hash.
+     * Reproducible across calls (same scenario → same id) so the generation-tool
+     * plan guard can match a generated test back to its approved candidate.
+     */
+    candidateId: string;
+    /**
+     * Set by the caller AFTER `validateDiscriminator` succeeds for a declared
+     * discriminator. Present only when the structural claim was verified against
+     * `steps[]` and the diff anchor; the ranker floats these ahead of unverified
+     * peers. Absent = no verified discriminator (unclaimed or demoted).
+     */
+    verifiedDiscriminator?: DiscriminatorKind;
+}
+/** Environment-derived inputs a Budgeter needs to split GENERATE vs ADDITIONAL. */
+export interface BudgetContext {
+    /** Upper bound on GENERATE items (a strategy parameter, formerly the hard cap). */
+    maxGenerate: number;
+    /** Total recommendations (GENERATE + ADDITIONAL); today's `topN`. */
+    maxTotal: number;
+    isUIOnlyPR: boolean;
+    hasFrontendChanges: boolean;
+    /** Method-aware coverage keys of external tests; matching candidates are dropped. */
+    externalCoverage: Set<string>;
+}
+/** A demoted claim: which candidate, and the human-readable reason returned to
+ *  the agent so it can fix the claim (never a silent drop). */
+export interface Demotion {
+    candidateId: string;
+    reason: string;
+}
+/** Result of budgeting: the GENERATE set, the ADDITIONAL set, how many UI
+ *  placeholder slots the render layer should add (mixed/UI-only PRs), and the
+ *  demoted-claim channel (the missing rejection surface for register-plan). */
+export interface SelectionResult {
+    generate: Candidate[];
+    additional: Candidate[];
+    reservedUISlots: number;
+    demotions: Demotion[];
+}
+/** A pluggable budgeting algorithm. Deterministic and pure. */
+export interface Budgeter {
+    readonly name: string;
+    select(ranked: Candidate[], ctx: BudgetContext): SelectionResult;
+}
+/**
+ * Deterministic candidate id: a slug of the scenario name plus an 8-char content
+ * hash. Pure and reproducible — the same scenario always yields the same id, so
+ * a candidate registered in the plan can be matched back when its test is later
+ * generated. The hash covers the salient, stable structural fields (name,
+ * category, testType, and each step's method/path/interactionType/status) so
+ * cosmetic re-serialization does not change the id while a real edit does.
+ */
+export declare function computeCandidateId(scenario: DraftedScenario): string;
+/** One approved plan item as persisted in `UnifiedAnalysisState.approvedPlan`.
+ *  Deliberately slim (no steps/requestBody/etc.) — `matchKeys` already carries
+ *  everything a downstream matcher needs. */
+export interface ApprovedPlanItem {
+    candidateId: string;
+    scenarioName: string;
+    testType: string;
+    category: string;
+    source: CandidateSource;
+    verifiedDiscriminator?: string;
+    matchKeys: string[];
+}

package/build/types/Recommendation.js

@@ -0,0 +1,48 @@
+import * as crypto from "crypto";
+/**
+ * The structural bug-shape a candidate claims to probe. Verified against the
+ * candidate's `steps[]` by `validateDiscriminator` (discriminators.ts); a claim
+ * that does not survive verification is demoted, never used to reject.
+ */
+export var DiscriminatorKind;
+(function (DiscriminatorKind) {
+    DiscriminatorKind["BOUNDARY_EQUALITY"] = "boundary_equality";
+    DiscriminatorKind["MULTI_RECORD_AGGREGATE"] = "multi_record_aggregate";
+    DiscriminatorKind["STATE_TRANSITION"] = "state_transition";
+    DiscriminatorKind["NEGATIVE_MATCH"] = "negative_match";
+})(DiscriminatorKind || (DiscriminatorKind = {}));
+/** Who drafted a candidate: the LLM loop, or the MCP server's own pre-ranking. */
+export var CandidateSource;
+(function (CandidateSource) {
+    CandidateSource["AGENT"] = "agent";
+    CandidateSource["SERVER"] = "server";
+})(CandidateSource || (CandidateSource = {}));
+/**
+ * Deterministic candidate id: a slug of the scenario name plus an 8-char content
+ * hash. Pure and reproducible — the same scenario always yields the same id, so
+ * a candidate registered in the plan can be matched back when its test is later
+ * generated. The hash covers the salient, stable structural fields (name,
+ * category, testType, and each step's method/path/interactionType/status) so
+ * cosmetic re-serialization does not change the id while a real edit does.
+ */
+export function computeCandidateId(scenario) {
+    const slugSource = scenario.scenarioName ?? "";
+    const slug = slugSource
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48) || "scenario";
+    const canonical = {
+        scenarioName: scenario.scenarioName ?? "",
+        category: scenario.category ?? "",
+        testType: scenario.testType ?? "",
+        steps: (scenario.steps ?? []).map((s) => ({
+            method: s?.method ?? "",
+            path: s?.path ?? "",
+            interactionType: s?.interactionType ?? "",
+            expectedStatusCode: s?.expectedStatusCode ?? 0,
+        })),
+    };
+    const hash = crypto.createHash("sha256").update(JSON.stringify(canonical)).digest("hex").slice(0, 8);
+    return `${slug}-${hash}`;
+}

package/build/types/RepositoryAnalysis.d.ts

@@ -1309,25 +1309,25 @@ export declare const branchDiffContextSchema: z.ZodObject<{
         }, "strip", z.ZodTypeAny, {
             method: string;
             sourceFile: string;
-            changeType: "added" | "modified" | "removed";
+            changeType: "modified" | "added" | "removed";
         }, {
             method: string;
             sourceFile: string;
-            changeType: "added" | "modified" | "removed";
+            changeType: "modified" | "added" | "removed";
         }>, "many">;
     }, "strip", z.ZodTypeAny, {
         path: string;
         methods: {
             method: string;
             sourceFile: string;
-            changeType: "added" | "modified" | "removed";
+            changeType: "modified" | "added" | "removed";
         }[];
     }, {
         path: string;
         methods: {
             method: string;
             sourceFile: string;
-            changeType: "added" | "modified" | "removed";
+            changeType: "modified" | "added" | "removed";
         }[];
     }>, "many">;
     removedEndpoints: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -1379,7 +1379,7 @@ export declare const branchDiffContextSchema: z.ZodObject<{
         methods: {
             method: string;
             sourceFile: string;
-            changeType: "added" | "modified" | "removed";
+            changeType: "modified" | "added" | "removed";
         }[];
     }[];
     affectedServices: string[];
@@ -1409,7 +1409,7 @@ export declare const branchDiffContextSchema: z.ZodObject<{
         methods: {
             method: string;
             sourceFile: string;
-            changeType: "added" | "modified" | "removed";
+            changeType: "modified" | "added" | "removed";
         }[];
     }[];
     affectedServices: string[];
@@ -2483,25 +2483,25 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             }, "strip", z.ZodTypeAny, {
                 method: string;
                 sourceFile: string;
-                changeType: "added" | "modified" | "removed";
+                changeType: "modified" | "added" | "removed";
             }, {
                 method: string;
                 sourceFile: string;
-                changeType: "added" | "modified" | "removed";
+                changeType: "modified" | "added" | "removed";
             }>, "many">;
         }, "strip", z.ZodTypeAny, {
             path: string;
             methods: {
                 method: string;
                 sourceFile: string;
-                changeType: "added" | "modified" | "removed";
+                changeType: "modified" | "added" | "removed";
             }[];
         }, {
             path: string;
             methods: {
                 method: string;
                 sourceFile: string;
-                changeType: "added" | "modified" | "removed";
+                changeType: "modified" | "added" | "removed";
             }[];
         }>, "many">;
         removedEndpoints: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -2553,7 +2553,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             methods: {
                 method: string;
                 sourceFile: string;
-                changeType: "added" | "modified" | "removed";
+                changeType: "modified" | "added" | "removed";
             }[];
         }[];
         affectedServices: string[];
@@ -2583,7 +2583,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             methods: {
                 method: string;
                 sourceFile: string;
-                changeType: "added" | "modified" | "removed";
+                changeType: "modified" | "added" | "removed";
             }[];
         }[];
         affectedServices: string[];
@@ -2785,7 +2785,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             methods: {
                 method: string;
                 sourceFile: string;
-                changeType: "added" | "modified" | "removed";
+                changeType: "modified" | "added" | "removed";
             }[];
         }[];
         affectedServices: string[];
@@ -2987,7 +2987,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             methods: {
                 method: string;
                 sourceFile: string;
-                changeType: "added" | "modified" | "removed";
+                changeType: "modified" | "added" | "removed";
             }[];
         }[];
         affectedServices: string[];

package/build/types/TestExecution.d.ts

@@ -37,6 +37,8 @@ export interface BatchExecutionResult {
 export interface TestExecutionOptions {
     testFile: string;
     workspacePath: string;
+    /** Cross-repo test repository root (testsRepoDir) when testFile was delivered outside workspacePath (SKYR-3819). */
+    testRepoPath?: string;
     language: string;
     testType: string;
     token?: string;

package/build/types/TestRecommendation.d.ts

@@ -1,5 +1,16 @@
 /** Internal scenario-scoring tier — UPPERCASE, includes CRITICAL. */
-export type PriorityTier = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+export declare enum PriorityTier {
+    CRITICAL = "CRITICAL",
+    HIGH = "HIGH",
+    MEDIUM = "MEDIUM",
+    LOW = "LOW"
+}
+/** How a scenario relates to the diff — tie-breaker within a priority tier. */
+export declare enum Novelty {
+    NEW = "new",
+    MODIFIED = "modified",
+    EXISTING = "existing"
+}
 /** All categories including internal ones. */
 export declare const SCENARIO_CATEGORIES: readonly ["new_endpoint", "bug_caught", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"];
 export type ScenarioCategory = typeof SCENARIO_CATEGORIES[number];

package/build/types/TestRecommendation.js

@@ -1,3 +1,18 @@
+/** Internal scenario-scoring tier — UPPERCASE, includes CRITICAL. */
+export var PriorityTier;
+(function (PriorityTier) {
+    PriorityTier["CRITICAL"] = "CRITICAL";
+    PriorityTier["HIGH"] = "HIGH";
+    PriorityTier["MEDIUM"] = "MEDIUM";
+    PriorityTier["LOW"] = "LOW";
+})(PriorityTier || (PriorityTier = {}));
+/** How a scenario relates to the diff — tie-breaker within a priority tier. */
+export var Novelty;
+(function (Novelty) {
+    Novelty["NEW"] = "new";
+    Novelty["MODIFIED"] = "modified";
+    Novelty["EXISTING"] = "existing";
+})(Novelty || (Novelty = {}));
 /** Internal-only categories (not submitted to tools). */
 const INTERNAL_CATEGORIES = [
     "new_endpoint", // CRITICAL - diff-direct scenarios always fill GENERATE slots first
@@ -24,17 +39,17 @@ export const SCENARIO_CATEGORIES = [...INTERNAL_CATEGORIES, ...CATEGORIES];
 export const TEST_CATEGORIES = CATEGORIES;
 /** Priority assignment for each category. */
 export const CATEGORY_PRIORITY = {
-    new_endpoint: "CRITICAL",
-    bug_caught: "CRITICAL", // tests targeting a <bug_found> flaw — always in GENERATE
-    business_rule: "HIGH", // formula/business-logic bugs are high priority but CRITICAL is reserved for new-endpoint diff-direct scenarios
-    security_boundary: "HIGH",
-    data_integrity: "HIGH",
-    breaking_change: "HIGH",
-    auth: "HIGH",
-    error_handling: "HIGH",
-    workflow: "MEDIUM",
-    data_validation: "MEDIUM",
-    crud: "LOW",
+    new_endpoint: PriorityTier.CRITICAL,
+    bug_caught: PriorityTier.CRITICAL, // tests targeting a <bug_found> flaw — always in GENERATE
+    business_rule: PriorityTier.HIGH, // formula/business-logic bugs are high priority but CRITICAL is reserved for new-endpoint diff-direct scenarios
+    security_boundary: PriorityTier.HIGH,
+    data_integrity: PriorityTier.HIGH,
+    breaking_change: PriorityTier.HIGH,
+    auth: PriorityTier.HIGH,
+    error_handling: PriorityTier.HIGH,
+    workflow: PriorityTier.MEDIUM,
+    data_validation: PriorityTier.MEDIUM,
+    crud: PriorityTier.LOW,
 };
 /** Map internal-only categories to their external equivalent for tool submission. */
 export function externalCategory(cat) {

package/build/types/TestTypes.js

@@ -243,7 +243,7 @@ export const codeRefactoringSchema = z.object({
     codeReuse: z
         .boolean()
         .default(false)
-        .describe("Whether to reuse existing code"),
+        .describe("Reuse existing code in the generated test — for TS/JS Playwright tests this refactors the test to use the repo's existing Page Object Model"),
     modularizeCode: z
         .boolean()
         .default(false)

package/build/utils/AnalysisStateManager.d.ts

@@ -4,6 +4,7 @@ import { PRTestContext } from "./pr-comment-parser.js";
 import { ParsedDiffEndpoint } from "./routeParsers.js";
 import type { CandidateUiPage } from "./uiPageEnumerator.js";
 import type { FrontendFileIntegration } from "../types/FrontendIntegration.js";
+import type { ApprovedPlanItem } from "../types/Recommendation.js";
 export type { CandidateUiPage } from "./uiPageEnumerator.js";
 export declare function setTestsRepoDir(dir: string | undefined): void;
 export declare function getTestsRepoDir(): string | undefined;
@@ -65,6 +66,41 @@ export interface UiAnalysisContext {
      */
     frontendFileIntegration?: FrontendFileIntegration[];
 }
+/**
+ * SKYR-3879 Path B — the server-side selection checkpoint's persisted result.
+ * Written by skyramp_register_test_plan (and pre-seeded by skyramp_analyze_changes
+ * when it has its own pre-ranked GENERATE items). `generate` is the mandated,
+ * final list generation tools gate against (see planGuard.ts); `additional` is
+ * report-only; `demotions` carries discriminator claims that failed structural
+ * verification (the candidate itself is never dropped, only the claim).
+ */
+export interface ApprovedPlan {
+    planId: string;
+    createdAt: string;
+    generate: ApprovedPlanItem[];
+    additional: ApprovedPlanItem[];
+    demotions: Array<{
+        candidateId: string;
+        reason: string;
+    }>;
+}
+/**
+ * Budget inputs computed once by skyramp_analyze_changes (from the same
+ * classification the Execution Plan prompt is built from) and reused by
+ * skyramp_register_test_plan, so re-ranking the agent's candidates never
+ * drifts from the budget the agent was shown. Persisted even when no
+ * `approvedPlan` is pre-seeded (e.g. no pre-drafted scenarios) so a
+ * register_test_plan call with only agent-drafted candidates still budgets
+ * against the correct maxGenerate/maxTotal/UI split.
+ */
+export interface PlanBudgetContext {
+    maxGenerate: number;
+    maxTotal: number;
+    isUIOnlyPR: boolean;
+    hasFrontendChanges: boolean;
+    /** Serialized form of the BudgetContext.externalCoverage Set. */
+    externalCoverageKeys: string[];
+}
 /**
  * Unified state data combining test discovery + endpoint scanning
  * Used by the unified test-management workflow
@@ -86,6 +122,17 @@ export interface UnifiedAnalysisState {
     /** Maintenance actions applied via skyramp_actions — skyramp_submit_report derives
      *  testMaintenance from this. */
     maintenanceVerdicts?: MaintenanceActionCore[];
+    /**
+     * Raw branch-diff text, size-capped (~200KB), persisted so
+     * skyramp_register_test_plan can verify a discriminator's `changedCodeAnchor`
+     * occurs verbatim in the actual diff. Absent when the analysis wasn't
+     * diff-scoped or no diff content was produced.
+     */
+    diffText?: string;
+    /** SKYR-3879 Path B — see {@link PlanBudgetContext}. */
+    planBudgetContext?: PlanBudgetContext;
+    /** SKYR-3879 Path B — see {@link ApprovedPlan}. */
+    approvedPlan?: ApprovedPlan;
 }
 /**
  * State file metadata

package/build/utils/docker.test.js

@@ -55,7 +55,7 @@ describe("dockerImageExistsLocally", () => {
     });
 });
 describe("pullDockerImage", () => {
-    const IMAGE = "skyramp/executor:v1.3.34";
+    const IMAGE = "skyramp/executor:v1.3.35";
     beforeEach(() => jest.clearAllMocks());
     describe("on amd64 host", () => {
         const originalArch = process.arch;

package/build/utils/planMatchKeys.d.ts

@@ -0,0 +1,61 @@
+/**
+ * SKYR-3879 Path B — shared match-key computation for the register-plan
+ * checkpoint. `computeMatchKeys` runs ONCE, at approval time (inside
+ * registerTestPlanTool / the analyze_changes pre-seed), so the two
+ * consumers — planGuard (generation-tool hard gate) and submitReportTool
+ * (report cross-check) — only ever do a Set/array membership check, never
+ * re-derive normalization logic against a live candidate.
+ *
+ * Two kinds of key:
+ *  - `name:<slug>`               — normalized scenarioName, for multi-step
+ *    candidates (batch-scenario / integration) where the agent's own name is
+ *    the natural join key.
+ *  - `ep:<testType>:<METHOD>:<path>` — one per step, for single-endpoint
+ *    matching (contract tests, or a fallback when names drift between
+ *    register and generate).
+ */
+import { DraftedScenario } from "../types/RepositoryAnalysis.js";
+import { ApprovedPlanItem, Candidate } from "../types/Recommendation.js";
+/** Query shape built from a generation-tool call or a submitted report entry. */
+export interface PlanMatchQuery {
+    scenarioName?: string;
+    testType?: string;
+    method?: string;
+    path?: string;
+}
+/** Lowercase, collapse non-alphanumeric runs to '-', trim leading/trailing '-'. */
+export declare function slugifyName(name: string | undefined): string;
+/**
+ * Normalize a path so param segments collapse: numeric ids, `{brace}` params,
+ * `:colon` params, and long hex/uuid segments all become `:p`. Mirrors
+ * discriminators.ts's normalizePath (duplicated here rather than imported —
+ * that function verifies discriminator claims against a diff, a different
+ * concern from plan matching, and keeping them independent avoids coupling
+ * this module's stability to phase 1's internal helper).
+ */
+export declare function normalizeMatchPath(rawPath: string | undefined): string;
+/** Name key (if a name exists) plus one endpoint key per step. */
+export declare function computeMatchKeys(scenario: DraftedScenario): string[];
+/** Build the persisted plan item from a ranked Candidate. */
+export declare function buildApprovedPlanItem(candidate: Candidate): ApprovedPlanItem;
+/**
+ * True when `query` matches at least one of `items`' matchKeys:
+ *  - by scenarioName slug (`name:<slug>`), or
+ *  - by testType + path (`ep:<testType>:*:<path>`), method-exact when
+ *    `query.method` is given, method-agnostic (any method) otherwise — the
+ *    contract tool's `method: ""` ("test all methods") case.
+ */
+export declare function matchesApprovedItem(items: ApprovedPlanItem[], query: PlanMatchQuery): boolean;
+/**
+ * True when `query` is admissible under the approved plan: it matches a
+ * GENERATE item, or it matches an ADDITIONAL item while the plan has at least
+ * one GENERATE item. ADDITIONAL is strictly a backfill pool for failed
+ * GENERATE items — on a zero-budget plan (`generate: []`, e.g. maxGenerate=0
+ * for a config-only PR) there is nothing to backfill, so ADDITIONAL must not
+ * admit generation. Shared by planGuard and submitReportTool so the gate and
+ * the report cross-check can never disagree on admissibility.
+ */
+export declare function matchesApprovedPlan(plan: {
+    generate: ApprovedPlanItem[];
+    additional: ApprovedPlanItem[];
+}, query: PlanMatchQuery): boolean;

package/build/utils/planMatchKeys.js

@@ -0,0 +1,125 @@
+/**
+ * SKYR-3879 Path B — shared match-key computation for the register-plan
+ * checkpoint. `computeMatchKeys` runs ONCE, at approval time (inside
+ * registerTestPlanTool / the analyze_changes pre-seed), so the two
+ * consumers — planGuard (generation-tool hard gate) and submitReportTool
+ * (report cross-check) — only ever do a Set/array membership check, never
+ * re-derive normalization logic against a live candidate.
+ *
+ * Two kinds of key:
+ *  - `name:<slug>`               — normalized scenarioName, for multi-step
+ *    candidates (batch-scenario / integration) where the agent's own name is
+ *    the natural join key.
+ *  - `ep:<testType>:<METHOD>:<path>` — one per step, for single-endpoint
+ *    matching (contract tests, or a fallback when names drift between
+ *    register and generate).
+ */
+/** Lowercase, collapse non-alphanumeric runs to '-', trim leading/trailing '-'. */
+export function slugifyName(name) {
+    return (name ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Normalize a path so param segments collapse: numeric ids, `{brace}` params,
+ * `:colon` params, and long hex/uuid segments all become `:p`. Mirrors
+ * discriminators.ts's normalizePath (duplicated here rather than imported —
+ * that function verifies discriminator claims against a diff, a different
+ * concern from plan matching, and keeping them independent avoids coupling
+ * this module's stability to phase 1's internal helper).
+ */
+export function normalizeMatchPath(rawPath) {
+    const pathPart = (rawPath ?? "").split("?")[0];
+    return pathPart
+        .split("/")
+        .map((seg) => {
+        if (seg === "")
+            return seg;
+        if (/^\{.*\}$/.test(seg))
+            return ":p";
+        if (/^:.+/.test(seg))
+            return ":p";
+        if (/^\d+$/.test(seg))
+            return ":p";
+        if (/^[0-9a-fA-F-]{16,}$/.test(seg))
+            return ":p";
+        return seg.toLowerCase();
+    })
+        .join("/");
+}
+function inferTestType(scenario) {
+    return (scenario.testType ?? (scenario.steps.length === 1 ? "contract" : "integration")).toLowerCase();
+}
+/** Name key (if a name exists) plus one endpoint key per step. */
+export function computeMatchKeys(scenario) {
+    const keys = [];
+    const slug = slugifyName(scenario.scenarioName);
+    if (slug)
+        keys.push(`name:${slug}`);
+    const testType = inferTestType(scenario);
+    for (const step of scenario.steps ?? []) {
+        if (!step?.method || !step?.path)
+            continue;
+        keys.push(`ep:${testType}:${step.method.toUpperCase()}:${normalizeMatchPath(step.path)}`);
+    }
+    return [...new Set(keys)];
+}
+/** Build the persisted plan item from a ranked Candidate. */
+export function buildApprovedPlanItem(candidate) {
+    return {
+        candidateId: candidate.candidateId,
+        scenarioName: candidate.scenario.scenarioName,
+        testType: inferTestType(candidate.scenario),
+        category: candidate.scenario.category,
+        source: candidate.source,
+        ...(candidate.verifiedDiscriminator ? { verifiedDiscriminator: candidate.verifiedDiscriminator } : {}),
+        matchKeys: computeMatchKeys(candidate.scenario),
+    };
+}
+/**
+ * True when `query` matches at least one of `items`' matchKeys:
+ *  - by scenarioName slug (`name:<slug>`), or
+ *  - by testType + path (`ep:<testType>:*:<path>`), method-exact when
+ *    `query.method` is given, method-agnostic (any method) otherwise — the
+ *    contract tool's `method: ""` ("test all methods") case.
+ */
+export function matchesApprovedItem(items, query) {
+    const nameSlug = query.scenarioName ? slugifyName(query.scenarioName) : "";
+    if (nameSlug) {
+        const nameKey = `name:${nameSlug}`;
+        if (items.some((item) => item.matchKeys.includes(nameKey)))
+            return true;
+    }
+    if (query.testType && query.path) {
+        const testType = query.testType.toLowerCase();
+        const normPath = normalizeMatchPath(query.path);
+        if (query.method) {
+            const epKey = `ep:${testType}:${query.method.toUpperCase()}:${normPath}`;
+            if (items.some((item) => item.matchKeys.includes(epKey)))
+                return true;
+        }
+        else {
+            const prefix = `ep:${testType}:`;
+            const suffix = `:${normPath}`;
+            if (items.some((item) => item.matchKeys.some((k) => k.startsWith(prefix) && k.endsWith(suffix)))) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * True when `query` is admissible under the approved plan: it matches a
+ * GENERATE item, or it matches an ADDITIONAL item while the plan has at least
+ * one GENERATE item. ADDITIONAL is strictly a backfill pool for failed
+ * GENERATE items — on a zero-budget plan (`generate: []`, e.g. maxGenerate=0
+ * for a config-only PR) there is nothing to backfill, so ADDITIONAL must not
+ * admit generation. Shared by planGuard and submitReportTool so the gate and
+ * the report cross-check can never disagree on admissibility.
+ */
+export function matchesApprovedPlan(plan, query) {
+    if (matchesApprovedItem(plan.generate, query))
+        return true;
+    return plan.generate.length > 0 && matchesApprovedItem(plan.additional, query);
+}

package/build/utils/pom-scope/import-expansion.d.ts

@@ -0,0 +1,5 @@
+/** One hop: for each selected file, resolve its relative import/require refs to files in the POM set. */
+export declare function expandImports(selected: string[], allPoms: string[]): Promise<Array<{
+    file: string;
+    referrer?: string;
+}>>;

package/build/utils/pom-scope/import-expansion.js

@@ -0,0 +1,32 @@
+import { readFile } from "fs/promises";
+import * as path from "path";
+const REF_RE = /(?:from\s+["']([^"']+)["']|require\(\s*["']([^"']+)["']\s*\))/g;
+/** One hop: for each selected file, resolve its relative import/require refs to files in the POM set. */
+export async function expandImports(selected, allPoms) {
+    const pomSet = new Set(allPoms);
+    const out = selected.map((file) => ({ file }));
+    const seen = new Set(selected);
+    for (const file of selected) {
+        let content;
+        try {
+            content = await readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const m of content.matchAll(REF_RE)) {
+            const ref = m[1] ?? m[2];
+            if (!ref || !ref.startsWith("."))
+                continue;
+            const base = path.resolve(path.dirname(file), ref);
+            for (const cand of [base, `${base}.js`, `${base}.ts`, base.replace(/\.js$/, ".ts")]) {
+                if (pomSet.has(cand) && !seen.has(cand)) {
+                    seen.add(cand);
+                    out.push({ file: cand, referrer: file });
+                    break;
+                }
+            }
+        }
+    }
+    return out;
+}