@skyramp/mcp 0.2.6 → 0.2.7

package/build/commands/commandLibrary.d.ts

@@ -0,0 +1,12 @@
+import type { OneClickCommandId, OneClickCommandDef } from "../types/OneClickCommands.js";
+export declare function getCommand(id: OneClickCommandId): OneClickCommandDef;
+export declare function getAllCommands(): OneClickCommandDef[];
+export declare function getCommandIds(): OneClickCommandId[];
+/**
+ * Look up a command by its string ID. Accepts any string so the tool handler
+ * does not need to cast; throws with a helpful message listing valid IDs if
+ * the ID is not found.
+ */
+export declare function lookupCommand(id: string): OneClickCommandDef;
+export { TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND } from "./testThisEndpointCommand.js";
+export { FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND } from "./recommendTestsAndExecuteCommand.js";

package/build/commands/recommendTestsAndExecuteCommand.d.ts

@@ -0,0 +1,2 @@
+import type { OneClickCommandDef } from "../types/OneClickCommands.js";
+export declare const FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND: OneClickCommandDef;

package/build/commands/testThisEndpointCommand.d.ts

@@ -0,0 +1,2 @@
+import type { OneClickCommandDef } from "../types/OneClickCommands.js";
+export declare const TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND: OneClickCommandDef;

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

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, registerUiAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerActionsTool, } from "./tools/test-management/index.js";
+import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerActionsTool, } from "./tools/test-management/index.js";
 import { registerTestbotPrompt } from "./prompts/testbot/testbot-prompts.js";
 import { registerTestbotResource } from "./resources/testbotResource.js";
 import { registerSubmitReportTool } from "./tools/submitReportTool.js";
@@ -152,7 +152,6 @@ codeQualityTools.forEach((registerTool) => registerTool(server));
 registerAnalysisResources(server);
 registerProgressResource(server);
 // Register unified test-management tools (replaces separate test-maintenance tools)
-registerUiAnalyzeChangesTool(server);
 registerAnalyzeChangesTool(server);
 registerAnalyzeTestHealthTool(server);
 registerActionsTool(server);

package/build/playwright/PlaywrightTraceService.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Service that manages a Playwright TraceRecordingBackend instance,
+ * exposing browser tools + skyramp_export_zip for use by the Skyramp MCP.
+ *
+ * The Playwright fork is CJS; this project is ESM. We use createRequire
+ * to bridge the module systems.
+ */
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface PlaywrightTraceOptions {
+    /** Run the browser in headless mode. */
+    headless?: boolean;
+    /** Directory for output files (zip, HAR). Defaults to cwd. */
+    outputDir?: string;
+}
+export declare class PlaywrightTraceService {
+    private _backend;
+    private _tools;
+    private _options;
+    constructor(options?: PlaywrightTraceOptions);
+    initialize(): Promise<void>;
+    isInitialized(): boolean;
+    getTools(): McpTool[];
+    callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult>;
+    shutdown(): Promise<void>;
+}
+export {};

package/build/playwright/index.d.ts

@@ -0,0 +1,3 @@
+export { PlaywrightTraceService, type PlaywrightTraceOptions, } from "./PlaywrightTraceService.js";
+export { registerPlaywrightTools, getPlaywrightTraceService, } from "./registerPlaywrightTools.js";
+export { registerTraceRecordingPrompt } from "./traceRecordingPrompt.js";

package/build/playwright/registerPlaywrightTools.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Registers all Playwright browser tools (+ skyramp_export_zip) as passthrough
+ * tools in the Skyramp MCP server, delegating calls to PlaywrightTraceService.
+ */
+import { PlaywrightTraceService, type PlaywrightTraceOptions } from "./PlaywrightTraceService.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function getPlaywrightTraceService(): PlaywrightTraceService | null;
+export declare function registerPlaywrightTools(server: McpServer, options?: PlaywrightTraceOptions): Promise<void>;

package/build/playwright/registerPlaywrightTools.js

