@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/types/RepositoryAnalysis.js

@@ -1,6 +1,4 @@
 import { z } from "zod";
-import { SCENARIO_CATEGORIES } from "./TestRecommendation.js";
-import { TestType } from "./TestTypes.js";
 /**
  * Repository Analysis Types
  * Comprehensive structure for analyzing code repositories
@@ -95,63 +93,13 @@ export const scenarioStepSchema = z.object({
         .optional(),
     bodyMustInclude: z.array(z.string()).optional(),
 });
-export const draftedScenarioSchema = z.object({
-    scenarioName: z.string(),
-    description: z.string(),
-    category: z.enum(SCENARIO_CATEGORIES),
-    priority: z.enum(["high", "medium", "low"]),
-    steps: z.array(scenarioStepSchema),
-    chainingKeys: z.array(z.string()),
-    requiresAuth: z.boolean(),
-    estimatedComplexity: z.enum(["simple", "moderate", "complex"]),
-    source: z.nativeEnum(ScenarioSource).optional(),
-    testType: z.nativeEnum(TestType).optional(),
-    bugCatchingTarget: z.string().optional(),
-});
 export const branchDiffContextSchema = z.object({
     currentBranch: z.string(),
     baseBranch: z.string(),
     changedFiles: z.array(z.string()),
-    newEndpoints: z.array(z.object({
-        path: z.string(),
-        methods: z.array(z.object({
-            method: z.string(),
-            sourceFile: z.string(),
-            interactionCount: z.number(),
-        })),
-    })),
-    modifiedEndpoints: z.array(z.object({
-        path: z.string(),
-        methods: z.array(z.object({
-            method: z.string(),
-            sourceFile: z.string(),
-            changeType: z.enum(["added", "modified", "removed"]),
-        })),
-    })),
-    removedEndpoints: z
-        .array(z.object({
-        path: z.string(),
-        methods: z.array(z.object({
-            method: z.string(),
-            sourceFile: z.string(),
-            changeType: z.literal("removed"),
-        })),
-    }))
-        .optional(),
-    affectedServices: z.array(z.string()),
+    affectedServices: z.array(z.string()).optional(),
     summary: z.string().optional(),
 });
-export const routeDiscoveryInfoSchema = z.object({
-    candidateFiles: z.array(z.string()),
-    staticHints: z.array(z.object({
-        path: z.string(),
-        methods: z.array(z.string()),
-        sourceFile: z.string(),
-    })),
-    openApiPaths: z.array(z.string()),
-    routerMountContext: z.array(z.string()),
-    diffFilePath: z.string().optional(),
-});
 export const analysisMetadataSchema = z.object({
     repositoryName: z.string(),
     analysisDate: z.string(),
@@ -196,7 +144,6 @@ export const repositoryAnalysisSchema = z.object({
         userFlows: z.array(z.string()),
         dataFlows: z.array(z.string()),
         integrationPatterns: z.array(z.string()),
-        draftedScenarios: z.array(draftedScenarioSchema),
     }),
     artifacts: z.object({
         openApiSpecs: z.array(z.object({
@@ -218,10 +165,8 @@ export const repositoryAnalysisSchema = z.object({
         })),
         notFound: z.array(z.string()),
     }),
-    apiEndpoints: z.object({
-        totalCount: z.number(),
+    workspace: z.object({
         baseUrl: z.string(),
-        endpoints: z.array(enrichedEndpointSchema),
     }),
     authentication: z.object({
         method: z.string(),
@@ -252,6 +197,5 @@ export const repositoryAnalysisSchema = z.object({
         estimatedCoverage: z.number().optional(),
         relevantExternalTestPaths: z.array(z.string()).optional(),
     }),
-    routeDiscovery: routeDiscoveryInfoSchema.optional(),
     branchDiffContext: branchDiffContextSchema.optional(),
 });

package/build/types/StepMethod.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+/** What a scenario step's `method` may say, as three closed sets rather than free
+ *  text. `HttpMethod` alone refused a UI recommendation, and `HttpMethod | UiVerb`
+ *  would refuse an operation name — so the third member is what makes the union
+ *  work: a call with no verb writes `OPERATION` and its name goes in `path`. */
+/** Every method RFC 9110 defines. A verb missing here reads as a page
+ *  interaction and skips four checks at once. */
+export declare const HTTP_STEP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE", "CONNECT"];
+/** The page interactions a step may name. TAKEN FROM WHAT RUNS HAVE WRITTEN: eleven
+ *  are every distinct `method` on a `ui` or `e2e` candidate across the 1,858
+ *  plan-state files in eval-logs, and `tap` is the twelfth because the schema and
+ *  the skill offer it. A verb missing here is a REFUSED submission. */
+export declare const UI_STEP_VERBS: readonly ["assert", "click", "drag", "drag-hold", "hover", "inspect", "navigate", "press", "release", "tap", "type", "wait"];
+/** A call to something with no HTTP verb — a GraphQL operation, a Thrift or gRPC
+ *  method. The operation's own name goes in `path`, and in `routes.operation`. */
+export declare const OPERATION_STEP_METHOD = "OPERATION";
+export declare const STEP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE", "CONNECT", "assert", "click", "drag", "drag-hold", "hover", "inspect", "navigate", "press", "release", "tap", "type", "wait", "OPERATION"];
+export type HttpStepMethod = (typeof HTTP_STEP_METHODS)[number];
+export type UiStepVerb = (typeof UI_STEP_VERBS)[number];
+export type StepMethod = (typeof STEP_METHODS)[number];
+/** One spelling of a method reduced to the canonical one, or `undefined` when it is
+ *  none of the three sets. Case and surrounding space are ignored on input and
+ *  fixed on store, so `" post"` and `"Click"` are the same step as `POST` and
+ *  `click`. Without the trim, one trailing space decided which checks ran. */
+export declare function normalizeStepMethod(raw: unknown): StepMethod | undefined;
+/** Whether a method names a page interaction. Read off the canonical spelling,
+ *  so a step that never went through the schema is judged the same way. */
+export declare function isUiStepVerb(raw: unknown): boolean;
+/** Whether a method names an HTTP request. */
+export declare function isHttpStepMethod(raw: unknown): boolean;
+/** The description every `method` field shares, so the three schemas cannot
+ *  describe the same field differently. It says what the field IS; the accepted
+ *  vocabulary is in the error the enum raises, which is where a wrong value gets
+ *  told about it. */
+export declare const STEP_METHOD_DESCRIPTION: string;
+/**
+ * The field itself: normalised first, then checked, so a rejection is about the
+ * verb and never about its capitalisation.
+ */
+export declare const stepMethodSchema: z.ZodEffects<z.ZodEnum<["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE", "CONNECT", "assert", "click", "drag", "drag-hold", "hover", "inspect", "navigate", "press", "release", "tap", "type", "wait", "OPERATION"]>, "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS" | "type" | "TRACE" | "CONNECT" | "assert" | "click" | "drag" | "drag-hold" | "hover" | "inspect" | "navigate" | "press" | "release" | "tap" | "wait" | "OPERATION", unknown>;

