@skyramp/mcp 0.4.3 → 0.4.4-rc.2

package/build/prompts/startTraceCollectionPrompts.d.ts

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

package/build/prompts/startTraceCollectionPrompts.js

@@ -1,4 +1,3 @@
-// src/prompts/skyrampPrompt.ts
 import { z } from "zod";
 import { logger } from "../utils/logger.js";
 import { SESSION_STORAGE_FILENAME } from "../types/TestTypes.js";
@@ -6,12 +5,12 @@ export function registerStartTraceCollectionPrompt(mcpServer) {
     logger.info("registering start trace collection prompt");
     mcpServer.registerPrompt("skyramp_trace_prompt", {
         description: "Skyramp trace collection prompt",
-        argsSchema: {
+        argsSchema: z.object({
             outputDir: z
                 .string()
                 .optional()
                 .describe("Workspace directory where the session file will be saved. Pass the configured testDirectory from .skyramp/workspace.yml so the prompt can show the resolved save path instead of an abstract <outputDir> placeholder."),
-        },
+        }),
     }, (args) => {
         const outputDir = args?.outputDir;
         const sessionPathDisplay = outputDir

package/build/prompts/test-maintenance/driftAnalysisShared.js

@@ -55,6 +55,8 @@ ${opts.domainNotes}
 
 **When uncertain, use VERIFY not IGNORE:** If the diff touches code this test could exercise but you cannot confirm impact without reading more context, assign VERIFY — do not default to IGNORE.
 
+**If your rationale concludes the test is unaffected, assign IGNORE, not VERIFY.** Assign VERIFY only for a doubt that the code you read does not settle. A rule that forbids IGNORE still applies.
+
 **A stated requirement wins over the code.** Before you write a new value or refresh a screenshot in an existing test, compare it with what the pull request title, the description and any requirements file they name state. If the new value breaks a stated requirement, do not write it: keep that assertion on the requirement's value and make only the other edits. If no other edit remains, mark the test VERIFY. The test stays red; do not relax it. If the requirements file is unchanged and the description presents the new behaviour as intended, the file is out of date: update the test.
 
 **Pre-commit verification — confirm before finalizing UPDATE/REGENERATE/DELETE:**

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

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

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

@@ -12,11 +12,11 @@ export function registerRecommendTestsPrompt(server) {
             "Parameters for generation tools must derive from the repository analysis, enrichedScenarios, " +
             "or source code you read — no invented field names, no guessed URLs. Provide a stateFile path " +
             "from skyramp_analyze_changes.",
-        argsSchema: {
+        argsSchema: z.object({
             stateFile: z
                 .string()
                 .describe("State file path returned by skyramp_analyze_changes"),
-        },
+        }),
     }, async (args) => {
         const stateFile = args.stateFile;
         if (!stateFile) {

package/build/prompts/testbot/testbot-prompts.d.ts

@@ -1,4 +1,4 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
 import type { RelatedRepository, TestbotPromptOptions } from "../../types/TestbotPromptOptions.js";
 /** "After generation, complete these steps" list at the end of Task 2. Exported
  *  for `referenceIntegrity.test.ts`, which compares it against the ordinals the

package/build/prompts/testbot/testbot-prompts.js

@@ -332,12 +332,12 @@ export function getTestbotPrompt(opts) {
     let maintenanceBeforeExecStep;
     let verifyExternalStep;
     if (planOnly) {
-        verifyExternalStep = `   ${MAINTAIN.VERIFY_EXTERNAL}. Plan-only run: do not run the external tests you edited.`;
+        verifyExternalStep = `   ${MAINTAIN.VERIFY_EXTERNAL}. Plan-only run: do not run the external tests you edited or the VERIFY files.`;
         maintenanceBeforeExecStep = `   ${MAINTAIN.BASELINE}. Plan-only run: skip the pre-edit baseline execution — the application is not running. Record every maintenance verdict from static drift analysis alone; execution statuses simply remain unrecorded.`;
     }
     else {
-        verifyExternalStep = `   ${MAINTAIN.VERIFY_EXTERNAL}. Run the external tests you edited again. Do this step right after ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.APPLY_ACTIONS)}. It applies to each \`[external]\` test file that you edited in ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.APPLY_ACTIONS)} and that ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.BASELINE)} ran. Run each such file with \`skyramp_execute_test\`, \`phase: "after"\` and \`stateFile\`, and use the same command as in ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.BASELINE)}. Record each result as the file's \`afterStatus\`. The final execution excludes \`[external]\` files, so this step is where they get their after-run. If no file applies, say so in your report. If a file still fails, report it — do not run it again.`;
-        maintenanceBeforeExecStep = `   ${MAINTAIN.BASELINE}. Call \`skyramp_execute_test\` with \`phase: "before"\` and \`stateFile\` for every Skyramp test you will change, and for every test the repository owns that you will mark UPDATE: ${runTestCall()}. Run them one at a time, not in parallel. Run the command even when you expect the runner or a package to be missing: the failure output is what names what is missing, and a check you make before the run reaches no repair. On this run repair the environment only — install what is missing and run the file again — and never edit the test file, because the result of the file as the repository wrote it IS the baseline. This captures the pre-edit baseline — do not skip it even when you expect the test to fail. \`skyramp_actions\` refuses an UPDATE of the repository's own test until that test has this run. Nothing else owes one: a VERIFY changes no file, and a REGENERATE or a DELETE of the repository's own test is a recommendation you report rather than apply. Never pass \`rebaselineSnapshots\` on this run: a \`Screenshot comparison failed\` here is the evidence that a visual baseline is stale, and the refresh belongs to the final execution.`;
+        verifyExternalStep = `   ${MAINTAIN.VERIFY_EXTERNAL}. Run the external tests you edited again, and run each VERIFY file once. Do this step right after ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.APPLY_ACTIONS)}, before you plan new tests. It applies to each \`[external]\` test file that you edited in ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.APPLY_ACTIONS)} and that ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.BASELINE)} ran, and to each file you marked VERIFY, except a test in a related repository. Run each such file with \`skyramp_execute_test\`, \`phase: "after"\` and \`stateFile\`. For an edited file, use the same command as in ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.BASELINE)}. Record each result as the file's \`afterStatus\`. The final execution excludes \`[external]\` files and VERIFY files, so this step is where they get their after-run. If no file applies, say so in your report. If a file still fails, report it — do not run it again.`;
+        maintenanceBeforeExecStep = `   ${MAINTAIN.BASELINE}. Call \`skyramp_execute_test\` with \`phase: "before"\` and \`stateFile\` for every Skyramp test you will change, and for every test the repository owns that you will mark UPDATE: ${runTestCall()}. Run them one at a time, not in parallel. Run the command even when you expect the runner or a package to be missing: the failure output is what names what is missing, and a check you make before the run reaches no repair. On this run repair the environment only — install what is missing and run the file again — and never edit the test file, because the result of the file as the repository wrote it IS the baseline. This captures the pre-edit baseline — do not skip it even when you expect the test to fail. \`skyramp_actions\` refuses an UPDATE of the repository's own test until that test has this run. Nothing else owes one: a VERIFY changes no file, so its one run comes in ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.VERIFY_EXTERNAL)}, and a REGENERATE or a DELETE of the repository's own test is a recommendation you report rather than apply. Never pass \`rebaselineSnapshots\` on this run: a \`Screenshot comparison failed\` here is the evidence that a visual baseline is stale, and the refresh belongs to the final execution.`;
     }
     // For follow-up requests: emit the @skyramp-testbot header + guardrails, both stop-early.
     // For first-run prompts: emit the full Task 1 analysis + maintenance section.
@@ -477,7 +477,7 @@ ${userPrompt ? "Follow-up requests never reach this step — Task 1's guardrails
 **How to generate each type (for ADD):**
 - **Integration**: call \`skyramp_batch_scenario_test_generation\` with ALL steps in a single call (pass the \`steps\` array with method, path, requestBody, statusCode for each step). Then call \`skyramp_integration_test_generation\` with the returned scenario file${INTEGRATION_CODE_REUSE_GEN_CLAUSE}.
   **Reuse the steps you declared in your own plan** — pass them straight through. Read a source model only for a field your plan does not already carry.
-  Scenario JSON and test files go in ${testDirInstruction}
+  Test files go in ${testDirInstruction} Pass that same directory as \`outputDir\` to \`skyramp_batch_scenario_test_generation\`. The tool writes the scenario JSON outside the repository, so it is not committed. Do NOT copy it into the test directory.
   **Pipeline for speed**: Call ALL \`skyramp_batch_scenario_test_generation\` calls in one batch. When they return, call ALL \`skyramp_integration_test_generation\` calls in the next batch. Do NOT serialize per-scenario (batch→integration→batch→integration) — batch ALL scenarios first, then generate ALL integration tests.
 - **Contract**: call \`skyramp_contract_test_generation\` with \`endpointURL\`, \`method\`, and \`requestData\` for POST/PUT/PATCH.
   Pass \`apiSchema\` if an OpenAPI spec exists.
@@ -536,7 +536,7 @@ ${CONTRACT_MODE_GUIDANCE}
   - **Removal guard — when \`uiContext.removedElements\` is non-empty**: the server lists which elements this PR removed — each identified by a \`data-*\` attribute and value, with the file it came from (renames, moves and deleted files are excluded). Read that file and the route or page files that render it to decide which page each appeared on. Per PAGE: \`browser_navigate\` to it, wait for the app to render, then call \`browser_assert_hidden\` once per listed element using the target the list shows — \`testId: "<value>"\` when the attribute is \`data-testid\`, otherwise \`attribute: "<name>", value: "<value>"\` (e.g. \`attribute: "data-cy"\`); no \`ref\` — the element no longer exists, so no snapshot has one; the tool checks the live page and refuses to record on a blank or un-rendered page. Then at least one \`browser_assert\` on a RETAINED element of the same page verifying its text, value or state. If a UI trace for that page is already planned, record the guard assertions inside that trace; otherwise this is its own trace and spec, \`verify-removed-ui-<page-slug>\`. The generated test asserts \`toBeHidden()\` on \`getByTestId(...)\` or \`page.locator('[data-cy="..."]')\` accordingly. A removed element the server did not list still gets its test (the removal check requires it) — ground that one in the diff and prefix its \`reasoning\` with \`[removed-element diff-grounded]\`; prefix \`reasoning\` with \`[removed-element server-listed]\` when the element came from \`uiContext.removedElements\`. When the removed element lived inside a control the page has to open — an \`option\` of a \`select\`, an item of a closed menu — open that control before asserting: a closed control's contents are never visible, so a hidden assertion recorded against a shut one passes whether the element was removed or not. \`browser_assert_hidden\` stays the tool either way, because \`browser_assert\` needs a snapshot \`ref\` and a removed element has none; where the control cannot be opened, say so in \`reasoning\` so the assertion step turns that guard into a count. **Deleted routes or pages are deleted features, not removed elements**: test the removal through the link or entry point that survives. A trace may still open the retired URL — to assert the app's fallback there, or that the old page's elements are gone — after it has recorded a positive \`browser_assert\` on a surviving page; a trace whose only visited page is the dead URL has no positive companion and is not a guard spec.
   - **Renames are not removals — on every PR, whatever \`uiContext.removedElements\` holds**: when a test id, \`aria-label\` or other accessible name changed, assert the element by its new identifier and leave the retired identifier alone (no \`browser_assert_hidden\` on it). A rename PR removes nothing, so this rule applies when the removed list is empty.
   - **\`browser_visual_snapshot\` — for visual/appearance checks**: when the instruction asks to take a screenshot, capture a baseline, or verify how a page/element/region *looks* (not its text or value), call \`browser_visual_snapshot\` — it records a \`toHaveScreenshot()\` assertion so the generated test pixel-compares against a baseline on every run. **EXCEPTION:** when the look in question IS the change under test (a colour, class, attribute or element-order the diff makes), assert the property directly instead — see the next bullet. Do NOT use \`browser_take_screenshot\` for this: it captures a throwaway image that is dropped at export and never appears in the generated test (use it only to view the page yourself).
-  - **A colour, class or attribute change the diff makes**: record it directly — \`browser_assert\` \`type: css/class/attribute\` on the element that OWNS the property (the flex container for \`flex-direction\`, not its children). If that owner has no stable ref, say so in \`reasoning\` as a recording gap — do not assert the wrong element or screenshot it. Element order has no assert kind: use \`flex-direction\` when the diff flipped it, else a \`boundingBox()\` comparison at the enhance step. \`browser_visual_snapshot\` only for a look no property expresses (image, gradient, chart).
+  - **A colour, class or attribute change the diff makes**: record it directly — \`browser_assert\` \`type: css/class/attribute\` on the element that OWNS the property (the flex container for \`flex-direction\`, not its children). If that owner has no stable ref, say so in \`reasoning\` as a recording gap — do not assert the wrong element or screenshot it. \`browser_visual_snapshot\` only for a look no property expresses (image, gradient, chart).
   - **Wait for stable state before the second capture**: After performing an action that affects computed fields (filling a discount, submitting a form, adding an item), check the current page state before calling the second \`browser_blueprint\` (the capture after the action). If a computed field — total, price, count, derived text — still shows its initial empty or zero value (e.g. \`$0.00\`, \`0\`, \`Loading...\`, empty string), that means async data hasn't finished loading yet. Use \`browser_wait_for\` to wait up to 10 seconds for the field to update to a real value (for example, wait for the total to show a non-zero amount like \`$799.99\` instead of \`$0.00\`). Once the field shows a real value, THEN call the second \`browser_blueprint\` to capture stable state. If after 10 seconds the field still hasn't updated, skip the assertion on that field — don't capture and assert a value that hasn't loaded.
   If \`browser_navigate\` fails (app not running / connection refused), apply skip condition (a) above: leave the planned test in your plan, say in \`businessCaseAnalysis\` why it was not written, AND record the outage in \`issuesFound\`.
   Each trace costs browser tool calls, so record the ones your plan holds and no more. One trace that asserts a real outcome is worth more than three that assert a heading.
@@ -641,9 +641,9 @@ Do not make any changes other than the code-reuse refactoring (step ${POSTGEN.UI
 ${FINISH_CHECKS_BLOCK}
 
 **Execution timing:**
-- **beforeStatus** (maintained tests only): execute each maintained test file **once at the start** (before any edits) to capture \`beforeStatus\`. This is the only execution allowed before edits.
+- **beforeStatus** (maintained tests only): execute each maintained test file you will edit **once at the start** (before any edits) to capture \`beforeStatus\`. This is the only execution allowed before edits.
 - **Probe residue**: before the final execution, delete through the API the records your own probes and recordings created. Find each one by the id its create response returned, or by the exact value you typed for it during a recording. Do not delete anything else, and do not delete by a pattern. Do not use the database or a container. Do not add the deletion to a test. List in the report the records the API could not remove.
-- **Final execution**: Apart from ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.VERIFY_EXTERNAL)}, do NOT call \`skyramp_execute_test\` again until ALL maintenance edits AND ALL new test generation/enhancement are complete. Then execute every test file once — maintained files (for \`afterStatus\`) and new files together — passing \`stateFile\` and \`repository\` on every call: the attempt cap and the \`afterStatus\` the report reads both live in that file, and \`repository\` names the section the result lands in. Omitting \`stateFile\` does not skip the cap — the tool falls back to this run's own state file — but a wrong or missing \`repository\` fails the call. For a maintained spec whose \`skyramp_actions\` entry carried \`rebaseline_snapshots\`, pass that exact list as \`rebaselineSnapshots\` on this run and only this run. **Execute tests SEQUENTIALLY (one at a time)** — do NOT send multiple \`skyramp_execute_test\` calls in the same tool call batch, as concurrent execution overwhelms the stdio transport and causes MCP disconnection. Exclude tests marked \`[external]\`.
+- **Final execution**: Apart from ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.VERIFY_EXTERNAL)}, do NOT call \`skyramp_execute_test\` again until ALL maintenance edits AND ALL new test generation/enhancement are complete. Then execute every test file once — maintained files (for \`afterStatus\`) and new files together — passing \`stateFile\` and \`repository\` on every call: the attempt cap and the \`afterStatus\` the report reads both live in that file, and \`repository\` names the section the result lands in. Omitting \`stateFile\` does not skip the cap — the tool falls back to this run's own state file — but a wrong or missing \`repository\` fails the call. For a maintained spec whose \`skyramp_actions\` entry carried \`rebaseline_snapshots\`, pass that exact list as \`rebaselineSnapshots\` on this run and only this run. **Execute tests SEQUENTIALLY (one at a time)** — do NOT send multiple \`skyramp_execute_test\` calls in the same tool call batch, as concurrent execution overwhelms the stdio transport and causes MCP disconnection. Exclude tests marked \`[external]\` and VERIFY files: both ran in ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.VERIFY_EXTERNAL)}.
 - Only report test results for files you actually ran.
 
 ### Post-Execution: Assertion Alignment
@@ -708,7 +708,7 @@ export function registerTestbotPrompt(server) {
     logger.info("Registering testbot prompt");
     server.registerPrompt("skyramp_testbot", {
         description: "Run Skyramp Testbot to generate test recommendations and perform test maintenance for a pull request.",
-        argsSchema: {
+        argsSchema: z.object({
             prTitle: z.string().describe("Pull request title"),
             prDescription: z.string().describe("Pull request description/body"),
             repositoryPath: z
@@ -768,7 +768,7 @@ export function registerTestbotPrompt(server) {
                 // like the resource does, instead of rejecting the call.
                 .preprocess((v) => parseMaxFixAttemptsArg(v), z.number().int().min(1).max(10).optional())
                 .describe("Per-TEST-FILE cap on skyramp_execute_test calls in the final phase: the first run plus the fix-and-rerun iterations the agent may spend on an infrastructure failure for that one file (SKYR-4460). 1..10; falls back to SKYRAMP_MAX_FIX_ATTEMPTS, then 3."),
-        },
+        }),
     }, async (args) => {
         const services = await readWorkspaceServices(args.repositoryPath);
         let prompt = getTestbotPrompt({

package/build/recommendation/answers.d.ts

@@ -20,8 +20,8 @@ export declare function unknownAnswerObjections(objections: Objection[], acknowl
 export declare const NON_ANSWERABLE_PREFIX = "coverage:stateTest:";
 export declare function isNonAnswerable(objectionId: unknown): boolean;
 /** The objections a sentence alone does not close either. A change with no test
- *  needs the test, a value a page and API change refuses needs a UI test or a
- *  maintained spec that names it (the XR02 evidence is at `surfaceReject` in
+ *  needs the test, a value a page and API change accepts or refuses needs a UI step
+ *  that names it (the XR02 evidence is at `surfaceCase` and `surfaceReject` in
  *  `verifierContracts.ts`), and a defect with no test needs the test — a defect
  *  the code already had before this pull request included. Each closes only when the
  *  answer also names what stopped the test: a service that is not running, a
@@ -31,7 +31,7 @@ export declare function isNonAnswerable(objectionId: unknown): boolean;
  *  Prose closed every uncovered change, including changes nothing prevented a test
  *  from reaching. Runs 34423214322 and 34423217796 then lost three defects the
  *  baseline reported: each was listed and closed by a sentence. */
-export declare const BLOCKER_ONLY_PREFIXES: readonly ["coverage:change:", "coverage:surfaceReject:", "defects:untested:"];
+export declare const BLOCKER_ONLY_PREFIXES: readonly ["coverage:change:", "coverage:surfaceCase:", "coverage:surfaceReject:", "defects:untested:"];
 export declare function needsBlocker(objectionId: unknown): boolean;
 /** The objection raised below carries this prefix and the id it objects to. */
 export declare const REFUSED_ANSWER_PREFIX = "answers:refused:";

package/build/recommendation/answers.js

@@ -53,8 +53,8 @@ export function isNonAnswerable(objectionId) {
         objectionId.startsWith(NON_ANSWERABLE_PREFIX));
 }
 /** The objections a sentence alone does not close either. A change with no test
- *  needs the test, a value a page and API change refuses needs a UI test or a
- *  maintained spec that names it (the XR02 evidence is at `surfaceReject` in
+ *  needs the test, a value a page and API change accepts or refuses needs a UI step
+ *  that names it (the XR02 evidence is at `surfaceCase` and `surfaceReject` in
  *  `verifierContracts.ts`), and a defect with no test needs the test — a defect
  *  the code already had before this pull request included. Each closes only when the
  *  answer also names what stopped the test: a service that is not running, a
@@ -66,6 +66,7 @@ export function isNonAnswerable(objectionId) {
  *  baseline reported: each was listed and closed by a sentence. */
 export const BLOCKER_ONLY_PREFIXES = [
     "coverage:change:",
+    "coverage:surfaceCase:",
     "coverage:surfaceReject:",
     "defects:untested:",
 ];

package/build/recommendation/verifierContracts.d.ts

@@ -158,7 +158,7 @@ export declare const COVERAGE_CONTRACT: {
     readonly objections: {
         readonly change: {
             readonly message: "This declared change has no test in the plan.";
-            readonly suggestion: "Plan a test that exercises it. If an existing test already covers it and this run edits that test rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this change's id — maintenance is coverage, and a duplicate spec beside the one you edited is the mistake. If this run cannot write one, answer it and set `blocker` to what stopped the run — a service that is not running, a paired branch that no longer exists, the one credential the run holds. An answer with no blocker leaves this open: a change nothing prevented a test from reaching takes the test. Coverage per file is the basic minimum; coverage per change is what the plan is judged by, so a file covered by a shape test still leaves the change it makes untested.";
+            readonly suggestion: "Plan a test that exercises it. If an existing test already covers it and this run edits that test, or runs it unchanged as a VERIFY, rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this change's id — maintenance is coverage, and a duplicate spec beside the one you edited is the mistake. If this run cannot write one, answer it and set `blocker` to what stopped the run — a service that is not running, a paired branch that no longer exists, the one credential the run holds. An answer with no blocker leaves this open: a change nothing prevented a test from reaching takes the test. Coverage per file is the basic minimum; coverage per change is what the plan is judged by, so a file covered by a shape test still leaves the change it makes untested.";
         };
         readonly noChanges: {
             readonly message: "The plan declares no changes, so nothing says what the pull request must make different.";
@@ -190,11 +190,11 @@ export declare const COVERAGE_CONTRACT: {
         };
         readonly surfaceCase: {
             readonly message: "This change is on the page and the API, and no ui or e2e test that cites it chooses `{case}` on the page.";
-            readonly suggestion: "Add a ui or e2e test, or a step in one, that chooses that value on the page and names it in the step, as in `Principal radio`, or answer in one line why the page cannot send it.";
+            readonly suggestion: "Add a ui or e2e test, or a step in one, that chooses that value on the page and names it in the step. If this run cannot write the test, answer it and set `blocker` to what stopped the run; an answer with no blocker leaves this open.";
         };
         readonly surfaceReject: {
             readonly message: "This change is on the page and the API, and no ui or e2e test that cites it tries `{case}` on the page or checks that the page no longer offers it.";
-            readonly suggestion: "Add a ui or e2e test, or a step in one, that names that value in the step, as in `Intern radio absent`: try it and assert the page refuses it, or assert the page no longer offers it. If an existing UI spec already does this and this run edits it, declare it in `maintains` with its real path and name the value in `differsBy`. If this run cannot write the test, answer it and set `blocker` to what stopped the run; an answer with no blocker leaves this open.";
+            readonly suggestion: "Add a ui or e2e test, or a step in one, that names that value in the step: try it and assert the page refuses it, or assert the page no longer offers it. If this run cannot write the test, answer it and set `blocker` to what stopped the run; an answer with no blocker leaves this open.";
         };
     };
     readonly suggestion: "Which planned test tests each behaviour this change promises and each file it touches, and for one nothing covers, why does it need none?";
@@ -302,7 +302,7 @@ export declare const DEFECTS_CONTRACT: {
         };
         readonly untested: {
             readonly message: "This declared defect has no test in the plan.";
-            readonly suggestion: "Add a planned test that cites the defect in `defects` and sets `expected.outcome` to `fail`. A defect in a file this pull request touches gets the test whether or not this pull request introduced it. If an existing test already proves it and this run edits that test rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this defect's id — maintenance is proof, and a duplicate spec beside the one you edited is the mistake. If something stopped this run from writing the test, answer it and set `blocker` to what stopped it.";
+            readonly suggestion: "Add a planned test that cites the defect in `defects` and sets `expected.outcome` to `fail`. A defect in a file this pull request touches gets the test whether or not this pull request introduced it. If an existing test already proves it and this run edits that test, or runs it unchanged as a VERIFY, rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this defect's id — maintenance is proof, and a duplicate spec beside the one you edited is the mistake. If something stopped this run from writing the test, answer it and set `blocker` to what stopped it.";
         };
         readonly expectedPass: {
             readonly message: "Every test that cites this defect expects to pass, and a test that passes today proves nothing about a defect.";

package/build/recommendation/verifierContracts.js

@@ -149,7 +149,7 @@ export const COVERAGE_CONTRACT = {
     objections: {
         change: {
             message: "This declared change has no test in the plan.",
-            suggestion: "Plan a test that exercises it. If an existing test already covers it and this run edits that test rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this change's id — maintenance is coverage, and a duplicate spec beside the one you edited is the mistake. If this run cannot write one, answer it and set `blocker` to what stopped the run — a service that is not running, a paired branch that no longer exists, the one credential the run holds. An answer with no blocker leaves this open: a change nothing prevented a test from reaching takes the test. Coverage per file is the basic minimum; coverage per change is what the plan is judged by, so a file covered by a shape test still leaves the change it makes untested.",
+            suggestion: "Plan a test that exercises it. If an existing test already covers it and this run edits that test, or runs it unchanged as a VERIFY, rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this change's id — maintenance is coverage, and a duplicate spec beside the one you edited is the mistake. If this run cannot write one, answer it and set `blocker` to what stopped the run — a service that is not running, a paired branch that no longer exists, the one credential the run holds. An answer with no blocker leaves this open: a change nothing prevented a test from reaching takes the test. Coverage per file is the basic minimum; coverage per change is what the plan is judged by, so a file covered by a shape test still leaves the change it makes untested.",
         },
         noChanges: {
             message: "The plan declares no changes, so nothing says what the pull request must make different.",
@@ -203,17 +203,18 @@ export const COVERAGE_CONTRACT = {
             suggestion: "Add a test on that surface that cites this change, or answer in one line why that surface needs no test.",
         },
         // `{case}` is the rendered case, as in `level="Principal" (accept)`. SKYR-4529: a form offered Lead and Principal, and
-        // only an API test sent Principal.
+        // only an API test sent Principal. SKYR-4554: a later XR02 run closed this with "a third red for one defect adds
+        // nothing", and no UI test saved Principal.
         surfaceCase: {
             message: "This change is on the page and the API, and no ui or e2e test that cites it chooses `{case}` on the page.",
-            suggestion: "Add a ui or e2e test, or a step in one, that chooses that value on the page and names it in the step, as in `Principal radio`, or answer in one line why the page cannot send it.",
+            suggestion: "Add a ui or e2e test, or a step in one, that chooses that value on the page and names it in the step. If this run cannot write the test, answer it and set `blocker` to what stopped the run; an answer with no blocker leaves this open.",
         },
         // `{case}` is the rendered case, as in `level="Principal" (accept)`. The XR02 run removed Intern from a form; the page
         // objection closed by a sentence, and no generated test checked the option was
         // gone.
         surfaceReject: {
             message: "This change is on the page and the API, and no ui or e2e test that cites it tries `{case}` on the page or checks that the page no longer offers it.",
-            suggestion: "Add a ui or e2e test, or a step in one, that names that value in the step, as in `Intern radio absent`: try it and assert the page refuses it, or assert the page no longer offers it. If an existing UI spec already does this and this run edits it, declare it in `maintains` with its real path and name the value in `differsBy`. If this run cannot write the test, answer it and set `blocker` to what stopped the run; an answer with no blocker leaves this open.",
+            suggestion: "Add a ui or e2e test, or a step in one, that names that value in the step: try it and assert the page refuses it, or assert the page no longer offers it. If this run cannot write the test, answer it and set `blocker` to what stopped the run; an answer with no blocker leaves this open.",
         },
     },
     suggestion: "Which planned test tests each behaviour this change promises and each file it touches, and for one nothing covers, why does it need none?",
@@ -374,7 +375,7 @@ export const DEFECTS_CONTRACT = {
         },
         untested: {
             message: "This declared defect has no test in the plan.",
-            suggestion: "Add a planned test that cites the defect in `defects` and sets `expected.outcome` to `fail`. A defect in a file this pull request touches gets the test whether or not this pull request introduced it. If an existing test already proves it and this run edits that test rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this defect's id — maintenance is proof, and a duplicate spec beside the one you edited is the mistake. If something stopped this run from writing the test, answer it and set `blocker` to what stopped it.",
+            suggestion: "Add a planned test that cites the defect in `defects` and sets `expected.outcome` to `fail`. A defect in a file this pull request touches gets the test whether or not this pull request introduced it. If an existing test already proves it and this run edits that test, or runs it unchanged as a VERIFY, rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this defect's id — maintenance is proof, and a duplicate spec beside the one you edited is the mistake. If something stopped this run from writing the test, answer it and set `blocker` to what stopped it.",
         },
         expectedPass: {
             message: "Every test that cites this defect expects to pass, and a test that passes today proves nothing about a defect.",

package/build/recommendation/verifiers/coverage.js

@@ -744,27 +744,24 @@ const REFUSING_VERBS = new Set([
     "assert",
 ]);
 /** The text that can name a value on the page: the steps of the UI tests whose verb
- *  is in `verbs`, and the edit note of each maintained spec, which is prose with no
- *  verb to read. */
-function pageTexts(uiTests, maintained, verbs) {
-    return [
-        ...uiTests.flatMap((plannedTest) => plannedTest.scenario.steps
-            .filter((step) => verbs.has(normalizeStepMethod(step.method) ?? ""))
-            .flatMap((step) => [step.path, step.description ?? ""])),
-        ...maintained.map((entry) => entry.differsBy),
-    ];
+ *  is in `verbs`. A maintained spec's edit note is prose with no verb to read: an
+ *  XR02 note named Principal in "4 radios (incl. Principal) render" and Intern in
+ *  "switches from the removed Intern radio", and neither chose or refused it. */
+function pageTexts(uiTests, verbs) {
+    return uiTests.flatMap((plannedTest) => plannedTest.scenario.steps
+        .filter((step) => verbs.has(normalizeStepMethod(step.method) ?? ""))
+        .flatMap((step) => [step.path, step.description ?? ""]));
 }
 /** A change on the page AND the API needs each accepted value chosen on the page,
  *  and each refused value tried or shown absent there, not only sent by an API
  *  test. `surfaceObjections` passes the page once any UI test cites the change,
  *  whatever value it picks. A UI step is free text (`Senior radio`), so the check
  *  reads whether a page step of a citing ui or e2e test that chooses the value (or,
- *  for a refused one, asserts it), or the `differsBy` of a citing maintained spec,
- *  names the value.
+ *  for a refused one, asserts it) names the value.
  *
- *  A refused value takes a test, a resolving maintained spec, or a blocker, never a
- *  sentence: in the XR02 run the page objection for a removed option closed by
- *  prose, and only an existing spec checked that the option was gone. */
+ *  Either value takes a UI test step or a blocker, never a
+ *  sentence: in XR02 runs the page objection for a removed option and for an added
+ *  one each closed by prose, and no generated test checked that value on the page. */
 function surfaceCaseObjections(registration, ctx) {
     const objections = [];
     const seen = new Set();
@@ -777,15 +774,15 @@ function surfaceCaseObjections(registration, ctx) {
         const uiTests = registration.plannedTests.filter((plannedTest) => citesChange(plannedTest, id) &&
             pageTypes.has(plannedTest.scenario.testType.toLowerCase()));
         // A maintained spec counts only when its file resolves, the bar
-        // `citedBehaviors` sets: the refused half closes by no sentence, so a note on a
-        // file nobody can open must not close it either.
+        // `citedBehaviors` sets. It decides whether the values are checked, never
+        // whether one is met.
         const maintained = (registration.maintains ?? []).filter((entry) => entry.changes.some((cited) => cited.trim() === id) &&
             maintainedFileIsInItsRepository(entry, ctx));
         const citedAtAll = maintained.length > 0 ||
             registration.plannedTests.some((plannedTest) => citesChange(plannedTest, id));
         const texts = {
-            surfaceCase: pageTexts(uiTests, maintained, CHOOSING_VERBS),
-            surfaceReject: pageTexts(uiTests, maintained, REFUSING_VERBS),
+            surfaceCase: pageTexts(uiTests, CHOOSING_VERBS),
+            surfaceReject: pageTexts(uiTests, REFUSING_VERBS),
         };
         for (const testCase of change.testCases ?? []) {
             const kind = pageObjectionKind(testCase);
@@ -817,19 +814,22 @@ function surfaceCaseObjections(registration, ctx) {
             if (seen.has(key))
                 continue;
             seen.add(key);
-            const citers = [
-                ...uiTests.map((plannedTest) => plannedTest.plannedTestId),
-                ...maintained.map((entry) => entry.file),
-            ];
+            const citers = uiTests.map((plannedTest) => plannedTest.plannedTestId);
+            // A maintained spec has no steps to name the value, so say its note is not
+            // read rather than fault it for a step it cannot carry.
+            const notes = maintained.length > 0
+                ? ` The edit note of ${maintained.map((entry) => entry.file).join(", ")} is not read.`
+                : "";
             objections.push({
                 objectionId,
                 verifier: "coverage",
                 message: fillPlaceholders(COVERAGE_CONTRACT.objections[kind].message, {
                     case: rendered,
                 }),
-                evidence: citers.length === 0
-                    ? `No ui or e2e test or maintained spec cites ${id}.`
-                    : `${citers.join(", ")} cite ${id}; no step or maintained edit of theirs names ${word}.`,
+                evidence: (citers.length === 0
+                    ? `No ui or e2e test cites ${id}.`
+                    : `${citers.join(", ")} cite ${id}; no page step of theirs names ${word}.`) +
+                    notes,
                 suggestion: COVERAGE_CONTRACT.objections[kind].suggestion,
             });
         }

package/build/recommendation/verifiers/deliveredMatchesPlan.js

@@ -81,9 +81,9 @@ export function checkMaintenanceDelivered(plan, maintained) {
         objections.push({
             objectionId,
             verifier: "deliveredMatchesPlan",
-            message: "The plan says this existing test covers a change, and no maintenance row says it was edited.",
-            evidence: `plan maintains ${file}; the maintenance rows that changed a file name ${editedPaths.length > 0 ? editedPaths.join(", ") : "no file"}`,
-            suggestion: "The maintenance rows come from the triage, not from this call, so this is not a field to fill in here: make the edit on the file you claimed and let the maintenance step record it, or drop the entry from `maintains` and register the plan again — coverage counted the change because the plan said you were editing that test. If the test already covered the change and needed no edit, or the edit landed somewhere the rows do not name, say which as the answer.",
+            message: "The plan says this existing test covers a change, and no maintenance row says it was edited or run unchanged after the edits.",
+            evidence: `plan maintains ${file}; the maintenance rows that edited or ran a file name ${editedPaths.length > 0 ? editedPaths.join(", ") : "no file"}`,
+            suggestion: 'The maintenance rows come from the triage, not from this call, so this is not a field to fill in here: make the edit on the file you claimed and let the maintenance step record it, run a file you marked VERIFY with `skyramp_execute_test` and `phase: "after"`, or drop the entry from `maintains` and register the plan again — coverage counted the change because the plan said you were editing that test. If the test already covered the change and needed no edit, or the edit landed somewhere the rows do not name, say which as the answer.',
         });
     }
     return objections;

package/build/resources/analysisResources.d.ts

@@ -1,4 +1,4 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
 export declare const ANALYSIS_URI_PREFIX = "skyramp://analysis";
 /**
  * Register MCP Resources for analysis data access.

package/build/resources/analysisResources.js

@@ -1,5 +1,5 @@
 import * as fs from "fs";
-import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ResourceTemplate } from "@modelcontextprotocol/server";
 import { StateManager, getSessionFilePath, getRegisteredSessions, hasSessionData, getSessionData, normalizeRecommendationState, } from "../utils/AnalysisStateManager.js";
 import { logger } from "../utils/logger.js";
 import { AnalysisScope } from "../types/RepositoryAnalysis.js";

package/build/resources/progressResource.d.ts

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

package/build/resources/sutSetupResource.d.ts

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

package/build/resources/sutSetupResource.js

@@ -1,4 +1,4 @@
-import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ResourceTemplate } from "@modelcontextprotocol/server";
 import { logger } from "../utils/logger.js";
 import { resourceText } from "../utils/utils.js";
 import { AnalyticsService } from "../services/AnalyticsService.js";

package/build/resources/testbotResource.d.ts

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

package/build/resources/testbotResource.js

@@ -1,4 +1,4 @@
-import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ResourceTemplate } from "@modelcontextprotocol/server";
 import { logger } from "../utils/logger.js";
 import { AnalyticsService } from "../services/AnalyticsService.js";
 import { getTestbotPrompt, parseRelatedRepositories, } from "../prompts/testbot/testbot-prompts.js";

package/build/services/AnalyticsService.d.ts

@@ -1,4 +1,4 @@
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolResult } from "@modelcontextprotocol/server";
 export declare class AnalyticsService {
     /**
      * Only the fields named here reach the analytics backend. The tool's own

package/build/services/FleetExecutionService.d.ts

@@ -0,0 +1,130 @@
+import Docker from "dockerode";
+/**
+ * Where the mounted pieces live inside the executor, per container platform.
+ *
+ * The two images are the same shape on purpose -- /app/classes, /app/lib, the work
+ * directory -- so the only real differences are the path separator, the classpath
+ * separator and the shell. Keeping them in one table is what stops those three leaking
+ * into the rest of the file.
+ */
+export type ContainerPlatform = "linux" | "windows";
+interface Layout {
+    work: string;
+    certs: string;
+    /** The directory a branch-built library jar is mounted from. */
+    overrideDir: string;
+    /** The directory a credential pool outside the work directory is mounted from. */
+    poolDir: string;
+    imageClasses: string;
+    imageLibDir: string;
+    classpathSep: string;
+    /** Path separator inside the container. */
+    sep: string;
+}
+/**
+ * A path inside the container's work directory.
+ *
+ * Everything the run reads or writes lives under the mount, so this is the only place a
+ * container path is spelled out -- which is the point of the table above. Writing them
+ * longhand per platform put the separator back in the call sites it was meant to keep it
+ * out of.
+ */
+export declare function workPath(l: Layout, ...parts: string[]): string;
+export declare const LAYOUT: Record<ContainerPlatform, Layout>;
+/**
+ * Which platform the executor runs as. The Docker daemon that will run the container
+ * decides, not the image name: a released executor is one tag carrying both operating
+ * systems, and a daemon pulls and starts the image for its own.
+ *
+ * Asked of `docker`, the client that creates the container. The image check and pull go
+ * through the default client (docker.ts), which is the same daemon for every caller today:
+ * skyramp_execute_fleet passes no client. A daemon whose OS cannot be read fails the run
+ * here with that error as the cause: guessing linux on a Windows daemon would fail later
+ * with a mount or pull error that says nothing about why. An explicit platform must match
+ * the daemon; a mismatch would pull or start an image the engine cannot run.
+ */
+export declare function resolvePlatform(docker: Docker, explicit?: ContainerPlatform): Promise<ContainerPlatform>;
+export interface FleetExecutionOptions {
+    directory: string;
+    executorImage?: string;
+    platform?: ContainerPlatform;
+    entryClass?: string;
+    certsDir: string;
+    credentials?: string;
+    libraryJar?: string;
+    timeoutSec?: number;
+    env?: Record<string, string>;
+}
+export interface FleetExecutionResult {
+    passed: boolean;
+    executorImage: string;
+    platform: ContainerPlatform;
+    entryClass: string;
+    exitCode: number | null;
+    report: string;
+    output: string;
+    result?: unknown;
+    timedOut?: boolean;
+}
+/** A simple (unqualified) Java class name. */
+export declare const JAVA_CLASS_NAME: RegExp;
+/**
+ * The generated fleet manager: the one class in the directory that JUnit runs. The journey
+ * and the load class travel with it because they sit beside it, and they are compiled but
+ * never selected -- the journey is an input the fleet ships to the worker, and the load
+ * class only supplies the scenario.
+ */
+export declare function findEntryClass(directory: string, explicit?: string): string;
+/**
+ * A fleet file that pins its worker image is refused.
+ *
+ * The library picks the image from the commit it was built from, and that pairing is what a
+ * run through this tool exercises. A pinned image proves the image is good and hides the
+ * case where the library asks for one that does not exist.
+ */
+export declare function assertNoPinnedImage(fleetFile: string): void;
+/**
+ * The fleet reaches the worker it deployed at an address derived from the Docker daemon:
+ * the daemon's host for a remote engine, `localhost` for a local socket. Inside this
+ * container `localhost` is the container, so a local-socket fleet cannot reach the worker it
+ * just deployed and would hang until the timeout instead of failing.
+ */
+export declare function assertRemoteDaemon(fleetFile: string): void;
+/**
+ * The image the run happens in.
+ *
+ * The released executor is named by version, and a branch build of it carries no commit in
+ * its name the way the worker images do -- `RUNNER_IMAGE` defaults to a constant tag. So a
+ * caller testing an unreleased library either names its image here, or mounts the jar.
+ */
+export declare function resolveExecutorImage(explicit?: string): string;
+/** What the container is told to run: the argv, and the script it ends with. */
+export interface ContainerCommand {
+    /** Passed to Docker as `Cmd`. */
+    argv: string[];
+    /** The shell script argv ends with -- named, because its index differs per platform. */
+    script: string;
+}
+/** javac, then the JUnit console runner, both against the image's classpath. */
+export declare function buildCommand(entryClass: string, overrideJar: string | undefined, platform?: ContainerPlatform): ContainerCommand;
+/** The lines the fleet printed, which is what a reader wants out of the JUnit noise. */
+export declare function extractReport(output: string): string;
+/**
+ * Where a path inside the container lands on the host.
+ *
+ * The work directory is a bind mount of `directory`, so anything written under it appears
+ * there. Deriving the host path from the container path keeps the two ends of
+ * SKYRAMP_FLEET_REPORT_JSON as one fact: the value handed to the JVM is the value read
+ * back, rather than a second hardcoded guess that happens to agree.
+ *
+ * Returns undefined when the path is not under the work directory -- a caller may point
+ * the variable anywhere, and nothing outside the mount is visible from here.
+ */
+export declare function hostPathForContainerPath(directory: string, workDir: string, containerPath: string): string | undefined;
+/**
+ * Compiles and runs a generated fleet trio in the executor image, and returns what the run
+ * reported. The container is the same one every other generated test runs in; only the
+ * command and the mounts differ.
+ */
+export declare function executeFleet(options: FleetExecutionOptions, docker?: Docker): Promise<FleetExecutionResult>;
+export {};