@skyramp/mcp 0.3.6 → 0.3.8

package/build/tools/submitReportTool.js

@@ -12,9 +12,12 @@ import { StateManager, runArtifactDir, getTestsRepoDir, } from "../utils/Analysi
 import { toolError, testFileMatches } from "../utils/utils.js";
 import { matchesApprovedPlan } from "../utils/planMatchKeys.js";
 import { isTestbotEnabled } from "../utils/featureFlags.js";
-import { findInvalidSourceCitations, findUnchangedFileClaims, listChangedFiles, listChangedFilesAcross, } from "../utils/reportVerification.js";
+import { findInvalidSourceCitations, findUnchangedFileClaims, listChangedFiles, listChangedFilesAcross, listChangedFilesAbs, } from "../utils/reportVerification.js";
+import { isPlanOnlyMode } from "../utils/planOnlyMode.js";
 import { getReportLanguage, isEnforcedReportLanguage, findLanguageViolations, findLanguageNearMisses, reportLanguageDisplayName, } from "../utils/reportLanguage.js";
-import { rederiveReuseOutcome, reuseChainSkipped, } from "./code-refactor/reuse-state.js";
+import { canonicalTestPath, findAssertionRecordByFileName, rederiveAssertionOutcome, } from "./code-refactor/assertion-state.js";
+import { rederiveReuseOutcome, reuseChainSkipped, samePath, } from "./code-refactor/reuse-state.js";
+import { retrofitGate, } from "./code-refactor/retrofit-state.js";
 // SKYR-3879 Path B: which testTypes the register-plan checkpoint gates. Mirrors
 // the generation tools actually wired to planGuard (batch-scenario/integration,
 // contract) — UI and E2E are on a separate blueprint-grounded pipeline and are