package/build/types/StepMethod.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+/** What a scenario step's `method` may say, as three closed sets rather than free
+ *  text. `HttpMethod` alone refused a UI recommendation, and `HttpMethod | UiVerb`
+ *  would refuse an operation name — so the third member is what makes the union
+ *  work: a call with no verb writes `OPERATION` and its name goes in `path`. */
+/** Every method RFC 9110 defines. A verb missing here reads as a page
+ *  interaction and skips four checks at once. */
+export const HTTP_STEP_METHODS = [
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "HEAD",
+    "OPTIONS",
+    "TRACE",
+    "CONNECT",
+];
+/** The page interactions a step may name. TAKEN FROM WHAT RUNS HAVE WRITTEN: eleven
+ *  are every distinct `method` on a `ui` or `e2e` candidate across the 1,858
+ *  plan-state files in eval-logs, and `tap` is the twelfth because the schema and
+ *  the skill offer it. A verb missing here is a REFUSED submission. */
+export const UI_STEP_VERBS = [
+    "assert",
+    "click",
+    "drag",
+    "drag-hold",
+    "hover",
+    "inspect",
+    "navigate",
+    "press",
+    "release",
+    "tap",
+    "type",
+    "wait",
+];
+/** A call to something with no HTTP verb — a GraphQL operation, a Thrift or gRPC
+ *  method. The operation's own name goes in `path`, and in `routes.operation`. */
+export const OPERATION_STEP_METHOD = "OPERATION";
+export const STEP_METHODS = [...HTTP_STEP_METHODS, ...UI_STEP_VERBS, OPERATION_STEP_METHOD];
+const HTTP_BY_SPELLING = new Map(HTTP_STEP_METHODS.map((m) => [m.toLowerCase(), m]));
+const UI_BY_SPELLING = new Map(UI_STEP_VERBS.map((v) => [v, v]));
+/** One spelling of a method reduced to the canonical one, or `undefined` when it is
+ *  none of the three sets. Case and surrounding space are ignored on input and
+ *  fixed on store, so `" post"` and `"Click"` are the same step as `POST` and
+ *  `click`. Without the trim, one trailing space decided which checks ran. */
+export function normalizeStepMethod(raw) {
+    const spelling = String(raw ?? "").trim().toLowerCase();
+    if (!spelling)
+        return undefined;
+    return HTTP_BY_SPELLING.get(spelling) ?? UI_BY_SPELLING.get(spelling) ?? (spelling === "operation" ? OPERATION_STEP_METHOD : undefined);
+}
+/** Whether a method names a page interaction. Read off the canonical spelling,
+ *  so a step that never went through the schema is judged the same way. */
+export function isUiStepVerb(raw) {
+    const method = normalizeStepMethod(raw);
+    return method !== undefined && UI_STEP_VERBS.includes(method);
+}
+/** Whether a method names an HTTP request. */
+export function isHttpStepMethod(raw) {
+    const method = normalizeStepMethod(raw);
+    return method !== undefined && HTTP_STEP_METHODS.includes(method);
+}
+const STEP_METHOD_HELP = `must be an HTTP method (${HTTP_STEP_METHODS.join(", ")}), a page interaction ` +
+    `(${UI_STEP_VERBS.join(", ")}), or "${OPERATION_STEP_METHOD}" for a call with no HTTP verb — ` +
+    `write the operation's own name in \`path\`, not here. Case does not matter.`;
+/** The description every `method` field shares, so the three schemas cannot
+ *  describe the same field differently. It says what the field IS; the accepted
+ *  vocabulary is in the error the enum raises, which is where a wrong value gets
+ *  told about it. */
+export const STEP_METHOD_DESCRIPTION = "What this step does to the system: an HTTP method, a page interaction, or `OPERATION` for a call " +
+    "with no HTTP verb — for that one, write the operation's own name in `path`.";
+/**
+ * The field itself: normalised first, then checked, so a rejection is about the
+ * verb and never about its capitalisation.
+ */
+export const stepMethodSchema = z.preprocess((value) => (typeof value === "string" ? (normalizeStepMethod(value) ?? value.trim()) : value), z.enum(STEP_METHODS, { errorMap: () => ({ message: `method ${STEP_METHOD_HELP}` }) }));

