@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/playwright/blueprintDigestStore.js

@@ -0,0 +1,117 @@
+import { currentRunStateFile } from "../utils/AnalysisStateManager.js";
+import { logger } from "../utils/logger.js";
+import { digestFromBlueprintText } from "./blueprintDigest.js";
+/** The digests of this run's `browser_blueprint` captures. IN PROCESS, not in the
+ *  state file: the only reader shares a process with the browser tools, and writing
+ *  each digest would read-modify-write the state file once per capture. KEYED BY
+ *  THE RUN, one slot — a new key means the previous run is over. */
+let capturedRunStateFile;
+let captures = [];
+/** The url of the last capture SEEN, which is not the last one that produced a
+ *  digest — see the drop branch below. */
+let lastSeenUrl;
+/** Where the browser IS, as the server saw it — from a navigation the server
+ *  forwarded, or from the last capture that named a page. Kept beside
+ *  `lastSeenUrl` rather than reusing it: that one is deliberately cleared by an
+ *  unreadable payload so a delta cannot inherit a wrong page, and clearing it is
+ *  exactly wrong for a reader asking "what page are we on". */
+let browserUrl;
+/** A run that takes more captures than this has a browsing problem of its own;
+ *  the cap is here so a runaway loop cannot grow the process without bound. */
+export const MAX_STORED_CAPTURES = 200;
+/** Record one capture, or do nothing. NOTHING HERE MAY COST THE CAPTURE: the
+ *  payload the agent receives is untouched and every failure is swallowed with a
+ *  log line. Gated on `currentRunStateFile()`, not `resolveRunStatePath()`, because
+ *  this gates BEHAVIOUR and `RUNNER_TEMP` is set in this repository's own CI. */
+export function recordBlueprintCapture(result) {
+    try {
+        if (!result || result.isError)
+            return;
+        const runStateFile = currentRunStateFile();
+        if (runStateFile === undefined)
+            return;
+        if (runStateFile !== capturedRunStateFile) {
+            capturedRunStateFile = runStateFile;
+            captures = [];
+            lastSeenUrl = undefined;
+            browserUrl = undefined;
+        }
+        for (const block of result.content ?? []) {
+            if (captures.length >= MAX_STORED_CAPTURES)
+                return;
+            if (block?.type !== "text" || typeof block.text !== "string")
+                continue;
+            // The last url SEEN, not the last that produced a digest: after a dropped
+            // payload, a delta inherited the url before it and filed its elements
+            // under the wrong page.
+            const digest = digestFromBlueprintText(block.text, lastSeenUrl);
+            if (digest) {
+                captures.push(digest);
+                lastSeenUrl = digest.url;
+                if (digest.url)
+                    browserUrl = { url: digest.url, source: "blueprint" };
+            }
+            else {
+                // Forget the previous url rather than carry it forward: an unreadable
+                // payload says nothing about which page we are on, and a WRONG url files a
+                // later delta under it. No url only costs the delta its inheritance.
+                lastSeenUrl = undefined;
+            }
+        }
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        logger.warning(`Could not record a browser_blueprint digest — the capture itself is unaffected: ${detail}`);
+    }
+}
+/**
+ * Record where a `browser_navigate` took the browser.
+ *
+ * The server forwards the navigation, so it knows the destination without asking
+ * the agent — which is the point: a tool that exists to correct an agent's idea of
+ * which page it is on cannot take that page from the agent. Swallows everything,
+ * like the capture recorder: nothing here may cost a navigation.
+ */
+export function recordBrowserNavigation(url) {
+    try {
+        if (typeof url !== "string" || !url.trim())
+            return;
+        const runStateFile = currentRunStateFile();
+        if (runStateFile === undefined)
+            return;
+        if (runStateFile !== capturedRunStateFile) {
+            capturedRunStateFile = runStateFile;
+            captures = [];
+            lastSeenUrl = undefined;
+        }
+        browserUrl = { url: url.trim(), source: "currentUrl" };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        logger.warning(`Could not record a browser navigation url — the navigation itself is unaffected: ${detail}`);
+    }
+}
+/** The page the browser is on, and how the server came to know it: a navigation it
+ *  forwarded (`currentUrl`) or the last capture that named a page (`blueprint`). */
+export function lastKnownBrowserUrl() {
+    const runStateFile = currentRunStateFile();
+    if (runStateFile === undefined || runStateFile !== capturedRunStateFile)
+        return undefined;
+    return browserUrl ? { ...browserUrl } : undefined;
+}
+/** This run's digests, and no other run's — the same key the capture stored
+ *  them under. A copy: a reader that spliced the array would delete the run's
+ *  evidence. */
+export function capturedBlueprintDigests() {
+    const runStateFile = currentRunStateFile();
+    if (runStateFile === undefined || runStateFile !== capturedRunStateFile)
+        return [];
+    return [...captures];
+}
+/** For tests, and as a safety hook between runs. */
+export function clearBlueprintDigests() {
+    capturedRunStateFile = undefined;
+    captures = [];
+    lastSeenUrl = undefined;
+    browserUrl = undefined;
+}

