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

package/build/index.js

@@ -24,7 +24,7 @@ import { registerCodeReuseTool } from "./tools/code-refactor/codeReuseTool.js";
 import { registerEnhanceAssertionsTool } from "./tools/code-refactor/enhanceAssertionsTool.js";
 import { registerBatchScenarioTestTool } from "./tools/generate-tests/generateBatchScenarioRestTool.js";
 import { registerMockTool } from "./tools/generate-tests/generateMockRestTool.js";
-import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerActionsTool, } from "./tools/test-management/index.js";
+import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerActionsTool, registerRegisterTestPlanTool, } from "./tools/test-management/index.js";
 import { registerTestbotPrompt } from "./prompts/testbot/testbot-prompts.js";
 import { registerSutSetupResource } from "./resources/sutSetupResource.js";
 import { registerTestbotResource } from "./resources/testbotResource.js";
@@ -151,6 +151,7 @@ registerProgressResource(server);
 registerAnalyzeChangesTool(server);
 registerAnalyzeTestHealthTool(server);
 registerActionsTool(server);
+registerRegisterTestPlanTool(server);
 // Register workspace management tools
 registerInitScanWorkspaceTool(server);
 registerInitializeWorkspaceTool(server);

package/build/prompts/code-reuse.d.ts

@@ -1 +1,7 @@
-export declare function getCodeReusePrompt(testFile: string, language: string, framework?: string): string;
+import type { ScopedPom } from "../utils/pom-scope/index.js";
+export declare function isPomAwareTarget(language: string, framework?: string): boolean;
+export declare function getCodeReusePrompt(testFile: string, language: string, framework?: string, scopedPoms?: {
+    tier1: ScopedPom[];
+    tier2: ScopedPom[];
+    scannedNoOverlap?: boolean;
+}): string;

package/build/prompts/code-reuse.js

@@ -18,11 +18,14 @@ const LANGUAGE_MAP = {
         fileName: "skyrampUtils.ts",
     },
 };