package/build/types/TestAnalysis.d.ts

@@ -41,6 +41,18 @@ export interface MaintenanceActionCore {
      *  downstream stage that reasons about the edit needs both — notably the report-time
      *  working-tree check, which otherwise calls a POM-backed UPDATE unbacked (SKYR-4129). */
     pomFile?: string;
+    /** Visual-snapshot baselines (toHaveScreenshot filenames, e.g. "page-001.png") an UPDATE
+     *  refreshes because the diff changed how the captured page/element looks (SKYR-4298).
+     *  The edit lands in the PNG under `<spec>-snapshots/`, not in the spec, so the
+     *  report-time working-tree check must accept that PNG as the UPDATE's backing, and
+     *  the final `skyramp_execute_test` must receive the list as `rebaselineSnapshots`. */
+    rebaselineSnapshots?: string[];
+    /** True when the UPDATE carries rebaselineSnapshots and no updateInstructions: the
+     *  refresh is its whole maintenance, so no edit to the spec/POM is expected. When false
+     *  (or absent) with baselines listed, the report-time check requires BOTH the edit and
+     *  the rewritten PNG — a listed baseline must never exempt the selector edit the same
+     *  verdict claimed (SKYR-3883 stays in force). */
+    rebaselineOnly?: boolean;
 }
 /** Normalized internal recommendation built from LLM-supplied args.recommendations. */
 export interface DriftRecommendation extends MaintenanceActionCore {

package/build/types/TestExecution.d.ts

@@ -60,6 +60,10 @@ export interface TestExecutionOptions {
     playwrightSaveStoragePath?: string;
     dockerNetwork?: string;
     useHostNetwork?: boolean;
+    /** Visual-snapshot baselines (toHaveScreenshot filenames, e.g. "page-001.png") this run
+     *  replaces instead of comparing against — forwarded to SmartPlaywright as
+     *  SKYRAMP_UPDATE_SNAPSHOTS (SKYR-4298). Only for an intended UI change the diff explains. */
+    rebaselineSnapshots?: string[];
 }
 /**
  * Progress callback for reporting execution status

package/build/types/TestRecommendation.d.ts

@@ -1,33 +1,33 @@
-/** Internal scenario-scoring tier — UPPERCASE, includes CRITICAL. */
-export declare enum PriorityTier {
-    CRITICAL = "CRITICAL",
-    HIGH = "HIGH",
-    MEDIUM = "MEDIUM",
-    LOW = "LOW"
-}
-/** How a scenario relates to the diff — tie-breaker within a priority tier. */
+/** How a scenario relates to the diff. */
 export declare enum Novelty {
     NEW = "new",
     MODIFIED = "modified",
     EXISTING = "existing"
 }
-/** All categories including internal ones. */
+/** Every category, and the only list there is. The plan and the report validate
+ *  against this one: the report used to take a shorter list and rename the three
+ *  above into it, which meant one test carried two category names. */
 export declare const SCENARIO_CATEGORIES: readonly ["new_endpoint", "bug_caught", "requirement_conflict", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"];
 export type ScenarioCategory = typeof SCENARIO_CATEGORIES[number];
-/** Categories valid for tool submissions (excludes internal-only categories). */
-export declare const TEST_CATEGORIES: readonly ["business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"];
-export type TestCategory = typeof TEST_CATEGORIES[number];
-/** Priority assignment for each category. */
-export declare const CATEGORY_PRIORITY: Record<ScenarioCategory, PriorityTier>;
-/** Map internal-only categories to their external equivalent for tool submission. */
-export declare function externalCategory(cat: ScenarioCategory): TestCategory;
+/** What each category means, and whether it expects a failing test. The plan
+ *  tool renders its `category` description from this, so the agent reads these
+ *  sentences as it picks one. `expectsRed` is true only for the two naming a
+ *  specific defect: a wider set would fire verifier 4 on ordinary candidates. */
+export declare const CATEGORY_MEANINGS: Record<ScenarioCategory, {
+    meaning: string;
+    expectsRed: boolean;
+}>;
+/** The category list as the plan tool shows it, one line each, table order. */
+export declare function categoryMenu(): string;
 /**
- * Categories whose scenarios target a specific identified defect — a code flaw
- * (`bug_caught`) or a stated requirement the code contradicts
- * (`requirement_conflict`). They survive external-test dedup: an existing test on
- * the same endpoint exercises the surface, not the flaw, so removing them would
- * drop the only test that fails on the defect.
+ * `category` is a free string whose schema description is an "e.g." list, so the
+ * agent picks the spelling: `Bug_Caught`, `bug-caught` and a trailing space each
+ * skipped verifier 4. Case, surrounding space and the `-`/`_`/space separator
+ * only — no alias list, since a category this misses is one nobody declared.
  */
-export declare const FLAW_TARGETING_CATEGORIES: readonly ["bug_caught", "requirement_conflict"];
-/** Whether `category` targets a specific identified defect (see {@link FLAW_TARGETING_CATEGORIES}). */
-export declare function isFlawTargetingCategory(category: ScenarioCategory | undefined): boolean;
+export declare function normalizeCategory(raw: unknown): string;
+/** Whether a candidate's `category` names a test expected to fail on the current
+ *  code, in any spelling. Verifier 4 and the report's `expectedToFail` derivation
+ *  read this one answer: comparing the field two ways made `Bug_Caught`
+ *  bug-catching in one and ordinary in the other. */
+export declare function categoryExpectsRed(raw: unknown): boolean;

package/build/types/TestRecommendation.js

@@ -1,113 +1,115 @@
-/** Internal scenario-scoring tier — UPPERCASE, includes CRITICAL. */
-export var PriorityTier;
-(function (PriorityTier) {
-    PriorityTier["CRITICAL"] = "CRITICAL";
-    PriorityTier["HIGH"] = "HIGH";
-    PriorityTier["MEDIUM"] = "MEDIUM";
-    PriorityTier["LOW"] = "LOW";
-})(PriorityTier || (PriorityTier = {}));
-/** How a scenario relates to the diff — tie-breaker within a priority tier. */
+/** How a scenario relates to the diff. */
 export var Novelty;
 (function (Novelty) {
     Novelty["NEW"] = "new";
     Novelty["MODIFIED"] = "modified";
     Novelty["EXISTING"] = "existing";
 })(Novelty || (Novelty = {}));
-/** Internal-only categories (not submitted to tools). */
+/** The three categories that say where a test came from or what defect it names,
+ *  rather than what it proves. The server assigns `new_endpoint`; the agent
+ *  declares the other two. */
 const INTERNAL_CATEGORIES = [
-    "new_endpoint", // MEDIUM - diff-direct scenario; where a test came from, not a guarantee of a slot
-    "bug_caught", // CRITICAL - tests targeting a specific <bug_found> flaw identified during enrichment
-    // CRITICAL - tests asserting a requirement the PR title/description (or a
-    // requirements file it references) states, which the implemented behavior
-    // contradicts. Separate from bug_caught deliberately (SKYR-4291): labelled
-    // bug_caught, a requirement-vs-code mismatch competed with the code-review
-    // flaws for the same promotion and lost it on severity. Its own category means
-    // its own carve-out here, first place in the promotion order SKYR-4275's bound
-    // hands out, and its own coverage gate.
+    "new_endpoint", // a diff-direct draft: where it came from, not what it proves
+    "bug_caught", // targets a specific <bug_found> flaw identified during enrichment
+    // Its own category rather than a bug_caught: the two are found by different
+    // reads, and calling a contradicted requirement a code flaw sends the author to
+    // the wrong place to fix it.
     "requirement_conflict",
 ];
-/** External categories valid for tool submissions, ordered by priority. */
+/** The categories that say what a test proves. */
 const CATEGORIES = [
-    // HIGH priority
-    "business_rule", // formula bugs, unique constraints, state machines — most common production failures
+    "business_rule", // formula bugs, unique constraints, state machines
     "security_boundary", // auth, permission, cross-user isolation, idempotency
     "data_integrity", // cascade deletes, orphan prevention, referential integrity
     "breaking_change", // route renames, auth migration, response shape changes
     "auth", // authentication and authorization flows
-    "error_handling", // missing 404/422 guards — silent failures are real bugs
-    // MEDIUM priority
+    "error_handling", // missing 404/422 guards
     "workflow", // cross-resource integration, user journeys
     "data_validation", // input validation and schema enforcement
-    // LOW priority
     "crud", // basic create/read/update/delete operations
 ];
-/** All categories including internal ones. */
+/** Every category, and the only list there is. The plan and the report validate
+ *  against this one: the report used to take a shorter list and rename the three
+ *  above into it, which meant one test carried two category names. */
 export const SCENARIO_CATEGORIES = [...INTERNAL_CATEGORIES, ...CATEGORIES];
-/** Categories valid for tool submissions (excludes internal-only categories). */
-export const TEST_CATEGORIES = CATEGORIES;
-/** Priority assignment for each category. */
-export const CATEGORY_PRIORITY = {
-    // CRITICAL means "this test targets a specific identified flaw" — only bug_caught
-    // asserts that. new_endpoint says where a test came from (a template fired on an
-    // endpoint the diff added), not that it earns a guaranteed slot. Reserving the
-    // top tier for it let server-drafted templates outrank anything an agent said,
-    // by label rather than merit. (The registration enum is SCENARIO_CATEGORIES, so
-    // an agent CAN submit new_endpoint; externalCategory maps it to crud/LOW for
-    // report and merge purposes only.)
-    //
-    // It sits BELOW the categories that state what a test proves, not level with
-    // them. Level was still too high: the last rank key is the candidateId, so among
-    // same-tier candidates the ALPHABET decided. Template names start with the
-    // resource (billing-, bookings-, export-, members-) and an agent names a scenario
-    // for what it checks, so on cc15-org-reviewer-role all 8 templates outranked all
-    // 12 candidates the agent wrote, and 2 of the 3 GENERATE slots went to the letter
-    // "b" beating "o". MEDIUM, not LOW: a template on an endpoint the diff just added
-    // is still worth more than a crud test on an endpoint that was always there. The
-    // floor survives — when the agent offers nothing above MEDIUM, templates still
-    // fill GENERATE.
-    new_endpoint: PriorityTier.MEDIUM,
-    bug_caught: PriorityTier.CRITICAL, // tests targeting a <bug_found> flaw — always in GENERATE
-    // A stated requirement the implementation contradicts is the point of the PR,
-    // so it sits in the same top tier as bug_caught. Being its own category, it is
-    // carved out separately in planRanker and takes the FIRST slot of the promotion
-    // bound SKYR-4275 sets — the code-review flaws promote into what is left, so a
-    // requirement conflict is never the finding that loses on severity.
-    requirement_conflict: PriorityTier.CRITICAL,
-    business_rule: PriorityTier.HIGH, // formula/business-logic bugs are high priority
-    security_boundary: PriorityTier.HIGH,
-    data_integrity: PriorityTier.HIGH,
-    breaking_change: PriorityTier.HIGH,
-    auth: PriorityTier.HIGH,
-    error_handling: PriorityTier.HIGH,
-    workflow: PriorityTier.MEDIUM,
-    data_validation: PriorityTier.MEDIUM,
-    crud: PriorityTier.LOW,
+/** What each category means, and whether it expects a failing test. The plan
+ *  tool renders its `category` description from this, so the agent reads these
+ *  sentences as it picks one. `expectsRed` is true only for the two naming a
+ *  specific defect: a wider set would fire verifier 4 on ordinary candidates. */
+export const CATEGORY_MEANINGS = {
+    new_endpoint: {
+        meaning: "set by the server's own drafts; do not assign it",
+        expectsRed: false,
+    },
+    bug_caught: {
+        meaning: "a flaw you found in the changed code; the test is expected to fail until it is fixed",
+        expectsRed: true,
+    },
+    requirement_conflict: {
+        meaning: "the code contradicts a requirement the PR states; expected to fail; reported as a critical or high issue",
+        expectsRed: true,
+    },
+    business_rule: {
+        meaning: "a formula, unique constraint or state machine the code is supposed to enforce",
+        expectsRed: false,
+    },
+    security_boundary: {
+        meaning: "auth, permissions, cross-user isolation or idempotency at a boundary",
+        expectsRed: false,
+    },
+    data_integrity: {
+        meaning: "cascade deletes, orphan prevention and referential integrity between resources",
+        expectsRed: false,
+    },
+    breaking_change: {
+        meaning: "a route rename, auth migration or response shape change that callers depend on",
+        expectsRed: false,
+    },
+    auth: {
+        meaning: "an authentication or authorization flow",
+        expectsRed: false,
+    },
+    error_handling: {
+        meaning: "a missing 404 or 422 guard on bad input",
+        expectsRed: false,
+    },
+    workflow: {
+        meaning: "a user journey across more than one resource",
+        expectsRed: false,
+    },
+    data_validation: {
+        meaning: "input validation and schema enforcement on a request",
+        expectsRed: false,
+    },
+    crud: {
+        meaning: "basic create, read, update or delete on one resource",
+        expectsRed: false,
+    },
 };
-/** Map internal-only categories to their external equivalent for tool submission. */
-export function externalCategory(cat) {
-    if (cat === "new_endpoint")
-        return "crud";
-    if (cat === "bug_caught")
-        return "business_rule";
-    // The stated requirement IS the business rule the test asserts — same landing
-    // spot as bug_caught, so a requirement-conflict test reads as a rule check in
-    // the customer-facing report rather than an unrecognised label.
-    if (cat === "requirement_conflict")
-        return "business_rule";
-    return cat;
+/** The category list as the plan tool shows it, one line each, table order. */
+export function categoryMenu() {
+    return SCENARIO_CATEGORIES.map((category) => {
+        const row = CATEGORY_MEANINGS[category];
+        return `- \`${category}\` — ${row.meaning}${row.expectsRed ? " (expects a failing test)" : ""}`;
+    }).join("\n");
 }
 /**
- * Categories whose scenarios target a specific identified defect — a code flaw
- * (`bug_caught`) or a stated requirement the code contradicts
- * (`requirement_conflict`). They survive external-test dedup: an existing test on
- * the same endpoint exercises the surface, not the flaw, so removing them would
- * drop the only test that fails on the defect.
+ * `category` is a free string whose schema description is an "e.g." list, so the
+ * agent picks the spelling: `Bug_Caught`, `bug-caught` and a trailing space each
+ * skipped verifier 4. Case, surrounding space and the `-`/`_`/space separator
+ * only — no alias list, since a category this misses is one nobody declared.
  */
-export const FLAW_TARGETING_CATEGORIES = [
-    "bug_caught",
-    "requirement_conflict",
-];
-/** Whether `category` targets a specific identified defect (see {@link FLAW_TARGETING_CATEGORIES}). */
-export function isFlawTargetingCategory(category) {
-    return category !== undefined && FLAW_TARGETING_CATEGORIES.includes(category);
+export function normalizeCategory(raw) {
+    return String(raw ?? "")
+        .trim()
+        .toLowerCase()
+        .replace(/[-\s]+/g, "_");
+}
+/** Whether a candidate's `category` names a test expected to fail on the current
+ *  code, in any spelling. Verifier 4 and the report's `expectedToFail` derivation
+ *  read this one answer: comparing the field two ways made `Bug_Caught`
+ *  bug-catching in one and ordinary in the other. */
+export function categoryExpectsRed(raw) {
+    const row = CATEGORY_MEANINGS[normalizeCategory(raw)];
+    return row?.expectsRed === true;
 }

package/build/types/TestbotPromptOptions.d.ts

@@ -18,10 +18,6 @@ export interface TestbotPromptOptions {
     prDescription: string;
     repositoryPath: string;
     baseBranch?: string;
-    maxRecommendations?: number;
-    maxGenerate?: number;
-    /** Reserved — accepted for API compat but not yet wired into the prompt. */
-    maxCritical?: number;
     prNumber?: number;
     userPrompt?: string;
     services?: Service[];