@@ -26,11 +26,17 @@ export async function registerPlaywrightTools(server, options) {
     // The full set (23 tools) overwhelms the LLM and causes it to use
     // browser_evaluate/browser_run_code instead of the simpler tools.
     //
-    // The DOM Analyzer group (browser_blueprint*, browser_sitemap_*,
-    // browser_widget_contract_lookup) is referenced by skyramp_testbot's
-    // Task 1 UI Recommendation Grounding and Task 2 capture-act-capture
-    // discipline. Omitting them here would silently make the prompt's
-    // instructions uncallable.
+    // browser_blueprint is the only DOM Analyzer tool registered — it handles
+    // both full captures and same-URL deltas via the URL-cache (isFullCapture).
+    // browser_blueprint_diff, browser_sitemap_build, browser_sitemap_query fire
+    // 0 times in production evals and have no active call path in the testbot prompt.
+    //
+    // browser_widget_contract_lookup / browser_widget_contract_cache are
+    // intentionally excluded: the curated fingerprint library only covers
+    // test fixtures (not production widgets), and the LLM can handle custom
+    // widgets via snapshot-driven trial-and-error without the tool.
+    // The widgetType field on blueprint elements still signals "custom" to
+    // the agent — no guidance is lost.
     const ESSENTIAL_TOOLS = new Set([
         'browser_navigate',
         'browser_snapshot',
@@ -53,13 +59,8 @@ export async function registerPlaywrightTools(server, options) {
         'browser_visual_snapshot',
         'skyramp_export_zip',
         'skyramp_load_trace',
-        'browser_mouse_action',
-        // DOM Analyzer tools (Phase C)
+        // DOM Analyzer: blueprint capture (capture-act-capture pattern)
         'browser_blueprint',
-        'browser_blueprint_diff',
-        'browser_sitemap_build',
-        'browser_sitemap_query',
-        'browser_widget_contract_lookup',
     ]);
     const filteredTools = tools.filter((t) => ESSENTIAL_TOOLS.has(t.name));
     logger.info(`Filtering to ${filteredTools.length} essential tools (from ${tools.length} total)`);

package/build/playwright/traceRecordingPrompt.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MCP prompt that guides the LLM through the Playwright-based trace recording
+ * and Skyramp test generation flow.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface TraceRecordingPromptOpts {
+    /** Directory where zip files should be written. Defaults to same dir as test file. */
+    outputDir?: string;
+    /** Whether to run skyramp_modularization after generation. Default: true. Set false in CI. */
+    modularize?: boolean;
+}
+export declare function getTraceRecordingPromptText(opts?: TraceRecordingPromptOpts): string;
+export declare function registerTraceRecordingPrompt(server: McpServer): void;

package/build/playwright/traceRecordingPrompt.js

@@ -42,20 +42,12 @@ Then execute in strict order:
 - **No Docker required**: the \`browser_*\` tools run a local browser session managed by the MCP server. Docker is ONLY used by \`skyramp_start_trace_collection\` (manual recording mode). Never suggest or check for Docker when using AI-driven recording.
 ${modularizeNote}
 
-### Tool discipline — three concepts, don't conflate
+### Tool discipline — two concepts, don't conflate
 
-These concepts drive the DOM Analyzer capture tools (\`browser_sitemap_build\`, \`browser_sitemap_query\`, \`browser_blueprint\`) and constrain how their outputs flow into generated test code:
+These concepts drive the DOM Analyzer capture tools and constrain how their outputs flow into generated test code:
 
 - **\`browser_snapshot\` — ephemeral refs**: the \`ref=e29\` values change on every call. Use them ONLY for dispatching the next 1–2 interactions (\`browser_click\`, \`browser_type\`, etc.). **Never put refs in generated test code** — they will not exist at playback time.
-- **\`browser_blueprint\` — stable logical names**: logical names like \`add_order_btn\` and their derived \`getByRole\` locators survive page reloads and playback. Use them in generated test code. Call \`browser_blueprint\` only when the DOM has changed since the last known-good blueprint (modal opens, form submits, filter changes, mutable actions); for pure navigation to an already-crawled URL, reuse the Sitemap cache via \`browser_sitemap_query\`.
-- **\`browser_sitemap_build\` — cached once per session**: crawls the whole app into a Sitemap. Call it once at the start of a session; subsequent calls within ~30 minutes reuse the cache unless \`refresh: true\` is passed. Read already-crawled pages via \`browser_sitemap_query\` (modes: \`page\`, \`edges\`, \`mapJson\`, \`outline\`) — do not re-call \`browser_sitemap_build\` to "check."
-
-### Tool discipline — delta tools (consumers of captures)
-
-These consume the outputs of the capture tools above; they don't capture state themselves.
-
-- **\`browser_blueprint_diff\` — structured before/after delta**: takes two \`browser_blueprint\` results and returns \`elementsAdded\`, \`elementsRemoved\`, \`textChanges\`, \`repeatingCountChanges\`, \`urlChanged\`. Use it to derive assertions from observable state changes rather than guessing at what "success" looks like — capture before an action, perform the action, capture after, diff. An empty diff is itself a meaningful signal (e.g. a silent failure worth catching).
-- **\`browser_widget_contract_lookup\` — custom widget interaction recipes**: when a blueprint element has \`widgetType: "custom"\` or \`"unknown"\`, look up its interaction recipe by \`fingerprint\` + \`ref\`. On \`"found"\`, the returned contract specifies the interaction steps (e.g. for a Radix Select: click trigger → wait for portal → click option). On \`"needs_inference"\`, fall through to snapshot-driven trial clicks. Use this so generated tests interact with custom widgets through stable contracts, not brittle positional clicks.
+- **\`browser_blueprint\` — stable logical names**: logical names like \`add_order_btn\` and their derived \`getByRole\` locators survive page reloads and playback. Use them in generated test code. Call \`browser_blueprint\` before and after each meaningful action to capture state changes.
 
 ### Assertions
 Call \`browser_assert\` when assertions are needed. Always provide the \`expected\` value.

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

@@ -0,0 +1 @@
+export declare function getCodeReusePrompt(testFile: string, language: string, framework?: string): string;

package/build/prompts/enhance-assertions/contractProviderAssertionsPrompt.d.ts

@@ -0,0 +1,2 @@
+import { EnhanceType } from "./sharedAssertionRules.js";
+export declare function getContractProviderAssertionsPrompt(testFile: string, enhanceType: EnhanceType): string;

package/build/prompts/enhance-assertions/integrationAssertionsPrompt.d.ts

@@ -0,0 +1,2 @@
+import { EnhanceType } from "./sharedAssertionRules.js";
+export declare function getIntegrationAssertionsPrompt(testFile: string, enhanceType: EnhanceType): string;

package/build/prompts/enhance-assertions/sharedAssertionRules.d.ts

@@ -0,0 +1,15 @@
+export type EnhanceType = "generation" | "maintenance";
+export declare const MAINTENANCE_SCOPE_NOTE = "Apply only to new test functions you are adding and existing test functions affected by changes in the diff. Do NOT modify test functions unrelated to the diff.";
+export declare function maintenanceTaskSuffix(enhanceType: EnhanceType): string;
+export interface AssertionEnrichmentExample {
+    language: string;
+    code: string;
+}
+export interface AssertionEnrichmentRule {
+    title: string;
+    description: string;
+    subPoints?: string[];
+    examples: AssertionEnrichmentExample[];
+}
+export declare function renderRule(index: number, rule: AssertionEnrichmentRule): string;
+export declare function getAssertionsPrompt(specificRules: AssertionEnrichmentRule[], scope: string, testFile: string, enhanceType: EnhanceType): string;

package/build/prompts/enhance-assertions/uiAssertionsPrompt.d.ts

@@ -0,0 +1,2 @@
+import { EnhanceType } from "./sharedAssertionRules.js";
+export declare function getUIAssertionsPrompt(testFile: string, enhanceType: EnhanceType): string;

package/build/prompts/fix-error-prompt.d.ts

@@ -0,0 +1 @@
+export declare function getFixErrorsPrompt(): string;

package/build/prompts/initialize-workspace/initializeWorkspacePrompt.d.ts

@@ -0,0 +1 @@
+export declare const INIT_WORKSPACE_INSTRUCTIONS: string;

package/build/prompts/modularization/integration-test-modularization.d.ts

@@ -0,0 +1 @@
+export declare function getModularizationPrompt(filePath: string): string;

package/build/prompts/modularization/ui-test-modularization.d.ts

@@ -0,0 +1 @@
+export declare function getModularizationPrompt(filePath: string): string;

package/build/prompts/personas.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Skyramp personas injected into tool descriptions and prompts.
+ *
+ * In TestBot environments (SKYRAMP_FEATURE_TESTBOT=1), the persona is injected
+ * once via `claude --append-system-prompt` from the testbot GitHub Action
+ * (see testbot.git `src/agents/claude.ts` `loadQaPersona()`) rather than
+ * repeating it in every tool description. In that case getPersonaPrefix()
+ * returns empty string to avoid wasting context tokens. The testbot action
+ * pulls SKYRAMP_QA_PERSONA at runtime via the `@skyramp/mcp/personas` export.
+ *
+ * In IDE/MCP-direct environments, it is included in each tool description so the
+ * model has the role context available without a separate system prompt.
+ */
+export declare const SKYRAMP_QA_PERSONA = "You are acting as a Skyramp QA Automation Engineer. Your responsibility is to translate user test intent into precise, deterministic test artifacts \u2014 whether generating API tests from specs, recording browser interactions for UI flows, or maintaining existing test suites. Derive all parameters strictly from the codebase, workspace config, API schemas, and page snapshots. Never guess or hallucinate values.";
+/**
+ * Returns the persona prefix for use in tool descriptions.
+ * Returns an empty string when running inside TestBot — the testbot action
+ * appends the persona via `claude --append-system-prompt` instead, so we
+ * avoid duplicating it in every tool description.
+ */
+export declare function getPersonaPrefix(): string;

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

@@ -0,0 +1 @@
+export declare function getPomAwareCodeReusePrompt(testFile: string): string;

package/build/prompts/startTraceCollectionPrompts.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerStartTraceCollectionPrompt(mcpServer: McpServer): void;

package/build/prompts/test-maintenance/actionsInstructions.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Prompt language for skyramp_actions output — the LLM_INSTRUCTIONS block
+ * emitted to the agent that applies UPDATE and REGENERATE edits.
+ *
+ * Kept separate from actionsTool.ts so prompt text is co-located with other
+ * maintenance prompts and can be reviewed/edited without touching tool logic.
+ */
+export interface RenameEntry {
+    oldPath: string;
+    newPath: string;
+    method: string;
+}
+/** Strategy string for URL-path find-and-replace updates. */
+export declare function buildRenameStrategy(): string;
+/** Strategy string for file renames after path substitution. */
+export declare function buildFileRenameStrategy(): string;
+/** Strategy string for in-place UPDATE edits. */
+export declare function buildUpdateStrategy(): string;
+/** Strategy string for REGENERATE — call generation tool to overwrite the file. */
+export declare function buildRegenerateStrategy(): string;
+/** Per-file instruction block for a single UPDATE recommendation. */
+export declare function buildUpdateFileInstruction(params: {
+    testFile: string;
+    renames: RenameEntry[];
+    suggestedNewFile?: string;
+    updateInstructions?: string;
+    rationale?: string;
+}): string;
+/** Per-file instruction block for a single REGENERATE recommendation. */
+export declare function buildRegenerateFileInstruction(params: {
+    testFile: string;
+    updateInstructions?: string;
+    outputDir: string;
+    outputFile: string;
+}): string;

package/build/prompts/test-maintenance/drift-analysis-prompt.d.ts

@@ -0,0 +1,4 @@
+export declare function buildDriftAnalysisPrompt(stateFile?: string, existingTests?: Array<{
+    testFile: string;
+    source?: string;
+}>): string;

package/build/prompts/test-maintenance/driftAnalysisSections.d.ts

@@ -0,0 +1,13 @@
+export declare function buildActionDecisionTree(): string;
+/** @deprecated use the individual check functions; this function is no longer part of the prompt */
+export declare function buildBreakingChangePatterns(): string;
+export declare function buildCheckEndpointExistence(): string;
+export declare function buildCheckResponseShape(): string;
+export declare function buildCheckAuthAndAuthorization(): string;
+export declare function buildCheckBehavioralContract(): string;
+export declare function buildCheckAssignAction(): string;
+export declare function buildCheckAdditiveFields(): string;
+export declare function buildDriftOutputChecklist(stateFile?: string, existingTests?: Array<{
+    testFile: string;
+    source?: string;
+}>): string;

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

@@ -0,0 +1,84 @@
+import { WorkspaceAuthType } from "../../utils/workspaceAuth.js";
+import { ScannedEndpoint } from "../../utils/repoScanner.js";
+/** Lightweight diff summary for the analysis output prompt. */
+interface DiffSummary {
+    changedFiles: string[];
+    newEndpoints: Array<{
+        method: string;
+        path: string;
+        sourceFile: string;
+    }>;
+    modifiedEndpoints: Array<{
+        method: string;
+        path: string;
+        sourceFile: string;
+    }>;
+    removedEndpoints?: Array<{
+        method: string;
+        path: string;
+        sourceFile: string;
+    }>;
+}
+interface AnalysisOutputParams {
+    sessionId: string;
+    stateFile?: string;
+    repositoryPath: string;
+    analysisScope: string;
+    parsedDiff?: DiffSummary;
+    /** Path to temp file containing the full unified diff.
+     *  Content is read once in buildAnalysisOutputText via readDiffFile — callers do not pass diffContent. */
+    diffFilePath?: string;
+    /** Resolved diff content — populated internally by buildAnalysisOutputText, not by callers. */
+    diffContent?: string;
+    /**
+     * Relative paths of all files whose names look like route/controller definitions.
+     * For full-repo scope: the LLM reads these to find endpoints from frameworks the
+     * static regex doesn't cover (Django, Axum, Ktor, FastAPI without prefix, etc.).
+     */
+    candidateRouteFiles?: string[];
+    scannedEndpoints: ScannedEndpoint[];
+    wsBaseUrl: string;
+    wsAuthHeader: string;
+    wsAuthType: WorkspaceAuthType | "";
+    wsSchemaPath: string;
+    /** True when wsSchemaPath was successfully fetched and parsed at analysis time */
+    specFetchSucceeded?: boolean;
+    routerMountContext: string[];
+    /** Content of key routing/mount files, read server-side (size-capped).
+     *  Present when no spec is available — inlined so LLM doesn't need an extra read step. */
+    routerFileContents?: Array<{
+        file: string;
+        content: string;
+    }>;
+    nextTool?: string;
+    /**
+     * Changed files that contain no HTTP endpoint registrations (utilities, helpers,
+     * services, models). When non-empty the LLM is instructed to trace callers of
+     * the changed functions to find the correct HTTP surface (Fix 2 / Bug 5).
+     * Only meaningful in CurrentBranchDiff scope.
+     */
+    unmatchedFiles?: string[];
+}
+/** "1" — Read source files / changed files */
+export declare const ANALYSIS_STEP_READ_FILES: string;
+/** "1.1" — Verify/build/validate endpoint path resolution table */
+export declare const ANALYSIS_STEP_RESOLVE_PATHS: string;
+/** "2" — Extract or map endpoints */
+export declare const ANALYSIS_STEP_EXTRACT: string;
+/** "3" — Draft scenarios / present catalog / identify drift */
+export declare const ANALYSIS_STEP_DRAFT: string;
+/** "4" — Call the downstream tool (recommend_tests / analyze_test_health) */
+export declare const ANALYSIS_STEP_CALL_TOOL: string;
+/**
+ * Returns the step label for the trace-callers sub-step given runtime params.
+ * Returns "2.1" when the step is active (non-frontend unmatched backend files
+ * present in diff scope), or null when the step is absent.
+ *
+ * Use in tests instead of hardcoding "2.1":
+ *   const label = getStepTraceCallers(params);
+ *   if (label) expect(output).toContain(`### Step ${label}: Trace callers`);
+ *   else expect(output).not.toContain("Trace callers");
+ */
+export declare function getStepTraceCallers(p: AnalysisOutputParams): string | null;
+export declare function buildAnalysisOutputText(p: AnalysisOutputParams): string;
+export {};

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

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

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

@@ -1,3 +1,4 @@
+import { jest } from "@jest/globals";
 jest.mock("@skyramp/skyramp", () => ({
     WorkspaceConfigManager: { create: jest.fn() },
 }));

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

@@ -0,0 +1,17 @@
+import { DraftedScenario } from "../../types/RepositoryAnalysis.js";
+import { PriorityTier } from "../../types/TestRecommendation.js";
+/** "0" — Code Review: correctness analysis */
+export declare const EXEC_STEP_CODE_REVIEW: string;
+/** "1" — External test coverage verification */
+export declare const EXEC_STEP_COVERAGE: string;
+/** "2" — Parameter grounding & priority assignment */
+export declare const EXEC_STEP_ENRICH: string;
+/** "3" — Diversity check */
+export declare const EXEC_STEP_DIVERSITY: string;
+/** "4" — Execute merged plan */
+export declare const EXEC_STEP_EXECUTE: string;
+export declare function buildExecutionPlan(scored: Array<{
+    scenario: DraftedScenario;
+    priority: PriorityTier;
+    novelty: string;
+}>, 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[]): string;

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

@@ -345,27 +345,18 @@ export function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValu
     // frozen, but the `reasoning` CONTENT for UI entries should be blueprint-
     // grounded using concrete elements the agent captured via browser_blueprint.
     const uiGroundingGuidance = hasFrontendChanges ? `
-**UI recommendation grounding — applies to \`testType: "ui"\` entries.** The \`reasoning\` field for \`testType: "ui"\` entries MUST contain at least three of {\`role\`, \`accessibleName\`, \`testId\`, \`stableId\`, \`logicalName\`} cited in key=value form. Entries that omit the tuple are not valid output for UI test types. The agent should call \`browser_blueprint\` on affected pages (if it hasn't already) and use the captured data.
+**UI recommendation grounding — applies to \`testType: "ui"\` entries in BOTH \`newTestsCreated\` and \`additionalRecommendations\`.** UI recommendations must populate three structured fields plus prose fields, all derived from captured \`browser_blueprint\` elements:
 
-**Field stability note for consumers:** \`testId\` and \`stableId\` are stable identifiers (from \`data-testid\` and unique \`id\` attributes respectively) — code-generation consumers can key off them. \`role\` and \`accessibleName\` are derived from ARIA and survive DOM reshuffles. \`logicalName\` is a **display handle, not a stable identifier** — it's derived from role + accessibleName + section context and drifts when the accessibleName text changes. Cite \`logicalName\` for readability in the \`reasoning\` field, but downstream consumers (test generators, scoping tools) should NOT key off it. Prefer \`testId\` > \`stableId\` > \`role + accessibleName\` > \`fingerprint\` for identity.
-
-**Format for singular elements:**
-> role=<role>, accessibleName="<Accessible Name>", testId=<test-id-or-null>, stableId=<id-or-null>, logicalName=<logical_name>
-
-**Format for repeating elements (table rows, list items):** include \`contextText\` values from the row when the recommendation targets a specific row:
-> role=<role>, accessibleName="<template>", testId=<null>, stableId=<null>, logicalName=<name>, contextText=["customer@example.com", "$129.99", "Pending"]
-
-**Example (Edit Order form's Save button on /orders/{id}):**
-> role=button, accessibleName="Save changes", testId=null, stableId=null, logicalName=save_changes_btn — verifies boundary-value clamping on discount_percent (0..100)
-
-**Example (new-order-row recommendation on /orders):**
-> role=button, accessibleName="View details for order 13", testId=null, stableId=null, logicalName=view_details_for_order_btn, contextText=["customer@example.com", "$129.99", "Pending"] — verifies new order row renders with correct customer + total + status
+- **\`targetElements\`** — array of one or more elements (\`role\`, \`accessibleName\`, \`testId\`, \`stableId\`, \`contextText\`, \`mutability\`, \`widgetType\`). Single-element for tests with one dominant target; multi-element for render-state, multi-step, or form tests.
+- **\`pageContext\`** — \`url\` and \`pageHash\` from the BlueprintCapture.
+- **\`description\`** — walkthrough of the test steps and assertions (what the test does, not why it is valuable).
+- **\`reasoning\`** — free-form prose grounded in \`targetElements\` explaining why this test is valuable. Every element cited must appear in \`targetElements\` by its \`accessibleName\` (bolded, character-for-character). See the Blueprint Citation Invariant in the Testbot prompt (step 4) for citation rules, identifier priority (\`testId\` > \`stableId\` > \`role + accessibleName\`), repeating-element format (\`contextText\` parenthetical), and self-check guidance.
 
 **Validates line — applies to \`testType: "ui"\` entries.** The \`Validates:\` line for UI entries should describe an observable behavior the test verifies — what changes on the page after the action, or what state the user can see. Ground this description in the captured blueprint when possible. Reference structural facts (an element appears, a count changes, a status text updates, a URL transitions) rather than implementation language (component names, props, internal state). The line should be readable to someone who has not seen the source diff.
 
-**Scope clarification:** this grounding format applies **only** to \`testType: "ui"\` entries. Contract, integration, e2e, batch-scenario \`reasoning\` and \`Validates:\` fields use their existing conventions (endpoint paths, schemas, fixture chains) — do NOT reformat those. The "Fill in placeholders, then display verbatim" rule above refers to the CATALOG STRUCTURE (sections, ordering, test types); UI entries' \`reasoning\` and \`Validates:\` CONTENT follows this grounding format.
+**Scope clarification:** this grounding rule applies **only** to \`testType: "ui"\` entries. Contract, integration, e2e, batch-scenario \`reasoning\` and \`Validates:\` fields use their existing conventions (endpoint paths, schemas, fixture chains) — do NOT reformat those. The "Fill in placeholders, then display verbatim" rule above refers to the CATALOG STRUCTURE (sections, ordering, test types); UI entries' \`reasoning\` and \`Validates:\` CONTENT follows this grounding rule.
 
-**If blueprint data isn't available** — agent skipped pre-scan, app unreachable, \`BlueprintInvariantError\`, or no candidate page covers the changed component — UI entries may fall back to source-grounded reasoning. Each such entry MUST be flagged with a leading \`[no-blueprint-data]\` marker in the \`reasoning\` field, and the failure mode must be logged in \`issuesFound\` with \`info\` severity naming the entry. Do NOT silently produce ungrounded reasoning without the marker.
+**If blueprint data isn't available** — agent skipped pre-scan, app unreachable, \`BlueprintInvariantError\`, or no candidate page covers the changed component — UI entries must fall back as follows: set \`targetElements: null\`, omit \`pageContext\`, prefix BOTH \`description\` and \`reasoning\` with \`[no-blueprint-data]\`, and log the failure in \`issuesFound\` with \`info\` severity. Do NOT silently produce ungrounded reasoning without the marker in both fields.
 ` : "";
     // UI/E2E guidance — the LLM adds as many as its Budget Plan calls for.
     // Note: if a UI test already occupies a GENERATE slot (uiPlaceholderBlock), that slot

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

@@ -0,0 +1,7 @@
+import { DraftedScenario } from "../../types/RepositoryAnalysis.js";
+import { PriorityTier } from "../../types/TestRecommendation.js";
+export declare function buildFullRepoRecommendations(scored: Array<{
+    scenario: DraftedScenario;
+    priority: PriorityTier;
+    novelty: string;
+}>, topN: number, baseUrl: string, authHeaderValue: string, authSchemeSnippet: string, authTypeValue: string, isFrontendProject?: boolean, isFrontendOnlyProject?: boolean, externalCoverage?: Set<string>): string;

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

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

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

@@ -1,3 +1,4 @@
+import { jest } from "@jest/globals";
 jest.mock("@skyramp/skyramp", () => ({ Skyramp: class {
     } }));
 import { mergeEnrichedScenarios } from "./registerRecommendTestsPrompt.js";