-export function getCodeReusePrompt(testFile, language, framework) {
-    const isTypescriptPlaywright = language.toLowerCase() === "typescript" &&
-        framework?.toLowerCase() === "playwright";
-    if (isTypescriptPlaywright) {
-        return getPomAwareCodeReusePrompt(testFile);
+export function isPomAwareTarget(language, framework) {
+    const lang = language.toLowerCase();
+    return (lang === "typescript" || lang === "javascript") && framework?.toLowerCase() === "playwright";
+}
+export function getCodeReusePrompt(testFile, language, framework, scopedPoms) {
+    const lang = language.toLowerCase();
+    if (isPomAwareTarget(lang, framework)) {
+        return getPomAwareCodeReusePrompt(testFile, lang, scopedPoms);
     }
     const ext = LANGUAGE_MAP[language].extension || "py";
     const fileName = LANGUAGE_MAP[language].fileName || "SkyrampUtils.py";

package/build/prompts/code-reuse.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/prompts/code-reuse.test.js

@@ -0,0 +1,62 @@
+import { getCodeReusePrompt } from "./code-reuse.js";
+const POM = "POM-AWARE CODE REUSE"; // unique to the POM branch
+const pom = (file, score = 2, rareHits = 2, matchedTokens = ["a-b-c"]) => ({ file, score, rareHits, matchedTokens });
+describe("getCodeReusePrompt routing", () => {
+    it("routes javascript + playwright to the POM-aware prompt", () => {
+        expect(getCodeReusePrompt("t.spec.js", "javascript", "playwright")).toContain(POM);
+    });
+    it("still routes typescript + playwright to the POM-aware prompt", () => {
+        expect(getCodeReusePrompt("t.spec.ts", "typescript", "playwright")).toContain(POM);
+    });
+    it("routes javascript + non-playwright to SkyrampUtils", () => {
+        expect(getCodeReusePrompt("t.spec.js", "javascript", "jest")).not.toContain(POM);
+    });
+    it("routes python to SkyrampUtils (no regression)", () => {
+        expect(getCodeReusePrompt("t.py", "python", "pytest")).not.toContain(POM);
+    });
+    it("does not trigger POM path when framework is undefined", () => {
+        expect(getCodeReusePrompt("t.spec.ts", "typescript")).not.toContain(POM);
+    });
+});
+describe("getCodeReusePrompt scoped POM list", () => {
+    it("emits the pre-detected two-tier STEP 1 when scoped files are supplied", () => {
+        const p = getCodeReusePrompt("t.spec.js", "javascript", "playwright", { tier1: [pom("/repo/pages/loginPage.js")], tier2: [pom("/repo/pages/homePage.js", 0.3, 1, ["menu-link-/alerts-item"])] });
+        expect(p).toContain("ALREADY DETECTED");
+        expect(p).toContain("/repo/pages/loginPage.js");
+        expect(p).toContain("catalog fully");
+        expect(p).toContain("/repo/pages/homePage.js");
+        expect(p).toContain("signature level");
+        expect(p).toContain("menu-link-/alerts-item"); // matched tokens surface for tier-2 mapping evidence
+        expect(p).not.toContain("DETECT POM CLASSES");
+    });
+    it("emits the glob STEP 1 when no scoped files are supplied", () => {
+        expect(getCodeReusePrompt("t.spec.js", "javascript", "playwright")).toContain("DETECT POM CLASSES");
+    });
+    it("emits the glob STEP 1 when both tiers are empty (fallback)", () => {
+        expect(getCodeReusePrompt("t.spec.js", "javascript", "playwright", { tier1: [], tier2: [] }))
+            .toContain("DETECT POM CLASSES");
+    });
+    it("returns the short skip response on a clean scan with zero overlap", () => {
+        const p = getCodeReusePrompt("t.spec.js", "javascript", "playwright", {
+            tier1: [], tier2: [], scannedNoOverlap: true,
+        });
+        expect(p).toContain("No reusable POM layer detected");
+        expect(p).toContain("verify: true"); // escape hatch mandates re-verify
+        expect(p).not.toContain("COMPLIANCE RULES"); // NOT the full workflow prompt
+        expect(p.length).toBeLessThan(2000);
+    });
+    it("keeps the full agent-driven fallback when scoping was inconclusive", () => {
+        // no scopedPoms argument = scan didn't run or didn't conclude
+        const p = getCodeReusePrompt("t.spec.js", "javascript", "playwright");
+        expect(p).toContain("COMPLIANCE RULES");
+        expect(p).not.toContain("No reusable POM layer detected");
+    });
+    it("leaves the SkyrampUtils path untouched for non-Playwright languages", () => {
+        const p = getCodeReusePrompt("t.py", "python", undefined, { tier1: [], tier2: [], scannedNoOverlap: true });
+        expect(p).not.toContain("No reusable POM layer detected");
+        expect(p).toContain("SkyrampUtils");
+    });
+    it("does not annotate when scoping simply was not attempted", () => {
+        expect(getCodeReusePrompt("t.spec.js", "javascript", "playwright")).not.toContain("No reusable POM layer detected");
+    });
+});

package/build/prompts/pom-aware-code-reuse.d.ts

@@ -1 +1,6 @@
-export declare function getPomAwareCodeReusePrompt(testFile: string): string;
+import type { ScopedPom } from "../utils/pom-scope/index.js";
+export declare function getPomAwareCodeReusePrompt(testFile: string, language?: string, scopedPoms?: {
+    tier1: ScopedPom[];
+    tier2: ScopedPom[];
+    scannedNoOverlap?: boolean;
+}): string;

package/build/prompts/pom-aware-code-reuse.js

@@ -1,8 +1,52 @@
 import { generateSkyrampHeader, SKYRAMP_UTILS_HEADER } from "../utils/utils.js";
-const TS_UTILS_FILE = "skyrampUtils.ts";
-const TS_CODEGEN_MARKER = "// Generated by Skyramp v";
-export function getPomAwareCodeReusePrompt(testFile) {
-    return `# POM-AWARE CODE REUSE — TYPESCRIPT/PLAYWRIGHT
+export function getPomAwareCodeReusePrompt(testFile, language = "typescript", scopedPoms) {
+    const isJs = language.toLowerCase() === "javascript";
+    const ext = isJs ? "js" : "ts";
+    const utilsFile = isJs ? "skyrampUtils.js" : "skyrampUtils.ts";
+    const codegenMarker = "// Generated by Skyramp v";
+    const headerLang = isJs ? "javascript" : "typescript";
+    const scopedActive = scopedPoms && scopedPoms.tier1.length + scopedPoms.tier2.length > 0;
+    if (!scopedActive && scopedPoms?.scannedNoOverlap) {
+        return `No reusable POM layer detected: a repo-wide scan found zero overlap between this test's selectors and any non-test source file. Code reuse is skipped — continue with the generated test as-is.
+
+Caveat: detection matches literal selector tokens; a POM layer built on computed/dynamic selectors could be missed. If you have concrete evidence of one (e.g. a pageobjects/ directory with classes covering this flow), you may refactor ${testFile} manually following the repo's existing spec conventions — and if you do, you MUST call this tool again with \`verify: true\` and follow its report before finishing. Do NOT call skyramp_modularization.`;
+    }
+    const renderPom = (p) => `- \`${p.file}\`${p.matchedTokens.length > 0 ? ` — matched: ${p.matchedTokens.map((t) => `\`${t}\``).join(", ")}` : ""}`;
+    const step1Section = scopedActive
+        ? `## STEP 1: POM FILES — ALREADY DETECTED
+
+POM detection has been performed programmatically from this test's selectors.
+
+**Tier 1 — high relevance (catalog fully — every property and method):**
+${scopedPoms.tier1.map(renderPom).join("\n") || "(none)"}
+
+**Tier 2 — supporting/possible (catalog at signature level ONLY — class name, method names, and the matched selectors shown; deepen a file only if STEP 2b maps an action to it):**
+${scopedPoms.tier2.map(renderPom).join("\n") || "(none)"}
+
+**Caution on matched tokens:** the tokens above are raw substring evidence from the detector, not a guarantee of the file's full frame id — a matched token like \`#application-new-applied\` can hide that the file's ACTUAL frame is a prefix-sibling such as \`#application-new-applied-type\`. When you catalog each file in STEP 2, record its ACTUAL full selector/frame id from source rather than the bare matched token.
+
+Do NOT glob or scan for other POM files. Proceed to STEP 2 and catalog exactly these files (plus any file they import or extend that you find essential while reading them).
+
+**Catalog-completeness guard for STEP 2a:** when checking for an existing \`skyramp-pom-catalog.md\`, it is only valid for THIS run if it already contains an entry for EVERY file listed above. If any listed file is missing from the catalog, do NOT reuse it wholesale — keep its existing entries and generate + append entries for the missing listed files (then use the updated catalog).
+
+**Decision:** continue to STEP 2.`
+        : `## STEP 1: DETECT POM CLASSES IN THE PROJECT
+
+Use the Glob tool to search for POM files starting from the directory containing \`${testFile}\`:
+- Pattern 1: \`**/pageobjects/**/*.{ts,js}\`
+- Pattern 2: \`**/page-objects/**/*.{ts,js}\`
+- Pattern 3: \`**/pages/**/*.{ts,js}\`
+- Pattern 4: \`**/*.page.{ts,js}\`
+- Pattern 5: \`**/*Page.{ts,js}\`
+- Pattern 6: \`**/pom/**/*.{ts,js}\`
+
+Exclude test/spec files by **basename only** — never match on the directory path. POM layers commonly live under a \`tests/\` directory (e.g. \`tests/ui-testing/pages/\`), and path-matching would wrongly drop every POM. A file is excluded only if its **basename** ends in \`.spec.ts\`, \`.spec.js\`, \`.test.ts\`, or \`.test.js\`. Do NOT exclude on the bare substrings \`test\` or \`spec\`: they falsely match legitimate POMs (e.g. \`searchJobInspectorPage.js\` contains "spec") and directory names (\`tests/\`).
+Also exclude \`node_modules\`.
+
+**Decision:**
+- Zero matches found → **SKIP TO STEP 6 (FALLBACK)**
+- One or more matches found → continue to STEP 2`;
+    return `# POM-AWARE CODE REUSE — TYPESCRIPT/JAVASCRIPT + PLAYWRIGHT
 
 ## COMPLIANCE RULES — READ THIS FIRST, APPLY TO EVERY STEP
 
@@ -27,22 +71,7 @@ This is NOT the same as SkyrampUtils consolidation. Do NOT create a SkyrampUtils
 
 ---
 
-## STEP 1: DETECT POM CLASSES IN THE PROJECT
-
-Use the Glob tool to search for POM files starting from the directory containing \`${testFile}\`:
-- Pattern 1: \`**/pageobjects/**/*.ts\`
-- Pattern 2: \`**/page-objects/**/*.ts\`
-- Pattern 3: \`**/pages/**/*.ts\`
-- Pattern 4: \`**/*.page.ts\`
-- Pattern 5: \`**/*Page.ts\`
-- Pattern 6: \`**/pom/**/*.ts\`
-
-Exclude any file with \`test\`, \`spec\`, \`.test.\`, or \`.spec.\` in its name.
-Also exclude \`node_modules\`.
-
-**Decision:**
-- Zero matches found → **SKIP TO STEP 6 (FALLBACK)**
-- One or more matches found → continue to STEP 2
+${step1Section}
 
 ---
 
@@ -50,7 +79,7 @@ Also exclude \`node_modules\`.
 
 **Step 2a: Check for existing catalog (MANDATORY FIRST STEP)**
 
-Check if \`skyramp-pom-catalog.md\` exists in the same directory as \`tsconfig.json\`:
+Check if \`skyramp-pom-catalog.md\` exists in the same directory as \`tsconfig.json\` (or \`jsconfig.json\`, or the test root if neither exists):
 - **If it exists:** Read it and verify it starts with \`<!-- skyramp-pom-catalog: auto-generated -->\`
   - Valid → Output: *"Using existing POM catalog from /path/to/skyramp-pom-catalog.md"* and **skip to STEP 2b**
   - Invalid → Continue to full catalog generation below
@@ -62,12 +91,17 @@ Check if \`skyramp-pom-catalog.md\` exists in the same directory as \`tsconfig.j
 
 Before writing a single line of refactored code, do the following:
 
-can 1. **Read existing refactored tests** — Find any already-refactored test files in the repository and note their established conventions: how imports are grouped, what comment style sections use, and how \`waitForTimeout\`, \`waitForResponse\`, and dynamic locators are handled. Where existing tests provide a pattern, follow it exactly.
+1. **Extract conventions from ONE existing test** — Open one existing test spec (prefer one that imports the POM layer). Extract ONLY: (a) the instantiation convention (central PageManager, e.g. \`const pm = new PageManager(page)\`, vs direct \`new X(page)\`), (b) import style and path aliases, (c) the section-comment style. Ignore everything else in that file — do NOT mimic its test logic, waits, or assertions.
 
 2. **Read tsconfig.json / jsconfig.json** — Capture path alias conventions (e.g., \`@pageobjects/*\`, \`@common-function/*\`). All imports in the refactored test must use these aliases exactly.
 
-3. **Read every POM file found in STEP 1** — For each file, document:
+3. **Read the POM files from STEP 1** — Depth depends on how STEP 1 listed them: files marked **Tier 2 (signature level)** get a REDUCED entry — class name, method names (signatures only), and the matched selectors STEP 1 showed; do NOT read their full bodies or record per-method timing/network details unless STEP 2b later maps an action to that file (then deepen just that file). **Tier 1 files — and ALL files when STEP 1 did not use tiers (agent-detected mode)** — get the FULL treatment below. For each full-depth file, document:
    - Class name, import path (using tsconfig aliases), and what page/component it represents
+   **Locator styles to capture — a POM class may expose selectors in ANY of these forms; catalog all of them, recording the selector string passed to \`.locator()\` / \`getByRole\` / \`getByTestId\` etc.:**
+   - Constructor-assigned: \`this.loginButton = page.locator('[data-test="login-sign-in"]')\`
+   - Getter accessors: \`get firstRow() { return this.page.locator('[data-test^="row-"]').first(); }\`
+   - Object-literal maps: \`this.locators = { menuItem: '[data-test="menu-item"]', ... }\` (each key is a named selector)
+   - Inline in methods: a \`.locator(...)\` used directly inside an action method (still a reusable target, named by its method)
    - Iframe selector used in the constructor (e.g. \`page.frameLocator('iframe#asset-list')\`), or "top-level page" if no iframe
    - Every property (locator): name and its exact selector string from the constructor assignment
    - Every method: name, parameters, what action it performs
@@ -77,7 +111,7 @@ can 1. **Read existing refactored tests** — Find any already-refactored test f
      - Whether the method wraps a multi-step sequence using sub-properties or components (e.g. \`searchAssetsByCondition\` internally calls \`searchConditionArea.expandWhenClosed()\`, \`clearBtn.click()\`, \`selectItemName()\`, \`valueKeyword.fill()\`, \`searchBtn.click()\`) — flag these as **wrapping methods**
    - Flag methods as **timing-aware**, **network-aware**, or **wrapping** as appropriate — all three are high-value substitution targets
 
-4. **Write the POM catalog — MANDATORY** — Write the complete catalog to \`skyramp-pom-catalog.md\` in the same directory as \`tsconfig.json\`. This gives you a clean structured reference for STEP 2b and leaves a record for debugging.
+4. **Write the POM catalog — MANDATORY** — Write the complete catalog to \`skyramp-pom-catalog.md\` in the same directory as \`tsconfig.json\` (or \`jsconfig.json\`, or the test root if neither exists). This gives you a clean structured reference for STEP 2b and leaves a record for debugging.
 
 **BLOCKING: Do not proceed to STEP 2b until you have written this file and confirmed the path in a single output line:**
 *"POM catalog written to /path/to/skyramp-pom-catalog.md"*
@@ -98,13 +132,15 @@ Use this exact format for the file:
   - \`methodName(param1, param2)\` — description; ⏱ timing-aware: waitForTimeout(Xms) + sleep(Ys) | 🌐 network-aware: waitForResponse('**/pattern**') | (omit tags if neither)
 \`\`\`
 
+**Tier-2 entries in the catalog:** for files cataloged at signature level, the entry contains the class name, the import path, a \`- **Methods:**\` list of names/signatures only, and the matched selectors from STEP 1 under \`- **Properties:**\`. Mark such entries with \`<!-- depth: signature -->\` on the line after the class heading so a later run knows the entry is shallow.
+
 ---
 
 ## STEP 2b: BUILD AND OUTPUT A MAPPING TABLE
 
 **This step is MANDATORY. Do not write any code until it is complete.**
 
-For every raw locator and action sequence in \`${testFile}\`, find the best POM match and record it in a table. Output the complete table to chat before proceeding to STEP 3.
+For every raw locator and action sequence in \`${testFile}\`, find the best POM match; record the PREFERRED and HIGH matches in a table (all others simply remain inline). Output the complete table to chat before proceeding to STEP 3.
 
 ### Matching criteria
 
@@ -138,6 +174,8 @@ Before considering any POM match, verify the iframe context matches:
 
 ### Mapping table format
 
+List ONLY rows with PREFERRED or HIGH confidence — these are the substitutions you will make. Do NOT enumerate LOW/UNCERTAIN or UNMAPPED locators in the table; every locator not in the table remains inline as-is.
+
 Output the table in this format:
 
 \`\`\`
@@ -145,16 +183,16 @@ Output the table in this format:
 |---|---|---|---|---|
 | goto + fill email/password + click login | LoginPage | login(email, password) | method is timing-aware (waitForTimeout+sleep) covering login sequence | PREFERRED |
 | frameLocator('iframe#asset-list').locator('button:has-text("資産登録")') | AssetListPage | assetEntryBtn | iframe.locator('button:has-text("資産登録")') | HIGH |
-| page.locator('input[name="email"]').fill(...) | LoginPage | emailInput | getByPlaceholder('メールアドレス（半角）') | LOW |
-| frameLocator('iframe#wf-input').locator('input[name="changeQty"]') | — | — | No match | UNMAPPED |
 \`\`\`
 
+All other locators remain inline.
+
 ### Rules after completing the table
 
 - **PREFERRED entries MUST be substituted** — use the POM method and drop the raw test's explicit waits/correlations that fall inside the method's scope
 - **HIGH entries MUST be substituted** — use the POM method or property; do NOT write an inline locator
 - **Always prefer the highest level of abstraction available** — if a wrapping method exists that covers a multi-step sequence, use it instead of calling the individual sub-properties directly. Example: use \`searchAssetsByCondition("資産名", assetName)\` not \`searchConditionArea.expandWhenClosed()\` + \`getConditionRow(1)\` + \`selectItemName()\` etc. Use \`bulkDelete()\` not \`bulkDeleteBtn.click()\` + \`confirmDeleteDialog\` + \`noticeDialog\` inline.
-- **Do NOT upgrade LOW or UNCERTAIN** because the substitution seems reasonable
+- **Do NOT upgrade LOW or UNCERTAIN to PREFERRED/HIGH** because the substitution seems reasonable — leave them inline and out of the table
 - **Conservative default**: an incorrect substitution that breaks the test is worse than leaving something inline — when in doubt, leave it inline
 - If the table has ZERO PREFERRED or HIGH entries → **SKIP TO STEP 6 (FALLBACK)**
 - If AT LEAST ONE PREFERRED or HIGH entry exists → continue to STEP 3
@@ -264,6 +302,8 @@ When a module operates inside an iframe, determine the correct frame handle by r
 
 **Never create standalone \`frameLocator()\` references in the test body.** If an action is UNMAPPED and must stay inline, access the frame through the POM's own \`iframe\` property (e.g. \`assetSelectPage.iframe.locator(...)\`, \`inputPage.iframe.getByRole(...)\`). Do not create a separate \`const inputPageFrame = skyrampPage.frameLocator('#application-new-applied')\` — this duplicates the frame reference that already exists in the POM.
 
+**Exception — orphan frame:** if NO cataloged POM class scopes to the frame a raw action uses, there is no POM \`iframe\` property to borrow. In that case a standalone inline \`frameLocator(...)\` for that action is CORRECT — keep it, and mark it with a brief comment (e.g. \`// no POM owns this frame — kept inline\`). Do not force-fit a method from a different-frame class (the gate above still forbids that) and do not invent a POM to cover it.
+
 ### 3h. Dynamic Locators — Prefer Positional Module Methods
 
 Before keeping a dynamic locator inline, check whether a module method exists that targets the same element by position rather than by value. If one exists, use it with the appropriate position (typically \`0\` for the first result) and add a comment noting it replaces the original dynamic locator. If no positional equivalent exists, keep the raw dynamic locator inline as-is.
@@ -278,6 +318,12 @@ If the existing POM files have an established pattern for checkbox interactions,
 
 Screenshot assertions (\`toHaveScreenshot\`) must stay in their **exact original position** relative to surrounding actions from the raw test. Note what actions appear immediately before and after the screenshot in the raw test, then place the screenshot at that same relative position in the refactored test. If a POM method would move the screenshot, inline that method's steps around it with a comment: \`// POM method not used — screenshot position must be preserved\`
 
+### 3k. Page Object Instantiation — Follow the Repo's Convention
+
+**Instantiation convention — follow the repo's existing pattern (read the existing specs to detect it):**
+- If the repo uses a central PageManager (e.g. \`const pm = new PageManager(page)\` then \`pm.loginPage.login()\`), the refactored test MUST use that accessor convention — do NOT instantiate page objects directly.
+- Otherwise, instantiate page objects directly, matching what the existing specs do.
+
 ---
 
 ## STEP 4: WRITE THE REFACTORED TEST
@@ -288,13 +334,11 @@ Using your catalog from STEP 2 and analysis from STEP 3, produce the refactored
 Before writing each line of refactored code, look up that action in your STEP 2b mapping table:
 - If it is marked **PREFERRED** → use the POM method and drop any raw waits/correlations inside its scope. This is the highest-value substitution.
 - If it is marked **HIGH** → you MUST use the POM method or property. Do NOT write an inline locator.
-- If it is marked **LOW / UNCERTAIN / UNMAPPED** → write it inline exactly as in the original test.
+- If it is NOT in the table (LOW / UNCERTAIN / UNMAPPED) → write it inline exactly as in the original test.
 
-Do not skip this lookup for any action. The mapping table is your source of truth — not the raw test's locators.
+A locator with a PREFERRED/HIGH mapping that is written inline anyway is a DEFECT — the customer reads that as a missed reuse.
 
-## STEP 4b: VERIFY AGAINST MAPPING TABLE
-
-Before proceeding to STEP 5, scan your refactored test output and for each HIGH entry in the mapping table confirm the corresponding POM call is present in the output. If any HIGH entry is missing its POM call and was written as inline code instead, go back and fix it before writing the file.
+Do not skip this lookup for any action. The mapping table is your source of truth — not the raw test's locators.
 
 **Section Comments:** Divide the test body into clearly labeled sections corresponding to the logical phases of the user journey. Use the comment style from the repository's existing tests. If none exists, use \`/*----- Section Name -----*/\`.
 
@@ -308,17 +352,19 @@ Before proceeding to STEP 5, scan your refactored test output and for each HIGH
 - Screenshot assertions (\`toHaveScreenshot\`): always keep inline; if mid-method sequence, inline that method's steps around it
 - Page readiness checks: use module methods such as \`pageToBeVisible()\` if they exist
 
-**IMPORTANT:** Do NOT create a \`skyrampUtils.ts\` or any SkyrampUtils file on this path. Do NOT call \`skyramp_modularization\` after completing POM-aware code reuse — POM refactoring replaces that step.
+**IMPORTANT:** Do NOT create a \`${utilsFile}\` or any SkyrampUtils file on this path. Do NOT call \`skyramp_modularization\` after completing POM-aware code reuse — POM refactoring replaces that step.
 
 ---
 
 ## STEP 5: WRITE THE OUTPUT
 
-Write the complete, runnable refactored test directly to \`${testFile}\`, overwriting it in place. The file must contain every line — never use placeholder comments like \`// ...continue\` or \`// ...existing code\`. If the test is long, write it in multiple passes until the file is complete. Confirm the file path written to in a single line once done.
+Write the complete, runnable refactored test directly to \`${testFile}\`, overwriting it in place. Before overwriting, save the current (pre-refactor) content to \`${testFile}.raw.bak\` — verification uses it to restore demoted substitutions. The file must contain every line — never use placeholder comments like \`// ...continue\` or \`// ...existing code\`. If the test is long, write it in multiple passes until the file is complete. Confirm the file path written to in a single line once done.
 
 Do not output a section breakdown, modularization summary, or any analysis to the chat. Perform all analysis internally.
 
-**Do NOT run the test. Do NOT call any other tools. Your work is complete once the file is written.**
+**A low substitution count can be the correct outcome.** When many actions stay inline because the POM layer simply does not model that flow (iframe-gate rejections, orphan frames, vocabulary drift from the cataloged classes), that is honest reuse, not a shortfall — do not pad the mapping table to inflate the count. In your one-line confirmation, state how many actions were substituted vs. kept inline and why in one clause (e.g. "6 substituted; 9 kept inline — POM layer does not model the apply-from-asset flow").
+
+**Do NOT run the test.** After writing the file, you MUST call \`skyramp_reuse_code\` once more with the same \`testFile\`/\`language\`/\`framework\` and \`verify: true\`, and follow its report: re-verify after every fix pass; a violation may be remapped at most once — if flagged again, demote it to the raw inline form; finish only when it reports PASSED (unverifiable notes are acceptable). Include \`verification: passed\` (or the unresolved count) in your final confirmation line.
 
 ---
 
@@ -360,7 +406,7 @@ Read ${testFile} and look for ALREADY DEFINED helper functions (not just repetit
 ## STEP 2: FIND EXISTING UTILS
 Use the Grep tool to search for files containing "${SKYRAMP_UTILS_HEADER}":
 - Pattern: "${SKYRAMP_UTILS_HEADER}"
-- Type: "ts"
+- Type: "${ext}"
 - Output mode: "files_with_matches"
 **CRITICAL: Only look for util files with header ${SKYRAMP_UTILS_HEADER}** - exclude test files (files with "test", "spec", ".test.", ".spec." in the name).
 Read the matching non-test files and check if any helpers can be reused in ${testFile}.
@@ -373,18 +419,18 @@ If helpers exist in util file that can be reused in ${testFile} without modifyin
 
 ## STEP 4: FIND LOCAL HELPERS IN OTHER SKYRAMP-GENERATED TEST FILES
 
-You are looking for sibling test files generated by Skyramp's codegen. They start with the comment line \`${TS_CODEGEN_MARKER}…\` (note: the version suffix is what distinguishes them from the SkyrampUtils header). The substring \`${SKYRAMP_UTILS_HEADER}\` is contained in that line, so:
+You are looking for sibling test files generated by Skyramp's codegen. They start with the comment line \`${codegenMarker}…\` (note: the version suffix is what distinguishes them from the SkyrampUtils header). The substring \`${SKYRAMP_UTILS_HEADER}\` is contained in that line, so:
 
 Use the Grep tool to search for other test files containing "${SKYRAMP_UTILS_HEADER}":
 - Pattern: "${SKYRAMP_UTILS_HEADER}"
-- Type: "ts"
+- Type: "${ext}"
 - Output mode: "files_with_matches"
 
 **CRITICAL: Exclude ${testFile} from the results** — only look at OTHER files, not the current file.
 
 The result will mix two kinds of files:
 - **Utils file(s)** — already handled by STEP 2/STEP 3.
-- **Other Skyramp-generated test files** — these are the targets of STEP 4 / 4b / 5. Identify them by the \`${TS_CODEGEN_MARKER}\` codegen marker on line 1 (NOT the bare utils header).
+- **Other Skyramp-generated test files** — these are the targets of STEP 4 / 4b / 5. Identify them by the \`${codegenMarker}\` codegen marker on line 1 (NOT the bare utils header).
 
 **STOP HERE IF NO OTHER SKYRAMP-GENERATED TEST FILES FOUND**
 **IF NO OTHER SKYRAMP-GENERATED TEST FILES ARE FOUND, SKIP TO STEP 6 - DO NOT CREATE ANY UTILS FILES.**
@@ -407,7 +453,7 @@ NOT A HELPER FUNCTION (do not extract):
 
 ## STEP 4b: PARAMETERIZE NEAR-DUPLICATE HELPERS ACROSS SKYRAMP-GENERATED TEST FILES
 
-**This step handles the cross-test case: ${testFile} AND another Skyramp-generated test file each define their own helper that does the SAME shape of work with only literal-value differences. These should become ONE parameterized helper in \`${TS_UTILS_FILE}\`.**
+**This step handles the cross-test case: ${testFile} AND another Skyramp-generated test file each define their own helper that does the SAME shape of work with only literal-value differences. These should become ONE parameterized helper in \`${utilsFile}\`.**
 
 ### Definition: "near-duplicate" helpers
 
@@ -478,9 +524,9 @@ For each helper defined locally in ${testFile}:
    - **Body**: the common primitive sequence with the differing literals replaced by parameters.
    - **Forbidden**: do NOT add if/else, ternaries, defaults, or any logic to bridge the differences. If a single body can't cover both call sites without new logic, they are NOT near-duplicates — leave them alone.
 4. **If multiple matches** → process each pair independently. Merge every pair that clearly meets all three near-duplicate criteria. Skip any pair you're uncertain about — a missed merge is recoverable, a wrong merge breaks both tests.
-5. **Write** the merged helper into \`${TS_UTILS_FILE}\` (create the file with the standard header if it doesn't exist; same header as STEP 5 below).
+5. **Write** the merged helper into \`${utilsFile}\` (create the file with the standard header if it doesn't exist; same header as STEP 5 below).
 6. **Delete** both original helpers from their test files.
-7. **Import** the merged helper from \`${TS_UTILS_FILE}\` into both test files.
+7. **Import** the merged helper from \`${utilsFile}\` into both test files.
 8. **Replace** the two original call sites with calls to the merged helper, passing the values that were originally hardcoded or argument-passed in each test.
 
 ### Hard rules
@@ -488,7 +534,7 @@ For each helper defined locally in ${testFile}:
 - **Conservative bias**: a wrong merge breaks both tests; a missed merge leaves a duplicate. When in doubt, do NOT merge.
 - **No "cleanup"**: the merged body must mirror the original primitive sequence — same waits, same correlation patterns, same order. This is not refactoring.
 - **Preserve typing style**: if originals used \`page: any\` (or untyped \`page\`), keep that convention.
-- **Don't merge with helpers already in \`${TS_UTILS_FILE}\`**: those are STEP 3's territory. STEP 4b is strictly cross-test merge between sibling Skyramp-generated test files.
+- **Don't merge with helpers already in \`${utilsFile}\`**: those are STEP 3's territory. STEP 4b is strictly cross-test merge between sibling Skyramp-generated test files.
 
 ---
 
@@ -505,15 +551,15 @@ For each helper defined locally in ${testFile}:
 **IF ANY CONDITION IS NOT MET, SKIP TO STEP 6 - DO NOT CREATE ANY UTILS FILES.**
 
 **CRITICAL:** For helpers found in STEP 4:
-1. **CREATE** \`${TS_UTILS_FILE}\` file if it doesn't exist with the following header:
+1. **CREATE** \`${utilsFile}\` file if it doesn't exist with the following header:
    \`\`\`ts
-   ${generateSkyrampHeader("typescript")}
+   ${generateSkyrampHeader(headerLang)}
    \`\`\`
-**CRITICAL: IF \`${TS_UTILS_FILE}\` is already big, create a new file with a different name and add the header to the new file.**
-2. **COPY** those local helper functions from original test source files to \`${TS_UTILS_FILE}\` without modifying them
+**CRITICAL: IF \`${utilsFile}\` is already big, create a new file with a different name and add the header to the new file.**
+2. **COPY** those local helper functions from original test source files to \`${utilsFile}\` without modifying them
 3. **DELETE** those local helper functions from test source files (REMOVE THEM COMPLETELY) WITHOUT ANY OTHER CHANGES.
-4. **IMPORT** those local helper functions from \`${TS_UTILS_FILE}\` back into test source files WITHOUT MAKING ANY OTHER CHANGE.
-5. **IMPORT** those local helper functions from \`${TS_UTILS_FILE}\` into ${testFile}
+4. **IMPORT** those local helper functions from \`${utilsFile}\` back into test source files WITHOUT MAKING ANY OTHER CHANGE.
+5. **IMPORT** those local helper functions from \`${utilsFile}\` into ${testFile}
 6. **REPLACE** duplicate code in ${testFile} with calls to imported helper functions WITHOUT MAKING ANY OTHER CHANGE.
 
 **CRITICAL: DO NOT CREATE UNNECESSARY HELPER FUNCTIONS**
@@ -525,14 +571,14 @@ For each helper defined locally in ${testFile}:
 3. **VERIFY** that helper functions are NO LONGER in original test files
 4. **VERIFY** that the original test files only have import statements and no duplicate code
 5. **VERIFY** that both original and new test files import from utils and use the helper functions
-5a. **VERIFY STEP 4b OUTCOMES** — for every near-duplicate pair you merged in STEP 4b: the merged helper exists in \`${TS_UTILS_FILE}\` exactly once; BOTH original helpers are deleted from their respective test files; BOTH test files import the merged helper from \`${TS_UTILS_FILE}\`; BOTH original call sites are replaced with calls to the merged helper. If any of these is false, fix it before finishing.
+5a. **VERIFY STEP 4b OUTCOMES** — for every near-duplicate pair you merged in STEP 4b: the merged helper exists in \`${utilsFile}\` exactly once; BOTH original helpers are deleted from their respective test files; BOTH test files import the merged helper from \`${utilsFile}\`; BOTH original call sites are replaced with calls to the merged helper. If any of these is false, fix it before finishing.
 6. **VERIFY** that no unnecessary helper functions were created
 7. **VERIFY** that all helper functions in utils are actually imported and used in the test files
 8. **REMOVE** any helper functions that are not being used after refactoring
 9. **NEVER** refactor, reorganize, or restructure existing source test files beyond moving helpers
 10. **Do NOT run the test** — your work is complete once the file is written
 
-**Do NOT call skyramp_modularization.** Code reuse is complete. The test file has been refactored in place — no further tools should be called.
+**Do NOT call skyramp_modularization.** Code reuse is complete. The test file has been refactored in place — no further tools should be called on this FALLBACK path. (If you took the POM-aware path instead, STEP 5's verification requirement still applies.)
 
 SUMMARIZE THE CODE REUSE PROCESS AND THE RESULTS.
 `;

package/build/prompts/pom-aware-code-reuse.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/prompts/pom-aware-code-reuse.test.js

@@ -0,0 +1,11 @@
+import { getPomAwareCodeReusePrompt } from "./pom-aware-code-reuse.js";
+describe("getPomAwareCodeReusePrompt language derivation", () => {
+    it("uses .ts utils filename for typescript (default)", () => {
+        expect(getPomAwareCodeReusePrompt("t.spec.ts")).toContain("skyrampUtils.ts");
+    });
+    it("uses .js utils filename for javascript", () => {
+        const p = getPomAwareCodeReusePrompt("t.spec.js", "javascript");
+        expect(p).toContain("skyrampUtils.js");
+        expect(p).not.toContain("skyrampUtils.ts");
+    });
+});

package/build/prompts/test-recommendation/diffExecutionPlan.d.ts

@@ -1,5 +1,5 @@
 import { DraftedScenario } from "../../types/RepositoryAnalysis.js";
-import { PriorityTier } from "../../types/TestRecommendation.js";
+import { Novelty, PriorityTier } from "../../types/TestRecommendation.js";
 /** "0" — Code Review: correctness analysis */
 export declare const EXEC_STEP_CODE_REVIEW: string;
 /** "1" — External test coverage verification */
@@ -10,10 +10,12 @@ export declare const EXEC_STEP_ENRICH: string;
 export declare const EXEC_STEP_DIVERSITY: string;
 /** "4" — Execute merged plan */
 export declare const EXEC_STEP_EXECUTE: string;
+/** "5" — Register test plan (SKYR-3879 Path B checkpoint) */
+export declare const EXEC_STEP_REGISTER: string;
 export declare function buildExecutionPlan(scored: Array<{
     scenario: DraftedScenario;
     priority: PriorityTier;
-    novelty: string;
+    novelty: Novelty;
 }>, maxGen: number, topN: number, baseUrl: string, authHeaderValue: string, authSchemeSnippet: string, authTypeValue: string, seed: string, endpointCount: number, isUIOnlyPR: boolean, hasFrontendChanges?: boolean, hasTraces?: boolean, externalCoverage?: Set<string>, relevantExternalTestPaths?: string[], 
 /**
  * Whether the diff classified at least one new/modified/removed endpoint.

package/build/prompts/test-recommendation/diffExecutionPlan.js

@@ -1,3 +1,4 @@
+import { roundRobinByType } from "../../recommendation/diversity.js";
 import { AUTH_MIDDLEWARE_PATTERNS_STR } from "../../utils/workspaceAuth.js";
 import { resolveServiceDetailsRef } from "../../utils/utils.js";
 import { logger } from "../../utils/logger.js";
@@ -21,7 +22,7 @@ The highest-severity \`<bug_found>\` block from this code review triggers a mand
 }
 function _execCoverageBody(ctx) {
     return `${ctx.externalTestFilesList}For every GENERATE item below, check its endpoint path and test type against the Existing Tests list (further down in the prompt).
-- **\`[external]\` tests**: If the endpoint is already covered by an \`[external]\` test of the same type → skip the resource entirely (do NOT create or update), **except for \`bug_caught\` and attack-surface \`security_boundary\` items**. A protected item may be skipped only if the external test directly asserts the same flaw/bypass and would fail/pass based on that same bug; same endpoint/resource coverage alone is not enough. Backfill from ADDITIONAL using the priority order below:
+- **\`[external]\` tests**: If the endpoint is already covered by an \`[external]\` test of the same type **that exercises the behavior this PR changes** → skip the resource entirely (do NOT create or update). Resource-level overlap alone is NOT coverage: when the PR tightens or adds a constraint (e.g. a max-items/max-length/enum bound), an external test that never crosses the new bound does not cover it — generate the boundary test. This matters most for single-resource APIs (e.g. one CRD served by the kube-apiserver), where resource-level dedup would permanently block all generation. \`bug_caught\` and attack-surface \`security_boundary\` items get the strictest reading: they may be skipped only if the external test directly asserts the same flaw/bypass and would fail/pass based on that same bug. Backfill from ADDITIONAL using the priority order below:
   1. **BUG-CATCHING TESTS FIRST (CRITICAL)**: If source code analysis revealed a bug, logic error, or incorrect formula (e.g. discount math adding instead of subtracting, off-by-one errors, missing validation), CREATE A TEST THAT EXPOSES IT. The test SHOULD FAIL — that's the point. Document the bug. Example: if discount formula is wrong, test with discount=20% and assert correct math. If no bug found, skip to #2.
   2. **PR-endpoint edge cases**: Look for integration test candidates covering error paths, boundary values, or alternative scenarios for the SAME endpoints changed in the PR diff. If no suitable candidate exists in ADDITIONAL, derive one from your source-code enrichment findings.
   3. **Same-resource other scenarios**: Other HTTP methods or flows on the same resource group touched by the PR.
@@ -94,6 +95,11 @@ For each pair of GENERATE items, ask: same HTTP method + path + step sequence +
 
 Same step sequence with only payload differences (e.g. 10% vs 5% discount both returning 200) = same code path = duplicate. Different scenario names do not make duplicate tests distinct.`;
 }
+function _execRegisterBody(_ctx) {
+    return `Register your complete candidate list — every test you would generate OR recommend — via \`skyramp_register_test_plan\` (\`stateFile\` required). Include a discriminator claim (\`discriminator\` field — valid kinds and anchor rules are in the tool schema) for candidates probing the changed logic identified in Step ${EXEC_STEP_CODE_REVIEW}/Step ${EXEC_STEP_ENRICH}.
+
+The returned GENERATE list is mandatory and final — generation tools reject unregistered scenarios. If the tool demotes a discriminator claim (returned in \`demotions\` with a reason), either strengthen the claim — a step that actually exercises the declared \`kind\`, or a verbatim anchor that occurs in the diff — or drop it; the candidate itself stays in the plan either way.`;
+}
 function _execExecuteBody(ctx) {
     return `Replace any scenario that pairs unrelated resources with one reflecting actual foreign-key relationships in the codebase.
 Use the field names and values from the \`<source_evidence>\` blocks you quoted in Step ${EXEC_STEP_ENRICH} to fill all tool call parameters. Prefer reusing Step ${EXEC_STEP_ENRICH} evidence when it already resolves a placeholder, but if a placeholder cannot be replaced with concrete values from files already read, you may read the specific schema, model, or handler file needed to resolve it. Assert response field values, not just status codes.
@@ -127,6 +133,7 @@ const _execPlan = new PromptPlan({ startFrom: 0 })
     .step("ENRICH", "Parameter Grounding & Priority Assignment", _execEnrichBody)
     .step("DIVERSITY", (ctx) => `Diversity check (using enriched knowledge from Step ${ctx.enrichStepLabel})`, _execDiversityBody)
     .step("EXECUTE", "Execute merged plan in rank order", _execExecuteBody)
+    .step("REGISTER", "Register your test plan", _execRegisterBody)
     .done();
 // ── Exported step label constants ─────────────────────────────────────────────
 /** "0" — Code Review: correctness analysis */
@@ -139,6 +146,8 @@ export const EXEC_STEP_ENRICH = _execPlan.labels.ENRICH; // "2"
 export const EXEC_STEP_DIVERSITY = _execPlan.labels.DIVERSITY; // "3"
 /** "4" — Execute merged plan */
 export const EXEC_STEP_EXECUTE = _execPlan.labels.EXECUTE; // "4"
+/** "5" — Register test plan (SKYR-3879 Path B checkpoint) */
+export const EXEC_STEP_REGISTER = _execPlan.labels.REGISTER; // "5"
 const SERVICE_REFS = resolveServiceDetailsRef();
 function prioritizeAttackSurfaceBundles(items) {
     const reordered = [];
@@ -154,69 +163,6 @@ function prioritizeAttackSurfaceBundles(items) {
     }
     return reordered;
 }
-/**
- * Select `count` items from a rank-ordered list, distributing GENERATE slots
- * EVENLY across the test types present, with spillover.
- *
- * Policy (kept identical to the multi-repo prose in testbot-prompts.ts's
- * "Cross-repo test generation" block — change both together):
- *  - Protected items first: CRITICAL-priority and attack-surface security_boundary
- *    scenarios always take a slot before round-robin (they must stay in GENERATE).
- *  - Bucket the rest by inferred test type (contract vs integration — the same
- *    inference used when rendering: `testType ?? (steps===1 ? contract : integration)`).
- *  - Round-robin one item per non-empty bucket per round, in the buckets' order of
- *    first appearance in the rank-ordered list (so the highest-ranked type wins
- *    round 1), preserving rank order within each bucket.
- *  - Spillover: an exhausted bucket is skipped on later rounds, so its freed slots
- *    go to the next type's next-highest item.
- *
- * Degenerate cases match the previous pure rank-order slice exactly: a single type
- * present, or `count >= items.length`, returns the same items in the same order —
- * so backend-only / single-type runs are unchanged (no regression).
- */
-function roundRobinByType(rankOrdered, count) {
-    if (count <= 0)
-        return [];
-    // Everything fits → no need to bucket; identical to the old slice.
-    if (count >= rankOrdered.length)
-        return rankOrdered.slice(0, count);
-    const inferType = (s) => s.testType ?? (s.steps.length === 1 ? "contract" : "integration");
-    // Protected items occupy GENERATE slots first, in rank order.
-    const selected = [];
-    const remaining = [];
-    for (const item of rankOrdered) {
-        if (selected.length < count &&
-            (item.priority === "CRITICAL" || isAttackSurfaceSecurityBoundary(item.scenario))) {
-            selected.push(item);
-        }
-        else {
-            remaining.push(item);
-        }
-    }
-    // Bucket the remainder by inferred type, preserving rank order and first-appearance
-    // bucket order.
-    const order = [];
-    const buckets = new Map();
-    for (const item of remaining) {
-        const t = inferType(item.scenario);
-        if (!buckets.has(t)) {
-            buckets.set(t, []);
-            order.push(t);
-        }
-        buckets.get(t).push(item);
-    }
-    // Round-robin one per non-empty bucket per round until full.
-    while (selected.length < count && order.some((t) => buckets.get(t).length > 0)) {
-        for (const t of order) {
-            if (selected.length >= count)
-                break;
-            const bucket = buckets.get(t);
-            if (bucket.length > 0)
-                selected.push(bucket.shift());
-        }
-    }
-    return selected;
-}
 export function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, authSchemeSnippet, authTypeValue, seed, endpointCount, isUIOnlyPR, hasFrontendChanges = false, hasTraces = false, externalCoverage = new Set(), relevantExternalTestPaths = [], 
 /**
  * Whether the diff classified at least one new/modified/removed endpoint.
@@ -473,7 +419,7 @@ ${buildScopeAssessmentSection(topN, maxGen, isUIOnlyPR, isUIOnlyPR ? 100 : hasFr
 
 ${_execPlan.render(_ctx)}
 
-### GENERATE (after completing Steps ${EXEC_STEP_CODE_REVIEW}–${EXEC_STEP_EXECUTE} above) — generate exactly these items in order; add variations to ADDITIONAL instead. If Step ${EXEC_STEP_COVERAGE} converts an item to UPDATE, backfill from ADDITIONAL (priority order in Step ${EXEC_STEP_COVERAGE})
+### GENERATE (after completing Steps ${EXEC_STEP_CODE_REVIEW}–${EXEC_STEP_EXECUTE} above and registering via Step ${EXEC_STEP_REGISTER}) — the list below is a starting point; \`skyramp_register_test_plan\`'s returned GENERATE list is the final, mandatory one. Generate exactly those items in order; add variations to ADDITIONAL instead. If Step ${EXEC_STEP_COVERAGE} converts an item to UPDATE, backfill from ADDITIONAL (priority order in Step ${EXEC_STEP_COVERAGE})
 
 ${isUIOnlyPR
         ? uiGenerateBlocks ||