package/build/playwright/registerPlaywrightTools.js

@@ -5,6 +5,8 @@
 import { z } from "zod";
 import { logger } from "../utils/logger.js";
 import { PlaywrightTraceService, } from "./PlaywrightTraceService.js";
+import { blueprintJsonSpan } from "./blueprintDigest.js";
+import { recordBlueprintCapture, recordBrowserNavigation } from "./blueprintDigestStore.js";
 let _service = null;
 export function getPlaywrightTraceService() {
     return _service;
@@ -14,6 +16,41 @@ export function getPlaywrightTraceService() {
  * shrinkBlueprintResult.
  */
 const BLUEPRINT_TOOL = "browser_blueprint";
+/**
+ * The one browser tool whose result carries a rule with it — see
+ * withAssertReminder.
+ */
+const NAVIGATE_TOOL = "browser_navigate";
+/**
+ * The line the agent reads the moment it has reached a page.
+ *
+ * The rule used to sit twice in the testbot start prompt, hundreds of lines
+ * before the page existed, and sb19 (run 33996699239) recorded a UI trace with
+ * ZERO browser_assert calls. A tool result is the one place the agent cannot
+ * read past.
+ */
+const ASSERT_REMINDER = "Assert at least one business outcome on this page with `browser_assert` before you leave it.";
+/**
+ * Append the assert rule to a successful browser_navigate result.
+ *
+ * The reminder rides the LAST text block, so it is the final thing in the
+ * payload whatever the fork wrote above it. A result carrying no text block at
+ * all gets one. An error result is returned untouched: the agent did not reach
+ * a page, so there is nothing to assert on.
+ */
+function withAssertReminder(result) {
+    if (result?.isError)
+        return result;
+    const content = result?.content ?? [];
+    const last = content.map((block) => block?.type).lastIndexOf("text");
+    if (last < 0) {
+        return { ...result, content: [...content, { type: "text", text: ASSERT_REMINDER }] };
+    }
+    return {
+        ...result,
+        content: content.map((block, i) => i === last && block?.type === "text" ? { ...block, text: `${block.text}\n\n${ASSERT_REMINDER}` } : block),
+    };
+}
 /**
  * Shrink a browser_blueprint result on the text channel it already arrives on.
  *
@@ -83,18 +120,13 @@ function dropNulls(value) {
  * that does not parse is returned as it arrived.
  */
 function shrinkBlueprintText(text) {
-    const start = text.indexOf("{");
-    if (start === -1)
+    // Where the JSON body starts and stops is `blueprintJsonSpan`'s answer, not a
+    // second reading of it here: the digest recorder reads the same body, and a
+    // drifted copy would silently deliver an unshrunk payload or an empty digest.
+    const span = blueprintJsonSpan(text);
+    if (!span)
         return text;
-    // The fork can append more sections after `### Result` — `### Page` whenever
-    // the title or URL changed since the last call, and `### Modal state`,
-    // `### Snapshot` or `### Events` when the page produced them. Only the Result
-    // section holds JSON, so the body has to stop at the next header; reading to
-    // the end of the string makes the parse throw and costs the whole saving.
-    // A `### ` at the start of a line cannot sit inside the JSON, because JSON
-    // escapes the newline that would have to precede it.
-    const nextSection = text.slice(start).search(/\n### /);
-    const end = nextSection === -1 ? text.length : start + nextSection;
+    const { start, end } = span;
     // The blank line the fork puts after a section belongs to the payload, not to
     // the JSON, so it is put back byte-for-byte rather than parsed away.
     const body = text.slice(start, end);
@@ -154,6 +186,7 @@ export async function registerPlaywrightTools(server, options) {
         'browser_wait_for',
         'browser_take_screenshot',
         'browser_assert',
+        'browser_assert_hidden',
         'browser_assert_api_request',
         'browser_assert_table_cell',
         'browser_mouse_action',
@@ -170,6 +203,7 @@ export async function registerPlaywrightTools(server, options) {
     for (const tool of filteredTools) {
         const zodSchema = jsonSchemaToZod(tool.inputSchema);
         const isBlueprint = tool.name === BLUEPRINT_TOOL;
+        const isNavigate = tool.name === NAVIGATE_TOOL;
         server.registerTool(tool.name, {
             description: tool.description || `Playwright tool: ${tool.name}`,
             inputSchema: zodSchema,
@@ -186,7 +220,21 @@ export async function registerPlaywrightTools(server, options) {
                 };
             }
             const result = await _service.callTool(tool.name, params);
-            return isBlueprint ? shrinkBlueprintResult(result) : result;
+            if (isNavigate) {
+                // The destination this server forwarded, so `skyramp_resolve_screen`
+                // can say where the browser actually is without asking the agent.
+                if (!result?.isError)
+                    recordBrowserNavigation(params.url);
+                return withAssertReminder(result);
+            }
+            if (!isBlueprint)
+                return result;
+            // Read for the digest BEFORE the shrink, so the recorder sees the
+            // payload the fork produced rather than one this file rewrote. It
+            // returns nothing and never throws — what the agent gets back is
+            // decided by the line below and by nothing here.
+            recordBlueprintCapture(result);
+            return shrinkBlueprintResult(result);
         });
     }
     logger.info(`Registered ${filteredTools.length} Playwright tools: ${filteredTools.map((t) => t.name).join(", ")}`);

package/build/playwright/traceRecordingPrompt.js

@@ -23,7 +23,7 @@ export function getTraceRecordingPromptText(opts) {
             : `- Do NOT run \`skyramp_modularization\` — skip modularization in CI.`;
     return `## Skyramp UI Test Recording
 
-${getPersonaPrefix()} For UI recording, every action must be grounded in what \`browser_snapshot\` returns. If an element is not visible in the snapshot, do not interact with it.
+${getPersonaPrefix()} For UI recording, every action must be grounded in what \`browser_snapshot\` returns. If an element is not visible in the snapshot, do not interact with it. **The usual reason an element is missing is that the browser is on a page that never renders it, and the cheapest moment to find that out is before the first click, not after the fifth.** \`skyramp_resolve_screen\` reads the repository's route table and this server's own browser session, and answers with the url to open, or tells you no route renders the file at all. Ask it first (step 1 below); ask it again the moment an expected element is missing. Do not reach for \`browser_evaluate\` to hunt an element the snapshot does not hold — a missing element is a wrong-page symptom, and \`browser_evaluate\` cannot tell you the page is wrong. **Locating an element is \`browser_snapshot\`'s job, and reading a route parameter off the page is too**; \`browser_evaluate\` is for state no snapshot can express, not for finding links, buttons or form fields.
 
 ### Required workflow
 
@@ -31,12 +31,13 @@ Before starting, output a \`<thinking>\` block that maps each step of the user's
 
 Then execute in strict order:
 
-1. **Navigate**: Call \`browser_navigate\` with the target URL. Always do this first, even if the browser appears to be on the correct page.
-2. **Snapshot**: Call \`browser_snapshot\` to get the current ARIA tree and element refs.
-3. **Interact**: Call the appropriate tool (\`browser_click\`, \`browser_type\`, \`browser_hover\`, etc.) using refs from the snapshot.
-4. **Repeat steps 2–3** for each user action until all steps are complete.
-5. **Export**: ${exportInstruction} Do NOT ask the user first — call it automatically.
-6. **Generate**: ${generateInstruction}
+1. **Resolve the screen**: when this test is about a frontend file the diff changed, call \`skyramp_resolve_screen\` with that file BEFORE \`browser_navigate\`, and take the target URL from its answer rather than from your own reading of the source. A route parameter it could not fill comes back in \`needs\` with the pattern left in the url (e.g. \`/secrets/$envSlug\`) — that url is not navigable as-is: read the real value off the app (open the parent page, follow a link, or take it from a list) and substitute it. Never invent one, and never navigate the pattern spelling literally. On \`unmounted\`, skip the browser entirely and say so.
+2. **Navigate**: Call \`browser_navigate\` with the target URL. Always do this before interacting, even if the browser appears to be on the correct page.
+3. **Snapshot**: Call \`browser_snapshot\` to get the current ARIA tree and element refs.
+4. **Interact**: Call the appropriate tool (\`browser_click\`, \`browser_type\`, \`browser_hover\`, etc.) using refs from the snapshot.
+5. **Repeat steps 3–4** for each user action until all steps are complete.
+6. **Export**: ${exportInstruction} Do NOT ask the user first — call it automatically.
+7. **Generate**: ${generateInstruction}
 
 ### Cross-tool rules
 

package/build/prompts/enhance-assertions/sharedAssertionRules.js

@@ -10,7 +10,7 @@ const SHARED_RULES = [
         subPoints: [
             "`is not None` / `not.toBeNull()` is only acceptable when the value is genuinely unknown — for server-generated timestamps or opaque IDs. This rule does not apply to computed fields.",
             "When a response field's value equals the value sent in the request body, path, or query, assert that exact value rather than a null-check — the sent value is known and reproducible.",
-            "Also applies to response-only fields the server always returns the same value for (`filename_download`, `content_type`, `size`, `url`, enum status after creation). Asserting only the id on a multi-key resource response is not sufficient.",
+            "Assert the exact value of a response-only field when the request this test sends determines it (`filename_download`, `content_type`, `size`, an enum status after creation). A value the app generates gets a format check when the test case depends on that value; leave the rest unasserted. Asserting only the id on a multi-key resource response is not sufficient.",
             "Range matchers like `toBeGreaterThanOrEqual(0)` and type-only checks like `typeof X === 'number'` are not acceptable for fields whose exact values are known.",
             "Assert the exact status code from the recorded trace or `expected_response_body` — for example, `201` for resource-creation endpoints. Action-style endpoints with verb path segments like `/run`, `/trigger`, `/execute`, `/deploy`, `/submit`, `/start`, `/stop`, or `/cancel` often use `200`, but assert the recorded or expected code. Permissive status matchers are never acceptable.",
         ],
@@ -41,7 +41,7 @@ expect(response.statusCode).toBe(201);`,
                 code: `expect(response.statusCode).toBe(404);
 expect(getValue(response, "errors.0.message")).toBe("Item not found");
 expect(getValue(response, "errors.0.extensions.code")).toBe("RECORD_NOT_FOUND");
-expect(getValue(response, "errors.1")).toBeUndefined();`,
+expect(getValue(response, "errors.1")).toBeNull();`,
             },
         ],
     },
@@ -92,12 +92,12 @@ expect(getValue(response, "data").length).toBeLessThanOrEqual(10);  // request s
                 language: "javascript",
                 code: `expect(getValue(response, "results").length).toBe(2);
 expect(getValue(response, "results.0.id")).toBe("prod_001");
-expect(getValue(response, "results.2")).toBeUndefined();`,
+expect(getValue(response, "results.2")).toBeNull();`,
             },
             {
                 language: "javascript",
                 code: `expect(getValue(response, "data").length).toBe(0);
-expect(getValue(response, "data.0")).toBeUndefined();`,
+expect(getValue(response, "data.0")).toBeNull();`,
             },
         ],
     },
@@ -207,7 +207,7 @@ Before editing the given file, you must output a \`<thinking>\` block. The aim o
 2. Classify each response first by its response status type and then assign the applicable assertion rules to the response.
    1. Success with body (2xx with a response body): all assertion rules below may apply — echo-back of request fields, computed response fields, array / items validation, and chained values across steps.
    2. Success with no body (200/202/204 with an empty body — e.g. logout/cancel/submit action endpoints): assert the status code only. Also apply chained-values rules if a follow-up step uses this response's ID.
-   3. Error response (4xx/5xx with a body): assert every error body field with its exact value plus array / items validation on the \`errors[]\` array (exact length + per-item fields + next index undefined). Status code alone is never sufficient when a body is present — for example, also assert \`errors.0.extensions.code == 'INVALID_PAYLOAD'\` and that \`errors.1\` is undefined.
+   3. Error response (4xx/5xx with a body): assert every error body field with its exact value plus array / items validation on the \`errors[]\` array (exact length + per-item fields + next index null). Status code alone is never sufficient when a body is present — for example, also assert \`errors.0.extensions.code == 'INVALID_PAYLOAD'\` and that \`errors.1\` is null.
 3. For each in-scope response, output one JSON object using the template below. The output is an array — one object per in-scope response.
    - \`step\`: the HTTP method, path, and response variable name for this request (e.g. \`POST /products → products_POST_response\`).
    - \`response_status\`: one of \`success\`, \`no_body\`, or \`error\` based on the classification in step 2.
@@ -233,14 +233,15 @@ ${scope}
 
 ### What not to do
 - Do not access response fields via dict syntax (\`response["field"]\`) or attribute access (\`response.field\`) — always use the SDK helper.
-- Do not assert \`not.toBeNull()\` / \`is not None\` on a field whose exact value is in the request body, prior response, or trace.
+- Do not assert \`not.toBeNull()\` / \`is not None\` on a field whose exact value is in the request body or a prior response.
+- Do not assert an exact value you learned only from a request you sent yourself while writing the test. Take the value from the diff, from what the request determines, or from a response this test received earlier.
 - Do not skip body assertions citing genuinely unpredictable fields — every assertable field still needs an assertion.
 - Do not use permissive status matchers (\`.toMatch(/^2/)\`, \`.toBeGreaterThanOrEqual(200)\`, \`checkStatusCode(response, '20x')\`).
-- Do not use shape-only or type-only assertions as a substitute for exact value validation. Forbidden patterns: \`Array.isArray(...)\`, \`typeof X === '...'\`, \`X instanceof Array\`, \`Object.keys(X).length > 0\`. When the recorded response contains actual values, assert them exactly.
+- Do not use shape-only or type-only assertions as a substitute for exact value validation. Forbidden patterns: \`Array.isArray(...)\`, \`typeof X === '...'\`, \`X instanceof Array\`, \`Object.keys(X).length > 0\`. When a field's value comes from one of those sources, assert it exactly.
 - Do not use shape-only, containment-only, range-only, or weak-length as the sole assertion on a populated array.
 - Do not swap between \`getValue\` and \`getResponseValue\` — keep whichever SDK helper the file already imports.
 - Do not restructure, reformat, reorder, or modify existing code; do not add comments or docstrings.
-- Do not change function signatures, imports, or variable names.
+- Do not change function signatures or variable names. You may add an import when a new assertion or a fix needs a helper — from \`@skyramp/skyramp\` or from the test's own helper module.
 - Do not remove existing assertions.
 
 ### Verification of Assertions

package/build/prompts/enhance-assertions/uiAssertionsPrompt.js

@@ -33,7 +33,7 @@ expect(trigger).to_be_focused()`,
             },
             {
                 title: "Selector constraints",
-                description: "Every assertion uses a selector already in the file. Never invent `data-testid`, role names, or classes.",
+                description: "Every assertion uses a selector already in the file. Never invent `data-testid`, role names, or classes. One exception: a `data-*` attribute + value listed in `uiContext.removedElements` (from the `skyramp_analyze_changes` output in your context) may be asserted `toBeHidden()` even though no element carries it any more — `getByTestId(value)` for `data-testid`, `page.locator('[data-cy=\"value\"]')` for any other attribute — see Removed element guard. A `-` line in the raw diff is not enough on its own: renames and moved elements also appear there.",
                 subPoints: [
                     "No tautological assertions — locating an element by text X, then asserting it contains X.",
                 ],
@@ -44,6 +44,28 @@ expect(trigger).to_be_focused()`,
                     },
                 ],
             },
+            {
+                title: "Removed element guard",
+                description: "When the PR deletes a rendered element (a `data-*` attribute + value listed in `uiContext.removedElements`) and the test visits the page that rendered it, assert `toBeHidden()` on it — `getByTestId(value)` when the attribute is `data-testid`, otherwise `page.locator('[<attribute>=\"<value>\"]')` (never `getByTestId` for `data-cy`/`data-qa`: Playwright resolves it against `data-testid` and the guard would pass vacuously). `toBeHidden` passes when the locator matches nothing or a single non-visible node (it is strict on multiple matches, like every locator assertion), which is the right contract for a removed element; do not substitute a `toBeVisible` on an unrelated element. Pair it with at least one positive assertion on a retained element of the same page so the test cannot pass on a blank or un-rendered page.",
+                subPoints: [
+                    "Anchor on the removed attribute+value or role+name, never on text or position — a text-based absence check breaks when unrelated siblings change.",
+                    "Do not add a guard for an element whose whole page or route was removed — that is maintenance of the tests that covered it, not a new assertion; a spec that opens a deleted route must be anchored on a surviving page first (a retained element asserted on a live page in the same spec) — a spec whose only visited page is the dead URL is not a valid guard.",
+                    "A renamed test id or accessible name (a removed `aria-label` included) is not a removed element: assert the element under its new identifier and never assert the retired identifier `toBeHidden()` — it passes today and turns into a false failure the day the name is reused.",
+                ],
+                examples: [
+                    {
+                        language: "javascript",
+                        code: `await expect(page.getByTestId('navbar-sessionid-row')).toBeHidden();
+await expect(page.locator('[data-cy="checkout-btn"]')).toBeHidden();
+await expect(page.getByTestId('navbar-products')).toHaveText('Products');`,
+                    },
+                    {
+                        language: "python",
+                        code: `expect(page.get_by_test_id('navbar-sessionid-row')).to_be_hidden()
+expect(page.get_by_test_id('navbar-products')).to_have_text('Products')`,
+                    },
+                ],
+            },
             {
                 title: "Page errors",
                 description: "Register `page.on('pageerror', ...)` before the first navigation and assert `expect(errors).toHaveLength(0)` at the end of the test.",
@@ -307,7 +329,7 @@ if (await existingSecret.isVisible().catch(() => false)) {
 
 ### Pre-Edit Assertion Analysis
 Before editing the given test file, you must output a \`<thinking>\` block. The aim of the \`<thinking>\` block is to analyze each in-scope item (action, selector, or captured network response) in the given test file and output a JSON array that ensures no assertion rule is overlooked. The JSON array should match the template below — every assertion category and every rule title under it must appear as a key, even when the value is \`[]\`.
-1. Selector inventory — list every selector already present in the generated test file (\`data-testid\`, role + name, text, label, etc.). New assertions may use only selectors from this list. Do not invent \`data-testid\` values, role names, or aria attributes. Also note captured network responses, repeated element patterns, exact rendered text/value/attribute from trace/source, and existing \`toBeVisible()\` assertions whose exact text is knowable.
+1. Selector inventory — list every selector already present in the generated test file (\`data-testid\`, role + name, text, label, etc.). New assertions may use only selectors from this list. An assertion the recorder dropped because it failed during recording may use the selector of the element named in that recording's blueprint capture. Do not invent \`data-testid\` values, role names, or aria attributes. Also note captured network responses, repeated element patterns, exact rendered text/value/attribute from trace/source, and existing \`toBeVisible()\` assertions whose exact text is knowable.
 2. Process — Replay → Identify → Fix or Add — walk through these three steps explicitly.
    a. Replay the scenario mentally. At each state-changing action (form submit, item add/edit/delete), ask: "What is the EXPECTED outcome based on the action performed?"
    b. Identify expectation mismatches. If the recorded trace shows a result that contradicts the action (e.g. removing 1 of 2 items but the page shows 3, submitting a form but getting a blank page, editing a field but the old value persists), that is an app bug the test should catch. List every mismatch you find.

package/build/prompts/promptAssets.d.ts

@@ -0,0 +1,20 @@
+/** Reader and markdown slicer for the prompt text shipped in `plugin/prompts/`.
+ *
+ *  The markdown is the single source of the instruction text: the prompts read it
+ *  back rather than carrying a second copy.
+ *
+ *  These files are NOT skills. Each one carries `{placeholder}` spans that only a
+ *  prompt render can fill — the repository path, a step number, the related-repo
+ *  count — so an agent that loaded one as a skill would read the braces. They sit
+ *  under `plugin/` rather than beside the code because `package.json` ships
+ *  `plugin/**` and nothing copies markdown out of `src/`. */
+/** Absolute path of the shipped `plugin/` directory. */
+export declare function pluginRoot(): string;
+export declare function readPromptAsset(relPath: string): string;
+/** One section INCLUDING its heading line. The caller that renders a whole
+ *  section wants the heading too, and retyping it in TypeScript let a heading
+ *  edit in the markdown leave the copy behind. */
+export declare function section(markdown: string, heading: string): string;
+/** Body of one section: the lines under `heading`, up to the next heading of
+ *  the same or a higher level. */
+export declare function sectionBody(markdown: string, heading: string): string;

package/build/prompts/promptAssets.js

@@ -0,0 +1,55 @@
+import { readFileSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+/** Reader and markdown slicer for the prompt text shipped in `plugin/prompts/`.
+ *
+ *  The markdown is the single source of the instruction text: the prompts read it
+ *  back rather than carrying a second copy.
+ *
+ *  These files are NOT skills. Each one carries `{placeholder}` spans that only a
+ *  prompt render can fill — the repository path, a step number, the related-repo
+ *  count — so an agent that loaded one as a skill would read the braces. They sit
+ *  under `plugin/` rather than beside the code because `package.json` ships
+ *  `plugin/**` and nothing copies markdown out of `src/`. */
+/** Absolute path of the shipped `plugin/` directory. */
+export function pluginRoot() {
+    // build/prompts/<file>.js or src/prompts/<file>.ts → package root → plugin/
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, "..", "..", "plugin");
+}
+export function readPromptAsset(relPath) {
+    return readFileSync(path.join(pluginRoot(), "prompts", relPath), "utf8");
+}
+function headingIndex(markdown, heading) {
+    // Anchored to line start so a heading quoted mid-paragraph cannot match.
+    if (markdown.startsWith(heading))
+        return 0;
+    const at = markdown.indexOf(`\n${heading}`);
+    return at === -1 ? -1 : at + 1;
+}
+/** Everything from `heading` to the end. Throws when the heading is absent: a
+ *  silent empty string would render a prompt with a section quietly missing. */
+function sliceFrom(markdown, heading) {
+    const at = headingIndex(markdown, heading);
+    if (at === -1)
+        throw new Error(`markdown section not found: ${heading}`);
+    return markdown.slice(at).trim();
+}
+/** One section INCLUDING its heading line. The caller that renders a whole
+ *  section wants the heading too, and retyping it in TypeScript let a heading
+ *  edit in the markdown leave the copy behind. */
+export function section(markdown, heading) {
+    const body = sectionBody(markdown, heading);
+    return body ? `${heading}\n\n${body}` : heading;
+}
+/** Body of one section: the lines under `heading`, up to the next heading of
+ *  the same or a higher level. */
+export function sectionBody(markdown, heading) {
+    const level = heading.match(/^#+/)?.[0].length ?? 0;
+    const lines = sliceFrom(markdown, heading).split("\n").slice(1);
+    const end = lines.findIndex((line) => {
+        const h = line.match(/^(#+)\s/);
+        return h !== null && h[1].length <= level;
+    });
+    return (end === -1 ? lines : lines.slice(0, end)).join("\n").trim();
+}

package/build/prompts/sut-setup/modes/dockerComposePrompt.js

@@ -2,10 +2,24 @@ import { buildContextBlock, buildInputsBody, buildCommonSutErrorsSection, buildL
 import { getPersonaPrefix } from "../../personas.js";
 import { PromptPlan } from "../../test-recommendation/promptPlan.js";
 // ── Step body builders ────────────────────────────────────────────────────────
+/**
+ * Step labels for the cross-references the bodies below make. Read from the
+ * plan's own declaration, not written out again: every one of these five
+ * references was off by one after `INIT_WORKSPACE` was added at the front.
+ * `_composePlan` is declared after the bodies, so this resolves on call.
+ */
+const STEP = (key) => {
+    const label = _composePlan.labels[key];
+    // Without this a renamed key renders "Step undefined" and nothing goes red.
+    if (label === undefined) {
+        throw new Error(`dockerComposePrompt: no step named "${key}"`);
+    }
+    return label;
+};
 function buildScanComposeBody(args) {
     const composeFile = args.sutSourceDockerComposeFile?.trim();
     if (composeFile) {
-        return `A specific compose file was provided: \`${composeFile}\`. Use it directly as the compose file — no scanning or generating. (Strategy in Step 2 will be REUSE with this file.)`;
+        return `A specific compose file was provided: \`${composeFile}\`. Use it directly as the compose file — no scanning or generating. (Strategy in Step ${STEP("DECIDE")} will be REUSE with this file.)`;
     }
     return `Search the repository for existing docker-compose files:
 - \`docker-compose.yml\`, \`docker-compose.yaml\`, \`compose.yml\`, \`compose.yaml\` at root
@@ -19,7 +33,7 @@ For each compose file found, determine if it is:
 function buildDecideStrategyBody(args) {
     const composeFile = args.sutSourceDockerComposeFile?.trim();
     if (composeFile) {
-        return `A specific compose file was provided in Step 1 (\`${composeFile}\`). Strategy is REUSE with this file. Confirm your decision:
+        return `A specific compose file was provided in Step ${STEP("SCAN")} (\`${composeFile}\`). Strategy is REUSE with this file. Confirm your decision:
 
 \`\`\`
 Decision: REUSE
@@ -27,7 +41,7 @@ Compose file: ${composeFile}
 Reason: provided by the user
 \`\`\``;
     }
-    return `Choose between reuse and generate based on what Step 1 found:
+    return `Choose between reuse and generate based on what Step ${STEP("SCAN")} found:
 - If an application docker-compose file was found → strategy is REUSE.
 - If only infrastructure-only compose files exist, or no compose files found → strategy is GENERATE.
 
@@ -70,7 +84,7 @@ function getReuseDockerComposeInstructions(composeFile) {
 4. Determine the teardown command: \`docker compose -f ${ref} down -v\`
 5. If the compose file defines admin credentials in environment variables, create \`.skyramp/sut/get-auth-token.sh\` using those credentials.
 
-These resolved commands are wired onto the \`skyramp/testbot\` action step using the input semantics from Step 3 above.`;
+These resolved commands are wired onto the \`skyramp/testbot\` action step using the input semantics from Step ${STEP("INPUTS")} above.`;
 }
 /** Generate instructions used when no reusable application compose file exists. */
 const GENERATE_DOCKER_COMPOSE_INSTRUCTIONS = `No usable application docker-compose was found. Generate one from scratch.
@@ -252,7 +266,7 @@ function buildApplyStrategyBody(args) {
         return `#### Reuse the provided Docker Compose file
 ${getReuseDockerComposeInstructions(composeFile)}`;
     }
-    return `Apply the strategy selected in Step 2:
+    return `Apply the strategy selected in Step ${STEP("DECIDE")}:
 
 #### If REUSE selected — Reuse existing Docker Compose
 ${getReuseDockerComposeInstructions()}

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

@@ -16,6 +16,8 @@ export declare function buildRenameStrategy(): string;
 export declare function buildFileRenameStrategy(): string;
 /** Strategy string for in-place UPDATE edits. */
 export declare function buildUpdateStrategy(): string;
+/** Strategy string for UPDATE entries that refresh visual-snapshot baselines (SKYR-4298). */
+export declare function buildRebaselineStrategy(): string;
 /** Strategy string for REGENERATE — call generation tool to overwrite the file. */
 export declare function buildRegenerateStrategy(): string;
 /** Strategy string for DELETE — remove obsolete test files whose covered endpoints/UI no longer exist. */
@@ -27,6 +29,8 @@ export declare function buildUpdateFileInstruction(params: {
     suggestedNewFile?: string;
     updateInstructions?: string;
     rationale?: string;
+    /** Visual baselines to refresh at final execution instead of editing (SKYR-4298). */
+    rebaselineSnapshots?: string[];
 }): string;
 /** Per-file instruction block for a single REGENERATE recommendation. */
 export declare function buildRegenerateFileInstruction(params: {

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

@@ -23,6 +23,10 @@ UPDATE is an in-place edit to the existing baseline file — do not create a new
 
 After editing, re-read each file to confirm the change landed, then call skyramp_enhance_assertions with each updated file path.`;
 }
+/** Strategy string for UPDATE entries that refresh visual-snapshot baselines (SKYR-4298). */
+export function buildRebaselineStrategy() {
+    return `Some update_context entries carry rebaseline_snapshots: the diff changed how the page or element those toHaveScreenshot() baselines capture looks, so the committed PNGs are stale and must be replaced, not the spec. For those baselines do NOT edit the toHaveScreenshot() call, do NOT raise maxDiffPixelRatio, do NOT remove the assertion, and do NOT touch the PNG yourself. Refresh them at the final execution: call skyramp_execute_test for that spec with rebaselineSnapshots set to exactly the listed filenames — SmartPlaywright re-captures each one and the new PNG lands beside the spec, where the Testbot PR shows it as an image diff for review. An entry with edit_required: false (no context) has nothing to edit: skip the Edit/re-read/skyramp_enhance_assertions steps for that file — the refresh at final execution is its whole maintenance. When you call skyramp_execute_test for the refresh, set testFile to the entry's spec_file (NOT its file, which is the page object for a POM-backed update). The execution result names which baselines were refreshed and which were not; report only the refreshed ones as refreshed. Never pass rebaselineSnapshots on the phase: "before" run — that run is the evidence that the baseline is stale.`;
+}
 /** Strategy string for REGENERATE — call generation tool to overwrite the file. */
 export function buildRegenerateStrategy() {
     return `For each file in regenerate_context, call the appropriate generation tool (skyramp_integration_test_generation or skyramp_contract_test_generation) with outputDir set to the file's directory and output set to the filename. The generation tool will overwrite the file. Do NOT use skyramp_ui_test_generation here — UI test regeneration requires a recorded trace (playwrightInput) and must be handled separately.`;
@@ -34,6 +38,7 @@ export function buildDeleteStrategy() {
 /** Per-file instruction block for a single UPDATE recommendation. */
 export function buildUpdateFileInstruction(params) {
     const { testFile, renames, suggestedNewFile, updateInstructions, rationale } = params;
+    const rebaselineSnapshots = params.rebaselineSnapshots ?? [];
     const renameTable = renames.length > 0 ? [
         `**Endpoint Rename Detected — Path Substitution Required:**\n`,
         `| Old Path | New Path | Method |`,
@@ -49,13 +54,20 @@ export function buildUpdateFileInstruction(params) {
     ].join("\n") : "";
     const changeBlock = updateInstructions
         ? `**What to change:**\n\n${updateInstructions}\n`
-        : renames.length === 0
+        : renames.length === 0 && rebaselineSnapshots.length === 0
             ? [
                 rationale ? `**Why:** ${rationale}\n` : "",
                 `**Action:** Update this test file based on the rationale above.\n`,
             ].filter(Boolean).join("\n")
             : "";
-    return `\n### ${testFile}\n\n${renameTable}${changeBlock}`;
+    const rebaselineBlock = rebaselineSnapshots.length > 0
+        ? [
+            `**Visual baselines to refresh:** ${rebaselineSnapshots.map((s) => `\`${s}\``).join(", ")}`,
+            rationale && !updateInstructions ? `**Why:** ${rationale}` : "",
+            `**Action:** Do not edit these \`toHaveScreenshot()\` calls, their \`maxDiffPixelRatio\`, or the PNGs. At the final execution, call \`skyramp_execute_test\` for this spec with \`rebaselineSnapshots: ${JSON.stringify(rebaselineSnapshots)}\` so SmartPlaywright re-captures them; the refreshed PNGs are delivered with the Testbot PR as image diffs.\n`,
+        ].filter(Boolean).join("\n")
+        : "";
+    return `\n### ${testFile}\n\n${renameTable}${changeBlock}${rebaselineBlock}`;
 }
 /** Per-file instruction block for a single REGENERATE recommendation. */
 export function buildRegenerateFileInstruction(params) {

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

@@ -11,17 +11,7 @@ export type UiDriftParams = {
     tests: Array<{
         testFile: string;
     }>;
-    changedFrontendFiles: string[];
     blueprintCaptured?: boolean;
-    /**
-     * Changed frontend files imported by 2+ production files, with their importer
-     * lists (server-computed). Drives the shared-component drift rule: a test may not
-     * be assigned IGNORE for one of these files until every importer has been read.
-     */
-    sharedComponents?: Array<{
-        file: string;
-        importers: string[];
-    }>;
 };
 /**
  * Build the drift analysis prompt.

package/build/prompts/test-maintenance/drift-analysis-prompt.js

@@ -110,17 +110,8 @@ export function buildDriftAnalysisPrompt(stateFile, apiTests, ui, repoPaths, ext
 
 **Signal:** ${signalNote}
 
-**Changed Frontend Files:**
-${ui.changedFrontendFiles.length > 0
-            ? ui.changedFrontendFiles.map(f => `- ${f}`).join("\n")
-            : "(none)"}
-${ui.sharedComponents && ui.sharedComponents.length > 0
-            ? `
-**Shared frontend components (imported by 2+ production files — cross-consumer blast radius):**
-${ui.sharedComponents.map(c => `- ${c.file} — ${c.importers.length} importer(s): ${c.importers.join(", ")}`).join("\n")}
-For any test whose changed target appears here, you MUST NOT assign IGNORE, and may assign UPDATE only after reading every listed importer (see "Component behavior changes").
-`
-            : ""}
+**Changed files:** read the diff. Your goal is to read the changes and come up with the list of affected test files in the existing repository. You MAY verify that a changed line is exercised by a test you selected by running it with \`skyramp_execute_test\`. Before you mark a test UPDATE, read the production files that import the changed component — grep for them yourself (see "Component behavior changes").
+
 **Instructions:**
 For each test in \`<tests_to_assess>\`, read it to determine its type, then apply the scope gate from the decision tree. Assign the appropriate action (DELETE, REGENERATE, UPDATE, VERIFY, IGNORE).
 </ui_analysis_context>