@@ -341,7 +344,8 @@ const issueFoundSchema = z
         .optional()
         .describe("Issue severity. critical = feature broken/unusable (e.g. page doesn't load, data corruption). " +
         "high = incorrect behavior (e.g. wrong calculation, stale data returned). " +
-        "medium = minor functional gap. low = cosmetic or informational."),
+        "medium = minor functional gap. low = cosmetic or informational. " +
+        "Floor: a requirement conflict — the PR title/description (or a requirements file it references) states a requirement the implemented behavior contradicts — is 'high' or 'critical', never 'medium' or below."),
     category: z
         .nativeEnum(IssueFoundCategory)
         .describe("Issue classification. bug = a product/code defect, e.g. found by a test or in the diff. " +
@@ -641,7 +645,26 @@ function computeReportMetrics(params) {
  * gets `chainSkipped: true` (SKYR-4220), the one claim that is exactly about the
  * reuse tool NOT having run. Applies to every test type: UI tests carry the POM
  * fields, API tests the shared-helper ones. */
-async function attachReuseOutcome(test, outcomes, handOffs) {
+/** Attach the assertion-enhancement summary to a report row.
+ *
+ *  How the row finds its record: records are keyed by the test file's full
+ *  path, but a report row only carries a file NAME. So the match compares
+ *  basenames, then checks testType and repository. When more than one record
+ *  still matches, the row gets NO summary — attaching the wrong spec's
+ *  numbers is worse than attaching none.
+ *
+ *  The numbers are server-derived and re-computed from the delivered file at
+ *  report time — the report narrative is LLM-authored, these numbers are not.
+ *  What a reader can conclude: `executionCount: 0` = generated but never
+ *  executed; no `assertions` field at all = the enhance tool never ran for
+ *  the file and it never executed. */
+async function attachAssertionOutcome(test, outcomes, checkouts) {
+    const record = findAssertionRecordByFileName(outcomes, test, checkouts);
+    if (!record)
+        return test;
+    return { ...test, assertions: await rederiveAssertionOutcome(record) };
+}
+async function attachReuseOutcome(test, outcomes, handOffs, retrofits = []) {
     // POM records describe browser specs; a basename collision with an API test's
     // fileName must not attach them there. A utils-path record is attachable anywhere.
     const record = outcomes?.[path.basename(test.fileName)];
@@ -652,6 +675,18 @@ async function attachReuseOutcome(test, outcomes, handOffs) {
         ? record
         : undefined;
     const derived = found ? await rederiveReuseOutcome(found) : undefined;
+    // Pre-existing generated tests this spec's reuse pass rewired (SKYR-4276 A4): the
+    // report names each with its recorded execution, so a reviewer sees that the
+    // module became a dependency of code they already owned — and that it still runs.
+    if (derived?.helpers && found?.testFilePath) {
+        const specPath = found.testFilePath;
+        const mine = retrofits.filter((r) => samePath(r.testFile, specPath));
+        if (mine.length > 0)
+            derived.helpers.retrofits = mine.map((r) => ({
+                file: path.basename(r.file),
+                ...(r.execution ? { execution: r.execution } : {}),
+            }));
+    }
     // The RAW record: a colliding record of any kind means reuse ran for this basename,
     // and the chain claim must not be made on the filtered view.
     const chainSkipped = await reuseChainSkipped(test.fileName, test.testType, record, handOffs);
@@ -1036,6 +1071,11 @@ export function registerSubmitReportTool(server) {
                 "Add a testMaintenanceDetails entry with the missing field(s), drafted from the execution output you already saw.");
             return errorResult;
         }
+        // SKYR-4276 A4: retrofits (pre-existing generated tests the reuse pass edited)
+        // that still stand in the working tree, resolved once here and attached to the
+        // rows below; an unexecuted one refuses the report (inside the SKYR-3883 block,
+        // which already enumerates the working tree).
+        let retrofitViews = [];
         // SKYR-3883: in a testbot run, refuse to ship a report that claims file work
         // the working tree doesn't reflect. The delivery step can only commit what the
         // agent actually created/edited, so a report claiming otherwise erodes trust
@@ -1071,6 +1111,9 @@ export function registerSubmitReportTool(server) {
                         newTests: dedupedNewTests,
                         verdicts: stateData.maintenanceVerdicts ?? [],
                         primaryRepository: fullState?.metadata?.repository,
+                        // SKYR-4250: captured at prompt-render time, since planOnly is a
+                        // prompt-only argument (mirrors the SKYR-4185 language capture).
+                        planOnly: isPlanOnlyMode(),
                     });
                     if (unbacked.length > 0) {
                         // Offer the attribution-correction path explicitly and show what DID change:
@@ -1096,6 +1139,17 @@ export function registerSubmitReportTool(server) {
                             `Files with actual working-tree changes:\n${changedList || "  (none)"}`);
                         return errorResult;
                     }
+                    const changedFilesAbs = await listChangedFilesAbs([
+                        repoRoot,
+                        getTestsRepoDir(),
+                        ...Object.values(fullState?.relatedRepos ?? {}).map((section) => section.repositoryPath),
+                    ]);
+                    const gate = await retrofitGate(stateData, changedFilesAbs, repoRoot);
+                    retrofitViews = gate.views;
+                    if (gate.refusal) {
+                        errorResult = toolError(gate.refusal);
+                        return errorResult;
+                    }
                 }
                 catch (err) {
                     // Never block a valid report because verification itself failed (path not a
@@ -1133,7 +1187,16 @@ export function registerSubmitReportTool(server) {
         // generation — downstream scoring scripts don't expect them and fail if
         // they encounter these string fields while traversing the object.
         // Also normalize each item's `repository` (blank → undefined).
-        const sanitizedNewTests = await Promise.all(dedupedNewTests.map(({ scenarioFile: _sf, traceFile: _tf, frontendTrace: _ft, ...rest }) => attachReuseOutcome(normalizeRepository(rest), stateData.reuseOutcomes, stateData.reuseHandOffs)));
+        // Checkout roots let the assertion-record matcher verify a candidate
+        // record actually lives in the row's repo (basename collisions across
+        // repos must not publish one spec's proof-of-work under another's name).
+        const assertionCheckouts = await stateManager
+            .listRepoCheckouts()
+            .catch(() => []);
+        const sanitizedNewTests = await Promise.all(dedupedNewTests.map(async ({ scenarioFile: _sf, traceFile: _tf, frontendTrace: _ft, ...rest }) => {
+            const row = await attachReuseOutcome(normalizeRepository(rest), stateData.reuseOutcomes, stateData.reuseHandOffs, retrofitViews);
+            return attachAssertionOutcome(row, stateData.assertionOutcomes ?? {}, assertionCheckouts);
+        }));
         const report = {
             businessCaseAnalysis: params.businessCaseAnalysis,
             newTestsCreated: sanitizedNewTests,
@@ -1142,10 +1205,25 @@ export function registerSubmitReportTool(server) {
             // an internal-only field, needed for matching but never meant to reach the report.
             // TODO(multi-repo maintenance): map(normalizeRepository) once testMaintenanceSchema
             // has a repository field (see TODO above).
-            testMaintenance: testMaintenance?.map(({ testFilePath, ...row }) => ({
-                ...row,
-                fileName: path.basename(testFilePath),
-            })),
+            testMaintenance: testMaintenance
+                ? await Promise.all(testMaintenance.map(async ({ testFilePath, ...row }) => {
+                    // Maintenance rows still carry the absolute path here, so the
+                    // assertion summary uses an EXACT canonical-path lookup — no
+                    // basename ambiguity. This is what carries the maintenance
+                    // honesty labels (nothing-to-verify vs verified) into the
+                    // report instead of leaving them as tool text the agent can
+                    // paraphrase.
+                    const record = stateData.assertionOutcomes?.[canonicalTestPath(testFilePath)];
+                    const assertions = record
+                        ? await rederiveAssertionOutcome(record)
+                        : undefined;
+                    return {
+                        ...row,
+                        fileName: path.basename(testFilePath),
+                        ...(assertions ? { assertions } : {}),
+                    };
+                }))
+                : undefined,
             // videoPath is filled from the run's execution records; testFilePath is the
             // match-only key and is stripped from the wire format, the same line drawn for
             // testMaintenance's own testFilePath above (downstream scoring scripts traverse

package/build/tools/test-management/registerTestPlanTool.d.ts

@@ -6,7 +6,7 @@ import { ChangedRoute } from "../../utils/changedRoutes.js";
 declare const registerCandidateSchema: z.ZodObject<{
     scenarioName: z.ZodString;
     description: z.ZodString;
-    category: z.ZodEnum<["new_endpoint", "bug_caught", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>;
+    category: z.ZodEnum<["new_endpoint", "bug_caught", "requirement_conflict", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>;
     priority: z.ZodEnum<["high", "medium", "low"]>;
     testType: z.ZodEffects<z.ZodNativeEnum<typeof TestType>, TestType, TestType>;
     steps: z.ZodArray<z.ZodObject<{
@@ -124,7 +124,7 @@ declare const registerCandidateSchema: z.ZodObject<{
     priority: "high" | "medium" | "low";
     testType: TestType;
     scenarioName: string;
-    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
     steps: {
         path: string;
         method: HttpMethod;
@@ -160,7 +160,7 @@ declare const registerCandidateSchema: z.ZodObject<{
     priority: "high" | "medium" | "low";
     testType: TestType;
     scenarioName: string;
-    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
     steps: {
         path: string;
         method: HttpMethod;

package/build/tools/test-management/registerTestPlanTool.js

@@ -12,7 +12,7 @@ import { CandidateSource, computeCandidateId, scenarioMergeKey, DiscriminatorKin
 import { selectPlan } from "../../recommendation/planRanker.js";
 import { resolveSubjectEndpoints } from "../../utils/subjectEndpoints.js";
 import { collectChangedRouteLines } from "../../utils/changedRoutes.js";
-import { reservedUISlots } from "../../recommendation/budgeters/shared.js";
+import { generateFloors } from "../../recommendation/budgeters/shared.js";
 import { inferScenarioType } from "../../recommendation/diversity.js";
 import { validateDiscriminator } from "../../recommendation/discriminators.js";
 import { isAttackSurfaceSecurityBoundary } from "../../prompts/test-recommendation/recommendationShared.js";
@@ -76,7 +76,7 @@ const discriminatorClaimSchema = z.object({
 const registerCandidateSchema = z.object({
     scenarioName: z.string().min(1).describe("Name for this test/scenario. Reused as the match key against the generation tool's scenarioName — keep it identical when you later call the generation tool."),
     description: z.string().min(1),
-    category: z.enum(SCENARIO_CATEGORIES).describe("Test category — drives ranking (never your own priority tag)."),
+    category: z.enum(SCENARIO_CATEGORIES).describe("Test category — drives ranking (never your own priority tag). `bug_caught` targets a `<bug_found>` flaw from code review. `requirement_conflict` asserts a requirement the PR title/description (or a requirements file it references) states and the implemented behavior contradicts — it fails on the current code by design. Both rank in the top tier but are carved out independently, so a requirement conflict never loses its slot to a code-review bug."),
     priority: z.enum(["high", "medium", "low"]).describe("Your own assessment — recorded, but ranking is derived from category, not this field."),
     testType: z.nativeEnum(TestType).refine((t) => PLAN_TEST_TYPES.has(t), {
         message: `testType must be one of ${[...PLAN_TEST_TYPES].join(", ")}`,
@@ -340,7 +340,26 @@ function renderGenerationDirective(plan) {
             (nonUICount > 0 ? ` Generate the ${tests(nonUICount)} of other types as well.` : ""),
     ];
 }
-function renderPlanText(plan, dropped) {
+/** SKYR-4292: the server cannot count the diff's changed behaviors, so an
+ *  under-budget plan is flagged (not rejected) with what a missing candidate looks
+ *  like. Wipro PR #24 registered 3 candidates against a 20-slot UI-only budget and
+ *  the tool answered "AUTHORITATIVE and FINAL" with no pushback. */
+function renderBudgetCheck(plan, maxTotal) {
+    const filled = plan.generate.length + plan.additional.length;
+    if (filled >= maxTotal)
+        return [];
+    return [
+        "",
+        `### Budget check: ${filled} of ${maxTotal} slots filled`,
+        "Every observable behavior this diff changes — each option value added, removed, renamed or reordered; each label, " +
+            "element, route, state, validation rule, computed value or style value (spacing, size, color, radius, font weight, " +
+            "class name) that renders differently; each removed element, asserted absent — needs a candidate above, however " +
+            "small the change. A change is covered only when an existing test asserts the changed value, not when a test merely " +
+            "reaches the component. If any changed behavior has no candidate, call skyramp_register_test_plan again with your " +
+            "full updated list. If the diff truly changes fewer behaviors than the budget, this plan stands as-is.",
+    ];
+}
+function renderPlanText(plan, dropped, maxTotal) {
     const lines = [];
     lines.push(`## Approved Test Plan (${plan.planId})`);
     lines.push("");
@@ -402,6 +421,7 @@ function renderPlanText(plan, dropped) {
     }
     lines.push("");
     lines.push(...renderGenerationDirective(plan));
+    lines.push(...renderBudgetCheck(plan, maxTotal));
     return lines.join("\n");
 }
 // ── Tool registration ───────────────────────────────────────────────────────
@@ -544,10 +564,11 @@ export function registerRegisterTestPlanTool(server) {
             // changes would silently plan zero UI tests (runs 32419025266,
             // 32431042133, 32431106864) — reject so the agent self-corrects in one
             // step, exactly like the empty-candidates rejection above.
-            if (reservedUISlots(budgetContext) > 0 &&
-                !allCandidates.some((c) => inferScenarioType(c.scenario) === TestType.UI)) {
-                errorResult = toolError("This run has frontend changes, so the plan reserves a UI slot — but no submitted or recovered " +
-                    "candidate has testType 'ui'. Resubmit your full candidate list including at least one UI candidate " +
+            const uiFloor = generateFloors(budgetContext).ui;
+            if (uiFloor > 0 && !allCandidates.some((c) => inferScenarioType(c.scenario) === TestType.UI)) {
+                errorResult = toolError(`This run has frontend changes, so the plan MUST include UI tests — at least ${uiFloor} of the ` +
+                    "GENERATE slots are held for them, and more are open to UI candidates on rank. No submitted or " +
+                    "recovered candidate has testType 'ui'. Resubmit your full candidate list including UI candidates " +
                     "for the changed frontend (see uiContext.changedFrontendFiles).");
                 return errorResult;
             }
@@ -576,7 +597,7 @@ export function registerRegisterTestPlanTool(server) {
                 return errorResult;
             }
             return {
-                content: [{ type: "text", text: renderPlanText(approvedPlan, result.dropped) }],
+                content: [{ type: "text", text: renderPlanText(approvedPlan, result.dropped, budgetContext.maxTotal) }],
             };
         }
         catch (error) {

package/build/types/AssertionOutcome.d.ts

@@ -0,0 +1,68 @@
+import type { TestType } from "./TestTypes.js";
+import type { EnhanceType } from "../prompts/enhance-assertions/sharedAssertionRules.js";
+/**
+ * Server-derived assertion-enhancement state. Lives in types/ (not beside
+ * assertion-state.ts) because AnalysisStateManager embeds AssertionRecord in
+ * the run state while assertion-state.ts imports AnalysisStateManager — same
+ * layering as ReuseOutcome.
+ */
+/** A verdict a verify pass can produce and store. */
+export type AssertionVerdict = "passed" | "failed";
+/** What the report can say about verification: the stored verdicts plus
+ *  "never-verified" — the report-time reading of a record that has no verdict
+ *  yet (instructions were handed out or the spec was executed, but no verify
+ *  pass ever ran). Only real verdicts are ever STORED (AssertionRecord);
+ *  "never-verified" exists only on the wire type below. */
+export type AssertionVerification = AssertionVerdict | "never-verified";
+/** One spec's enhancement record in the run state, keyed by the spec's
+ *  CANONICAL ABSOLUTE PATH (see assertion-state.ts `canonicalTestPath`).
+ *
+ *  Two creation paths, which is why the baseline group is optional while the
+ *  identity fields are not:
+ *  - instruction hand-out (recordAssertionBaseline) writes the full record;
+ *  - execution counting (recordAssertionExecution) creates a minimal record
+ *    for a spec that executed without ever being enhanced — identity fields
+ *    plus executionCount, no baseline group.
+ */
+export interface AssertionRecord {
+    /** Canonical path the record is for — kept in the record as a
+     *  defense-in-depth ownership check on reads and writes. */
+    testFilePath: string;
+    testType: TestType;
+    /** Times skyramp_execute_test ran this spec (recorded server-side after the
+     *  gates pass). Proof-of-work substrate: generated-but-never-executed and
+     *  executed-but-never-enhanced both become visible. */
+    executionCount: number;
+    /** Absent on execution-only records (no hand-out happened). */
+    enhanceType?: EnhanceType;
+    /** File hash + metrics at instruction hand-out time — the verify baseline.
+     *  Present as a group iff a hand-out happened. */
+    fileSha256?: string;
+    /** Copy of the generated file at hand-out time, saved under the run artifact
+     *  dir (never the repo, so it cannot leak into the customer commit). Lets the
+     *  agent diff/restore and gives evals a ground-truth pre-enhancement artifact. */
+    baselineFilePath?: string;
+    baselineCount?: number;
+    baselineStrength?: number;
+    baselineFingerprints?: string[];
+    issuedAt?: string;
+    /** Verdict of the last verify pass; absent until one runs. */
+    verification?: AssertionVerdict;
+    /** Reason from an accepted `assertions complete` decline marker. */
+    declinedReason?: string;
+}
+/** Report-facing proof-of-work summary attached to `newTestsCreated` rows —
+ *  the compact wire projection of AssertionRecord (which stays internal: it
+ *  carries fingerprints, hashes, and baseline paths the report must not).
+ *  Server-derived, re-derived from the delivered file at report time, never
+ *  supplied by the LLM. A missing `assertions` field on a row means no record
+ *  exists at all — the enhance tool never ran and the spec never executed. */
+export interface AssertionOutcome {
+    verification: AssertionVerification;
+    assertionsBaseline?: number;
+    assertionsFinal?: number;
+    strengthBaseline?: number;
+    strengthFinal?: number;
+    declinedReason?: string;
+    executionCount: number;
+}

package/build/types/AssertionOutcome.js

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

package/build/types/RepositoryAnalysis.d.ts

@@ -1119,7 +1119,7 @@ export declare const scenarioStepSchema: z.ZodObject<{
 export declare const draftedScenarioSchema: z.ZodObject<{
     scenarioName: z.ZodString;
     description: z.ZodString;
-    category: z.ZodEnum<["new_endpoint", "bug_caught", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>;
+    category: z.ZodEnum<["new_endpoint", "bug_caught", "requirement_conflict", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>;
     priority: z.ZodEnum<["high", "medium", "low"]>;
     steps: z.ZodArray<z.ZodObject<{
         order: z.ZodNumber;
@@ -1231,7 +1231,7 @@ export declare const draftedScenarioSchema: z.ZodObject<{
     description: string;
     priority: "high" | "medium" | "low";
     scenarioName: string;
-    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
     steps: {
         path: string;
         method: string;
@@ -1268,7 +1268,7 @@ export declare const draftedScenarioSchema: z.ZodObject<{
     description: string;
     priority: "high" | "medium" | "low";
     scenarioName: string;
-    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
     steps: {
         path: string;
         method: string;
@@ -1607,7 +1607,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         draftedScenarios: z.ZodArray<z.ZodObject<{
             scenarioName: z.ZodString;
             description: z.ZodString;
-            category: z.ZodEnum<["new_endpoint", "bug_caught", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>;
+            category: z.ZodEnum<["new_endpoint", "bug_caught", "requirement_conflict", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>;
             priority: z.ZodEnum<["high", "medium", "low"]>;
             steps: z.ZodArray<z.ZodObject<{
                 order: z.ZodNumber;
@@ -1719,7 +1719,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -1756,7 +1756,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -1799,7 +1799,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -1842,7 +1842,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -2743,7 +2743,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -2956,7 +2956,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;

package/build/types/ReuseOutcome.d.ts

@@ -1,3 +1,4 @@
+import type { TestExecutionStatus } from "./TestExecution.js";
 /**
  * The code-reuse observability shape carried in a TestbotReport — the wire contract
  * between this server and the consumers that render it (test-bot.git). It covers
@@ -85,6 +86,14 @@ export declare enum HelperVerificationOutcome {
     /** The test neither wrote nor imports a shared utils file. */
     NoUtilsFile = "no-utils-file"
 }
+/** A pre-existing Skyramp-generated test the reuse pass edited to import from the
+ *  shared utils file. `execution` is the recorded post-edit run; a retrofit without
+ *  one cannot be reported (skyramp_submit_report refuses). */
+export interface RetrofitOutcome {
+    /** BASENAME of the edited test. */
+    file: string;
+    execution?: TestExecutionStatus;
+}
 /** Shared-helper reuse for an API test, re-derived from the delivered files at report
  *  time — nothing here is read back from what the agent or the verify pass recorded.
  *  Absent altogether when no utils file exists for the test (the same omission rule
@@ -105,6 +114,13 @@ export interface HelperReuseOutcome {
      *  per method+path, status-code-only assertions, method+resource names — with
      *  documented declines (`reuse-verify: allow …`) counted as holding. */
     verification?: HelperVerificationOutcome;
+    /** Pre-existing generated tests this spec's reuse pass rewired onto the utils
+     *  file, each with its recorded execution. Omitted when none. */
+    retrofits?: RetrofitOutcome[];
+    /** Whether the delivered test plus the helpers it imports still hold every
+     *  assertion (and page-error guard) present when modularization was handed out.
+     *  Present only when that baseline exists. */
+    assertionsPreserved?: boolean;
 }
 /**
  * What lands in a report's `reuse` field for a generated test. Every member is

package/build/types/TestRecommendation.d.ts

@@ -12,7 +12,7 @@ export declare enum Novelty {
     EXISTING = "existing"
 }
 /** All categories including internal ones. */
-export declare const SCENARIO_CATEGORIES: readonly ["new_endpoint", "bug_caught", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"];
+export 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"];
@@ -21,3 +21,13 @@ export type TestCategory = typeof TEST_CATEGORIES[number];
 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;
+/**
+ * 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.
+ */
+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;

package/build/types/TestRecommendation.js

@@ -17,6 +17,14 @@ export var Novelty;
 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.
+    "requirement_conflict",
 ];
 /** External categories valid for tool submissions, ordered by priority. */
 const CATEGORIES = [
@@ -59,6 +67,12 @@ export const CATEGORY_PRIORITY = {
     // 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,
@@ -75,5 +89,25 @@ export function externalCategory(cat) {
         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;
 }
+/**
+ * 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.
+ */
+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);
+}

package/build/types/TestTypes.d.ts

@@ -246,3 +246,7 @@ export declare const codeRefactoringSchema: z.ZodObject<{
     codeReuse?: boolean | undefined;
     modularizeCode?: boolean | undefined;
 }>;
+/** Test types skyramp_enhance_assertions supports — single-sourced so the
+ *  tool's schema enum and generation-time baseline seeding cannot drift
+ *  (contract additionally requires provider mode at the seeding site). */
+export declare const ASSERTION_ENHANCEABLE_TEST_TYPES: readonly [TestType.INTEGRATION, TestType.CONTRACT, TestType.UI];

package/build/types/TestTypes.js

@@ -274,3 +274,11 @@ export const codeRefactoringSchema = z.object({
         .default(false)
         .describe("Whether to modularize the code"),
 });
+/** Test types skyramp_enhance_assertions supports — single-sourced so the
+ *  tool's schema enum and generation-time baseline seeding cannot drift
+ *  (contract additionally requires provider mode at the seeding site). */
+export const ASSERTION_ENHANCEABLE_TEST_TYPES = [
+    TestType.INTEGRATION,
+    TestType.CONTRACT,
+    TestType.UI,
+];

package/build/types/TestbotReport.d.ts

@@ -2,6 +2,7 @@ import type { DriftAction } from "./TestAnalysis.js";
 import type { TestExecutionStatus } from "./TestExecution.js";
 import type { HttpMethod, TestType } from "./TestTypes.js";
 import type { ReuseOutcome } from "./ReuseOutcome.js";
+import type { AssertionOutcome } from "./AssertionOutcome.js";
 /** Classification of an issuesFound entry. Bug is a product/code defect; the
  *  other values are tooling noise that the Testbot report renders in its
  *  Configuration Errors section instead of Issues Found. */
@@ -39,6 +40,14 @@ export interface TestbotReport {
          *  rest of this file mirrors Zod schemas by hand, which is why only this field
          *  is imported). Absent in reports from MCP versions predating it. */
         reuse?: ReuseOutcome;
+        /** Assertion-enhancement proof-of-work summary, present when
+         *  skyramp_enhance_assertions or skyramp_execute_test recorded state for
+         *  this test. Server-derived like `reuse` (imported for the same reason);
+         *  cross-checks the LLM-authored narrative against server-observed facts:
+         *  verification status, before/after assertion metrics, decline reason,
+         *  and how many times the test actually executed. Absent in reports from
+         *  MCP versions predating it. */
+        assertions?: AssertionOutcome;
     }[];
     /** Omitted when no existing tests were found (agent omits the field). */
     testMaintenance?: {
@@ -51,6 +60,10 @@ export interface TestbotReport {
         beforeDetails: string;
         afterStatus: TestExecutionStatus;
         afterDetails: string;
+        /** See newTestsCreated[].assertions — maintenance rows are matched by
+         *  exact canonical path, so this carries the maintenance honesty labels
+         *  (nothing-to-verify vs verified) into the report. */
+        assertions?: AssertionOutcome;
     }[];
     testResults: {
         testType: TestType;

package/build/types/index.d.ts

@@ -4,5 +4,5 @@ export { TestType, HttpMethod } from "./TestTypes.js";
 export type { TestbotReport } from "./TestbotReport.js";
 export { IssueFoundCategory } from "./TestbotReport.js";
 export { ReuseDeclinedBy, ReuseVerificationOutcome, HelperVerificationOutcome, } from "./ReuseOutcome.js";
-export type { ReuseOutcome, ReuseSkippedEntry, ReuseMissedEntry, HelperReuseOutcome, } from "./ReuseOutcome.js";
+export type { ReuseOutcome, ReuseSkippedEntry, ReuseMissedEntry, HelperReuseOutcome, RetrofitOutcome, } from "./ReuseOutcome.js";
 export type { RelatedRepository, TestbotPromptOptions, } from "./TestbotPromptOptions.js";