@skyramp/mcp 0.2.6 → 0.2.8-rc.1

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.js

@@ -127,7 +127,7 @@ An unintegrated non-route component has no DOM node in the running app and canno
         return `${canInline ? "Read the \`<diff>\` above" : `Read the diff file at \`${p.diffFilePath}\``} and identify every new or modified API endpoint — route registrations, handler methods, controller annotations. Then use the **Router Mounting / Nesting** section above to reconstruct the full URL path for each endpoint by chaining all parent router prefixes down to the handler (e.g. a handler in a file with \`prefix="/reviews"\` that is mounted at \`/{product_id}\` under a router mounted at \`/api/v1/products\` → full path \`/api/v1/products/{product_id}/reviews\`).
 ${diffHasJavaFiles ? JAVA_SPRING_NOTE : ""}
 For each endpoint found: note the HTTP method, full path, and source file.
-${preDetectedEndpoints ? "The endpoint catalog above already lists some changed endpoints — verify and augment with anything it missed." : "No endpoints were pre-detected in the changed files — extract them from the diff."}
+${preDetectedEndpoints ? "The endpoint catalog above already lists some changed endpoints — verify and augment with anything it missed. **If a changed file contains many endpoints (hub/routing files like api.go, routes.py, router.ts), cross-reference against the diff hunks to identify only the endpoints whose handler code actually changed — do not include neighboring routes whose code was untouched.**" : "No endpoints were pre-detected in the changed files — extract them from the diff."}
 **Also identify removed endpoints**: Look for deleted route annotations (lines starting with \`-\` in the diff) in modified files (files that still exist but had routes deleted). A removed endpoint is a route definition present in the base branch but absent in the current branch. Cross-reference against the scanned endpoint listing below — if a deleted route annotation's endpoint still appears there (e.g. moved to another file), it is NOT removed. Only flag endpoints that are truly gone from the codebase.
 **CRITICAL — Query params vs body:** For GET endpoints (especially search/filter/list),
 identify which parameters are URL query params vs request body. Look at framework-specific

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

@@ -154,6 +154,69 @@ 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 = []) {
     const frontendUrl = "<frontend_url>";
     // Slot allocation:
@@ -183,8 +246,19 @@ export function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValu
         })
         : scored;
     const slotOrderedItems = prioritizeAttackSurfaceBundles(scoredAfterExternalDedup);
-    const generateItems = slotOrderedItems.slice(0, Math.min(backendGenerateCount, slotOrderedItems.length));
-    const rawAdditionalItems = slotOrderedItems.slice(backendGenerateCount, topN);
+    // Distribute the backend GENERATE slots evenly across the test types present
+    // (contract vs integration) with spillover, instead of a pure top-N rank slice —
+    // so a backend change isn't starved of (say) integration coverage just because
+    // contract scenarios out-ranked it. See roundRobinByType.
+    const generateItems = roundRobinByType(slotOrderedItems, Math.min(backendGenerateCount, slotOrderedItems.length));
+    // ADDITIONAL = everything not chosen for GENERATE, in original rank order, capped
+    // at the remaining budget. Computed by set-difference (not a positional slice)
+    // because round-robin may pick items that aren't the first backendGenerateCount by
+    // rank — a positional slice would double-list a generated item or drop one.
+    const generateSet = new Set(generateItems);
+    const rawAdditionalItems = slotOrderedItems
+        .filter((it) => !generateSet.has(it))
+        .slice(0, Math.max(0, topN - backendGenerateCount));
     // Filter additional items whose primary resource + test type already appear in GENERATE
     const generatedCoverage = new Set(generateItems.map((item) => scenarioCoverageKey(item.scenario)));
     const additionalItems = rawAdditionalItems.filter((item) => !generatedCoverage.has(scenarioCoverageKey(item.scenario)));
@@ -345,27 +419,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.
-
-**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)
+**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:
 
-**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";

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

@@ -0,0 +1,203 @@
+/**
+ * PromptPlan — structured prompt composition with phases, steps, and sub-steps.
+ *
+ * Design goals:
+ * - Main steps are always non-conditional; their labels (1, 2, 3, …) are
+ *   static string constants usable in tests without calling any function.
+ * - Sub-steps are sequentially numbered within their parent (1.1, 1.2, 2.1, …).
+ *   No manually chosen suffixes — insertion or removal automatically renumbers.
+ * - Conditional sub-steps: when absent, remaining siblings re-number so the
+ *   LLM never sees a gap in the step sequence.
+ * - Phases group steps under an optional named heading with a configurable
+ *   rendering style.
+ * - preview(params) returns a structured snapshot for developer inspection:
+ *   which steps are active, what their labels are, and why conditional ones
+ *   are absent.
+ *
+ * Usage:
+ *   const _plan = new PromptPlan<MyParams>()
+ *     .addPhase("main", "Task Instructions", { headerLevel: "##", stepFormat: "hash" })
+ *     .step("READ",   "Read the files",   (p) => buildReadBody(p))
+ *     .subStep("PATHS", "Resolve paths",  (p) => buildPathsBody(p))
+ *     .step("EXTRACT", "Extract items",   (p) => buildExtractBody(p))
+ *     .subStep("TRACE", "Trace callers",  (p) => buildTraceBody(p),
+ *       { when: (p) => p.hasUnmatched, whenDesc: "unmatched backend files present" })
+ *     .step("CALL",   "Call the tool",    (p) => buildCallBody(p))
+ *     .done();
+ *
+ *   // Static constants for non-conditional steps (safe to export at module level)
+ *   export const STEP_READ    = _plan.labels.READ;    // "1"
+ *   export const STEP_PATHS   = _plan.labels.PATHS;   // "1.1"
+ *   export const STEP_EXTRACT = _plan.labels.EXTRACT; // "2"
+ *   export const STEP_CALL    = _plan.labels.CALL;    // "3"
+ *
+ *   // Dynamic accessor for the conditional sub-step
+ *   export const getStepTrace = (p: MyParams) => _plan.labelFor("TRACE", p); // "2.1" | null
+ *
+ *   // Render for the LLM
+ *   const promptText = _plan.render(params);
+ *
+ *   // Developer review
+ *   console.log(_plan.preview(params));
+ */
+export type StepBody<P> = (params: P) => string;
+/** Step title: either a static string or a function for dynamic titles. */
+export type StepTitle<P> = string | ((params: P) => string);
+export type StepCondition<P> = (params: P) => boolean;
+interface SubStepDef<P> {
+    key: string;
+    title: StepTitle<P>;
+    body: StepBody<P>;
+    condition?: StepCondition<P>;
+    conditionDesc?: string;
+}
+interface StepDef<P> {
+    key: string;
+    title: StepTitle<P>;
+    body: StepBody<P>;
+    subSteps: SubStepDef<P>[];
+}
+interface PhaseDef<P> {
+    key: string;
+    title: string;
+    headerLevel: "##" | "###" | "hidden";
+    stepFormat: "hash" | "bold";
+    steps: StepDef<P>[];
+}
+export interface SubStepPreview {
+    key: string;
+    /** Computed label if active (e.g. "2.1"), or "N.?" if conditional and absent. */
+    label: string;
+    title: string;
+    active: boolean;
+    /** Human-readable description of the condition gating this sub-step. */
+    conditionDesc?: string;
+}
+export interface StepPreview {
+    key: string;
+    label: string;
+    title: string;
+    subSteps: SubStepPreview[];
+}
+export interface PhasePreview {
+    key: string;
+    title: string;
+    steps: StepPreview[];
+}
+export interface PlanPreview {
+    phases: PhasePreview[];
+    /** Total steps (main + sub-steps) that are active for the given params. */
+    activeStepCount: number;
+    /** Total steps registered in the plan, including conditional ones. */
+    totalStepCount: number;
+}
+export declare class PhaseBuilder<P extends object> {
+    private readonly _plan;
+    private readonly _phase;
+    private _lastStep;
+    constructor(plan: PromptPlan<P>, phase: PhaseDef<P>);
+    /**
+     * Add a non-conditional main step.
+     * Main steps always appear in the rendered output and always carry a stable
+     * label (1, 2, 3, …) regardless of which sub-steps are active.
+     */
+    step(key: string, title: StepTitle<P>, body: StepBody<P>): this;
+    /**
+     * Add a sub-step under the most recently declared main step.
+     * Sub-steps are sequentially numbered within their parent (1.1, 1.2, …).
+     *
+     * When opts.when is provided the sub-step is conditional: if the condition
+     * returns false for the given params, the step is omitted and remaining
+     * siblings re-number so the LLM never sees a gap.
+     *
+     * @throws when called before any step() in this phase.
+     */
+    subStep(key: string, title: StepTitle<P>, body: StepBody<P>, opts?: {
+        when?: StepCondition<P>;
+        whenDesc?: string;
+    }): this;
+    /** Finish building this phase and return the parent PromptPlan. */
+    done(): PromptPlan<P>;
+}
+export declare class PromptPlan<P extends object> {
+    private readonly _phases;
+    private readonly _startFrom;
+    /** Track registered step/sub-step keys for duplicate detection. */
+    private readonly _registeredKeys;
+    /**
+     * @param opts.startFrom - Label of the first main step. Defaults to 1.
+     *   Use 0 for execution-plan style (Step 0, Step 1, Step 2, …).
+     */
+    constructor(opts?: {
+        startFrom?: number;
+    });
+    /** @internal Register a key and throw if already taken. */
+    _registerKey(key: string): void;
+    /**
+     * Add a phase and return a PhaseBuilder to register its steps.
+     * Multiple phases share a single global main-step counter, so step labels
+     * increment continuously across phase boundaries.
+     */
+    addPhase(key: string, title: string, opts?: {
+        /** Markdown heading level for the phase header. "hidden" emits no header. */
+        headerLevel?: "##" | "###" | "hidden";
+        /**
+         * Step header rendering style.
+         * "hash" => "### Step N: Title"  (analysis prompt style)
+         * "bold" => "**Step N — Title**" (execution plan style)
+         */
+        stepFormat?: "hash" | "bold";
+    }): PhaseBuilder<P>;
+    /**
+     * Static label map for all non-conditional steps (main steps and
+     * unconditional sub-steps). Conditional sub-steps are not present here —
+     * use labelFor() for those.
+     *
+     * Safe to export as module-level constants for use in tests.
+     *
+     * **Ordering constraint**: unconditional sub-steps that appear *after* a
+     * conditional sibling will have a stable label here only if no conditional
+     * siblings precede them. When a conditional sibling is active at runtime,
+     * labelFor() will assign a higher number than the static label here. To
+     * avoid this mismatch, place conditional sub-steps AFTER all unconditional
+     * siblings, or use labelFor() for any sub-step with a conditional predecessor.
+     *
+     * O(steps) per call — intentionally avoids a stale-cache window during plan
+     * construction. Plans have ~6 steps so the cost is negligible; exported
+     * constants are evaluated once at module-load time.
+     */
+    get labels(): Record<string, string>;
+    /**
+     * Dynamic label for any registered step given runtime params.
+     *
+     * Returns null when the step has a condition that evaluates to false.
+     * Throws when key is not registered in this plan.
+     *
+     * For non-conditional steps the result equals labels[key], but using
+     * labels is preferred for those since it avoids passing params.
+     */
+    labelFor(key: string, params: P): string | null;
+    /**
+     * Render the full prompt for the given params.
+     *
+     * - Phase headers are emitted when headerLevel is not "hidden".
+     * - Steps are formatted per the phase's stepFormat.
+     * - Conditional sub-steps absent for these params are skipped; remaining
+     *   siblings re-number with no gaps.
+     * - Each section (header + body) is separated by a single blank line.
+     */
+    render(params: P): string;
+    /**
+     * Return a structured preview of all steps and their active state for the
+     * given params. Useful in development, tests, and debugging to verify exactly
+     * which steps would be emitted and what labels they carry.
+     *
+     * @example
+     *   const pv = _plan.preview({ ...params, unmatchedFiles: [] });
+     *   // pv.phases[0].steps[1].subSteps[0] =>
+     *   //   { key: "TRACE_CALLERS", label: "2.?", active: false,
+     *   //     conditionDesc: "non-frontend unmatched backend files present" }
+     */
+    preview(params: P): PlanPreview;
+}
+export {};

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

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

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

@@ -0,0 +1,35 @@
+export declare const MAX_TESTS_TO_GENERATE = 3;
+export declare const MAX_RECOMMENDATIONS = 20;
+export declare const MAX_CRITICAL_TESTS = 3;
+/**
+ * Error string emitted by skyramp_integration_test_generation when both
+ * an explicit authHeader and a workspace api.authType are passed simultaneously.
+ * Both the tool description and all prompt locations import this constant,
+ * so every occurrence is character-for-character identical by construction.
+ */
+export declare const AUTH_CONFLICT_ERROR_MSG = "Auth header and auth type cannot be supported at the same time.";
+export declare function buildArchitectPreamble(isDiffScope: boolean): string;
+export declare function buildContextFetchingGuidance(sessionId?: string): string;
+export declare function buildReasoningProtocol(): string;
+export interface AuthCallParams {
+    authHeader: string;
+    authScheme?: string;
+    authToken?: string;
+}
+/**
+ * Returns the authScheme snippet for a given authHeader + authType combination.
+ *
+ * Delegates scheme resolution to getAuthScheme() in workspaceAuth.ts — the single
+ * source of truth — so this file no longer maintains its own slug→scheme table.
+ */
+export declare function getAuthSnippets(authHeaderValue: string, authType?: string, explicitScheme?: string): {
+    authSchemeSnippet: string;
+    authTokenSnippet: string;
+};
+export declare const PATH_PARAM_UUID_GUIDANCE: string;
+export declare function buildTestPatternGuidelines(): string;
+export declare function buildTestQualityCriteria(): string;
+export declare function buildGenerationRules(isUIOnlyPR: boolean): string;
+export declare function buildVerificationChecklist(topN: number, maxGen: number, codeReviewStepLabel?: string): string;
+export declare function buildFewShotExamples(): string;
+export declare function buildToolWorkflows(authHeaderValue: string, authTypeValue?: string, explicitScheme?: string): string;

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

@@ -0,0 +1,31 @@
+/**
+ * Shared dedup primitives used by both diff-mode (diffExecutionPlan.ts) and
+ * full-repo mode (fullRepoCatalog.ts). Extracted here to avoid circular imports.
+ */
+import { DraftedScenario } from "../../types/RepositoryAnalysis.js";
+export declare function scenarioCoverageKey(scenario: DraftedScenario): string;
+/**
+ * Method-aware coverage key for external test dedup.
+ * Unlike scenarioCoverageKey (resource::testType), this includes the HTTP method
+ * so that e.g. an external test covering "GET /orders" doesn't block generating
+ * a test for "PUT /orders" — a different operation on the same resource.
+ */
+export declare function externalDedupKey(scenario: DraftedScenario): string;
+export declare function isAttackSurfaceSecurityBoundary(scenario: DraftedScenario): boolean;
+export declare function isOrdinaryDirectAuthBoundary(scenario: DraftedScenario): boolean;
+/**
+ * Build a set of coverage keys from external (non-Skyramp) tests.
+ * Parses `testLocations` entries tagged with `[external]` to extract the
+ * method-aware `METHOD::resource::testType` keys they cover.
+ */
+export declare function buildExternalCoverageSet(testLocations: Record<string, string>): Set<string>;
+export declare const TASK_UI_PRESCAN = "0";
+export declare const TASK_ANALYZE_MAINTAIN = "1";
+export declare const TASK_GENERATE = "2";
+export declare const TASK_SUBMIT = "3";
+export declare const TESTBOT_TASK1_STEP_ANALYZE = "1";
+export declare const TESTBOT_TASK1_STEP_MAINTAIN = "2";
+export declare const TESTBOT_TASK1_STEP_CODE_REVIEW = "3";
+export declare const TESTBOT_TASK1_STEP_UI_GROUNDING = "4";
+export declare const taskRef: (taskId: string) => string;
+export declare const taskStepRef: (taskId: string, stepId: string) => string;

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

@@ -0,0 +1,7 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { DraftedScenario } from "../../types/RepositoryAnalysis.js";
+export declare function mergeEnrichedScenarios(serverScenarios: DraftedScenario[], raw: string): {
+    scenarios: DraftedScenario[];
+    rejectionNotes: string[];
+};
+export declare function registerRecommendTestsPrompt(server: McpServer): void;

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

@@ -0,0 +1,55 @@
+export declare function hasFlutterSdkDep(repositoryPath: string): boolean;
+/**
+ * Returns true if the file path is a frontend file.
+ *
+ * Four tiers:
+ * 1. .vue / .svelte — always frontend; these file types cannot be route handlers.
+ * 2. .dart — always frontend IFF `hasFlutterSdkDep` is true (Flutter project).
+ *    Sits in tier 1 because there's no server-side Dart web framework in scope
+ *    when the Flutter SDK dep is present, so `API_DIR_PATTERN` doesn't apply.
+ * 3. .tsx / .jsx — frontend unless in an API/backend directory (e.g. pages/api/).
+ * 4. Ambiguous extensions (.ts, .js, .css, .html, …) — require a recognised
+ *    frontend directory AND must not be in an API/backend directory.
+ *
+ * The `hasFlutterSdkDep` opt is passed in by the budget-driving caller
+ * (analyzeChangesTool) which has repository context.
+ * Pure-path callers (test-recommendation-prompt, analysisOutputPrompt,
+ * scopeAssessment's own buildScopeAssessmentSection) default to false —
+ * they don't drive the budget.
+ */
+export declare function isFrontendFile(filePath: string, { hasFlutterSdkDep }?: {
+    hasFlutterSdkDep?: boolean;
+}): boolean;
+/**
+ * Returns true if the file path looks like a test file rather than UI source.
+ *
+ * Catches:
+ *   - Skyramp-generated tests (`*_test.ts`, `*_smoke.ts`, `*_contract.ts`,
+ *     `*_fuzz.ts`, `*_integration.ts`, `*_load.ts`, `*_e2e.ts`, `*_ui.ts`)
+ *   - Skyramp scenario files (`scenario_*.json`)
+ *   - Conventional Vitest/Jest/Playwright spec naming
+ *     (`*.spec.{ts,tsx,js,jsx}`, `*.test.{ts,tsx,js,jsx}`)
+ *   - Files inside `__tests__/` directories (Jest convention)
+ *
+ * Used by callers that want to filter test files OUT of frontend-source
+ * processing — `isFrontendFile` returns true for `.spec.ts` under a
+ * frontend directory because the rule is "tier-3 ambiguous + frontend dir,"
+ * but those tests aren't UI source we'd want to ground recommendations in.
+ */
+export declare function isTestFile(filePath: string): boolean;
+/**
+ * Builds the PR scope assessment section.
+ *
+ * When `precomputedUIPct` is provided (0 = backend-only, 100 = UI-only) the server
+ * has already determined the split unambiguously — skip Steps A–C and emit one line.
+ *
+ * For mixed PRs (`precomputedUIPct` is undefined, `hasFrontendChanges` is true) skip
+ * Steps A–C but keep Step D so the LLM can apply judgment to determine the UI%.
+ *
+ * Falls back to the full four-step assessment when no precomputed data is available.
+ */
+export declare function buildScopeAssessmentSection(maxTotal?: number, maxGenerate?: number, isUIOnly?: boolean, 
+/** Server-determined UI/E2E percentage. `undefined` = mixed PR or unknown. */
+precomputedUIPct?: number, 
+/** Whether the diff contains frontend files (true ↔ mixed PR when precomputedUIPct is undefined). */
+hasFrontendChanges?: boolean): string;

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

@@ -109,8 +109,8 @@ function checkPubspec(pubspecPath) {
  * 4. Ambiguous extensions (.ts, .js, .css, .html, …) — require a recognised
  *    frontend directory AND must not be in an API/backend directory.
  *
- * The `hasFlutterSdkDep` opt is passed in by the budget-driving callers
- * (uiAnalyzeChangesTool, analyzeChangesTool) which have repository context.
+ * The `hasFlutterSdkDep` opt is passed in by the budget-driving caller
+ * (analyzeChangesTool) which has repository context.
  * Pure-path callers (test-recommendation-prompt, analysisOutputPrompt,
  * scopeAssessment's own buildScopeAssessmentSection) default to false —
  * they don't drive the budget.

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

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

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

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

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

@@ -0,0 +1,6 @@
+import { RepositoryAnalysis, AnalysisScope } from "../../types/RepositoryAnalysis.js";
+import { WorkspaceAuthType } from "../../utils/workspaceAuth.js";
+import { PRTestContext } from "../../utils/pr-comment-parser.js";
+import { buildExternalCoverageSet, externalDedupKey } from "./recommendationShared.js";
+export { buildExternalCoverageSet, externalDedupKey };
+export declare function buildRecommendationPrompt(analysis: RepositoryAnalysis, analysisScope?: AnalysisScope, topN?: number, prContext?: PRTestContext, workspaceAuthHeader?: string, workspaceAuthType?: WorkspaceAuthType, workspaceAuthScheme?: string, maxGenerateOverride?: number, sessionId?: string): string;