@skyramp/mcp 0.5.0-rc.6 → 0.5.0-rc.8

package/build/prompts/modularization/ui-test-modularization.d.ts

@@ -1,3 +1,4 @@
+export declare const PICKED_OPTION_RULE = "ONE exception, because there the selector IS the value this scenario selects: the locator of the option or item the scenario picks from a list, when its test id or role name carries that option's label (`getByTestId(\"add-order-product-option-Adidas Running Shoes\")`, `getByRole(\"option\", { name: \"Adidas Running Shoes\" })`). That one argument becomes a parameter, and the call site passes the original string whole and byte-identical (`getByTestId(productOptionTestId)` called with `\"add-order-product-option-Adidas Running Shoes\"`; `getByRole(\"option\", { name: productName })` called with `\"Adidas Running Shoes\"`) \u2014 never rebuilt from a template or a shorter value. Every other selector, including the control that opens the list and the button that confirms the pick, stays verbatim.";
 export declare function getModularizationPrompt(filePath: string, testType: string, language?: string): string;
 /** Structured view of which steps render for the given inputs (for tests). */
 export declare function previewModularizationPlan(filePath: string, testType: string, language?: string): import("../test-recommendation/promptPlan.js").PlanPreview;

package/build/prompts/modularization/ui-test-modularization.js

@@ -151,7 +151,7 @@ ${p.utilsReuse
 **SHARED HELPER SHAPE:**
 - [ ] Every helper name is a canonical intent (\`openEditOrderForm\`, \`applyDiscount\`) with no scenario value or adjective in it
 - [ ] No helper contains a value assertion (${BROWSER_VALUE_ASSERTIONS}) — each sits in the test body, right after the helper call it verifies
-- [ ] Every selector inside a helper is byte-identical to the original test
+- [ ] Every selector inside a helper is byte-identical to the original test, except a picked option's locator argument, which is a parameter whose call-site argument is byte-identical
 - [ ] The assertion COUNT is unchanged: every \`expect(\` from the original is still in this file or inside a helper it calls, and the \`page.on('pageerror'...)\` guard and its final \`expect\` over the collected errors are still here — cross-cutting guards are never removed (the verify step counts both)
 `
     : ""}
@@ -184,10 +184,17 @@ If ANY answer is "no", fix it before submitting.
 // scenario's data — a `toHaveText("Total: $899.98")` inside a shared helper
 // fails every other caller. Selectors stay verbatim regardless (a selector is
 // not scenario data; parameterizing it invents a template the recorder never saw).
+// SKYR-4537: the one selector that is scenario data. An option picked from a list
+// is often located by its own label (test id or role name), so the value the
+// scenario selects lives only inside that locator. Kept verbatim in the helper it
+// pins every caller to this scenario's option, and the reuse scan can never match
+// another test that picks a different one. Passing the whole string (no template)
+// keeps the selector byte-identical at the call site.
+export const PICKED_OPTION_RULE = 'ONE exception, because there the selector IS the value this scenario selects: the locator of the option or item the scenario picks from a list, when its test id or role name carries that option\'s label (`getByTestId("add-order-product-option-Adidas Running Shoes")`, `getByRole("option", { name: "Adidas Running Shoes" })`). That one argument becomes a parameter, and the call site passes the original string whole and byte-identical (`getByTestId(productOptionTestId)` called with `"add-order-product-option-Adidas Running Shoes"`; `getByRole("option", { name: productName })` called with `"Adidas Running Shoes"`) — never rebuilt from a template or a shorter value. Every other selector, including the control that opens the list and the button that confirms the pick, stays verbatim.';
 function sharedHelperShape() {
     return `**SHARED HELPER SHAPE (this project consolidates helpers into a shared utils file):**
 - ${BROWSER_HELPERS.namingRule}
-- **PARAMETERS**: \`page\`, plus every value this scenario types or selects (${BROWSER_HELPERS.liftableLiterals}). Selectors are NEVER parameters — they stay verbatim inside the helper body.
+- **PARAMETERS**: \`page\`, plus every value this scenario types or selects (${BROWSER_HELPERS.liftableLiterals}). Selectors are NEVER parameters — they stay verbatim inside the helper body. ${PICKED_OPTION_RULE}
 - ${BROWSER_HELPERS.assertionRule} ${ASSERTION_BOUNDARY_RULE_EXTRACT}
 - Helpers are module-level named functions in this file; the test body becomes navigation + a sequence of helper calls + this scenario's assertions, in the original order.`;
 }

package/build/tools/code-refactor/codeReuseTool.js

@@ -469,8 +469,9 @@ export function registerCodeReuseTool(server) {
             return errorResult;
         }
         finally {
+            // No prompt: it carries the user's test code, and PushToolEvent
+            // forwards every field verbatim.
             AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
-                prompt: params.prompt,
                 testFile: params.testFile,
                 language: params.language,
                 framework: params.framework,

package/build/tools/code-refactor/utils-verify-gates.js

@@ -248,7 +248,7 @@ function inlineCallSitesAdvisory(r) {
         "",
         "",
         `ADVISORY — ${n} ${family.inlineSite.noun}${n === 1 ? "" : "s"} in other Skyramp-generated tests that a shared helper already ${family.inlineSite.already}:`,
-        ...r.inlineCallSites.map((c) => `- ${show(c.file, r)}:${lines(c)}${c.localHelper ? ` (in local helper ${c.localHelper})` : ""} · ${what(c)} · ${labelOf(c.utilsFile)}.${c.helper}`),
+        ...r.inlineCallSites.map((c) => `- ${show(c.file, r)}:${lines(c)}${c.localHelper ? ` (in local helper ${c.localHelper})` : ""} · ${what(c)} · ${labelOf(c.utilsFile)}.${c.helper}${c.kind === "sequence" && c.call ? ` · replace lines ${lines(c)} (the generated bindings in them included) with \`${c.call}\`` : ""}`),
         `${family.inlineSite.instruction} ${inlineSiteTail(family.inlineSite.localCopy)}`,
     ].join("\n");
 }

package/build/tools/fixErrorTool.js

@@ -58,8 +58,9 @@ export function registerFixErrorTool(server) {
             return errorResult;
         }
         finally {
+            // No prompt: it carries the user's test code, and PushToolEvent
+            // forwards every field verbatim.
             AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
-                prompt: params.prompt,
                 testFile: params.testFile,
             }).catch((err) => {
                 logger.warning("Analytics event failed", { error: String(err) });

package/build/utils/utils-verify/action-key.d.ts

@@ -37,7 +37,9 @@ export interface ActionStep {
      *  do not balance. A helper with one such step has no key; a spec's other steps
      *  are still read, so an unreadable step is a boundary no matched run crosses. */
     key?: string;
-    /** 1-based line of the action verb. */
+    /** 1-based line where the action's chain starts (`page` in a prettier-wrapped
+     *  `await page\n  .getByTestId(…)\n  .click()`); the verb's line when the chain
+     *  starts inside the previous action. */
     line: number;
     /** The source between the previous action's closing `)` (or the start of the
      *  body) and this action's chain: what stands between two consecutive actions.
@@ -47,6 +49,11 @@ export interface ActionStep {
     /** The source after this action's closing `)` up to the next action's chain, or
      *  to the end of the body for the last step — the next step's `gapBefore`. */
     gapAfter: string;
+    /** 1-based line of the action's closing `)`, where `gapAfter` starts. */
+    endLine: number;
+    /** The action's first argument as written (`""` when it has none): the value a
+     *  `fill` types, which the key leaves out. */
+    value: string;
 }
 /**
  * Every action in `body`, in order, each keyed as `actionKeyOf` keys it. Where
@@ -55,12 +62,62 @@ export interface ActionStep {
  * copy of a helper's sequence needs. Lines survive the Python and alias rewrites:
  * neither adds or removes a newline.
  */
-export declare function actionStepsOf(body: string, language?: UtilsLanguage): ActionStep[];
+export declare function actionStepsOf(body: string, language?: UtilsLanguage, 
+/** A helper's parameter names: a locator argument (or `name:` option) that is
+ *  one of them keys as the wildcard `paramSlot(name)` instead of failing. */
+params?: ReadonlySet<string>): ActionStep[];
 /** `click empty-cart-btn; fill qty` → `click \`empty-cart-btn\`; fill \`qty\`` — the
  *  key as the agent reads it, selectors quoted so a `#id` never reads as prose. */
 export declare function describeActionKey(key: string): string;
 /** Index of the `)` that closes the `(` at `open`, on a string-blanked copy. */
 export declare function matchingClose(structure: string, open: number): number;
+/** The text a parameter-fed locator argument keys as: a string no selector holds.
+ *  A key holding SLOT_MARK holds a wildcard. */
+export declare const SLOT_MARK = "\u0001";
+export declare function paramSlot(name: string): string;
+/** What an action's value is, as `resolveStepValue` reads it: one of the reading
+ *  helper's parameters, a literal, or another expression (kept as written). */
+export interface StepValue {
+    kind: "param" | "literal" | "expr";
+    text: string;
+    /** The zero-argument calls chained on a resolved `getValue(…)`, spaces dropped:
+     *  `.toString()` for a number the fill types. */
+    suffix?: string;
+}
+/**
+ * An action's value (`ActionStep.value`) as the sibling scan compares it: a bare
+ * parameter of the helper, a literal, or the generated `getValue(playwrightRequestN,
+ * "key")` — a dotted key read through nested objects, a chained `.toString()` kept
+ * as `suffix` — read through the binding that holds it (`requestBindingsOf`), to
+ * the parameter or literal stored under that key. Anything else is an expression,
+ * compared as written.
+ */
+export declare function resolveStepValue(raw: string, bindings: ReadonlyMap<string, string>, params?: ReadonlySet<string>): StepValue;
+/** The generator's `const playwrightRequestN: Record<…> = { … }` bindings in `text`,
+ *  by name, to the object literal as written. A name bound twice is left out. */
+export declare function requestBindingsOf(text: string): Map<string, string>;
+/** The normalised arguments of every `page.waitForResponse(…)` in `text`. */
+export declare function responseWaitsOf(text: string): string[];
+/** A use of the identifier `name`: not part of a longer name or a property access. */
+export declare function identifierUseRe(name: string, flags?: string): RegExp;
+/** A declared parameter's name (see paramName), or `undefined` for a rest or
+ *  destructured one: no single value a call or a wildcard can carry. */
+export declare function simpleParamName(raw: string): string | undefined;
+/** A browser helper's sequence as the sibling scan matches it (SKYR-4537). */
+export interface ActionPattern {
+    /** One key per step, as `actionStepKeys` keys it, except that a locator argument
+     *  fed by a parameter is the wildcard `paramSlot(name)`. */
+    steps: string[];
+    /** Each step's value, read through the helper's own request bindings. */
+    values: StepValue[];
+    /** The helper's `waitForResponse` arguments (see responseWaitsOf). */
+    responseWaits: string[];
+    /** The parameters the body reads: one a call leaves out changes what it does. */
+    usedParams: string[];
+}
+/** The helper's ActionPattern, or `undefined` when a step stays unreadable with
+ *  its parameters as wildcards. `params` are the declared parameters as written. */
+export declare function actionPatternOf(body: string, language: UtilsLanguage, params: readonly string[]): ActionPattern | undefined;
 /** Whitespace and braces dropped outside string literals, `'` normalised to `"` —
  *  the spelling a locator chain has inside a key. */
 export declare function normalizeChain(text: string): string;

package/build/utils/utils-verify/action-key.js

@@ -1,3 +1,5 @@
+import { escapeRegExp } from "../regex.js";
+import { paramName } from "./parse.js";
 /**
  * The Playwright actions a browser helper can perform — the closed vocabulary that
  * gives the action VERB, where an API helper's method comes from the request. A
@@ -52,7 +54,10 @@ export function actionStepKeys(steps) {
  * copy of a helper's sequence needs. Lines survive the Python and alias rewrites:
  * neither adds or removes a newline.
  */
-export function actionStepsOf(body, language = "typescript") {
+export function actionStepsOf(body, language = "typescript", 
+/** A helper's parameter names: a locator argument (or `name:` option) that is
+ *  one of them keys as the wildcard `paramSlot(name)` instead of failing. */
+params) {
     const src = resolveLocatorAliases(language === "python" ? toPlaywrightJs(body) : body);
     // Structure is read on a copy with string CONTENTS blanked (same length), so a
     // `)` or `.` inside a literal never ends a chain, and a `.click(` written inside
@@ -63,7 +68,7 @@ export function actionStepsOf(body, language = "typescript") {
     for (const m of structure.matchAll(ACTION_RE)) {
         const verb = m[1];
         const dot = m.index;
-        const line = src.slice(0, dot).split("\n").length;
+        const verbLine = src.slice(0, dot).split("\n").length;
         const argsOpen = dot + m[0].length - 1;
         const argsClose = matchingClose(structure, argsOpen);
         const chainStart = chainStartBefore(structure, dot);
@@ -71,16 +76,24 @@ export function actionStepsOf(body, language = "typescript") {
         // An action inside another action's arguments: its chain starts before the
         // previous action ended, so there is no gap to judge and no run to join.
         if (argsClose === -1 || chainStart < prevEnd) {
-            steps.push({ line, gapBefore, gapAfter: "" });
+            steps.push({
+                line: verbLine,
+                gapBefore,
+                gapAfter: "",
+                endLine: verbLine,
+                value: "",
+            });
             prevEnd = argsOpen + 1;
             continue;
         }
         prevEnd = argsClose + 1;
         steps.push({
-            line,
+            line: src.slice(0, chainStart).split("\n").length,
             gapBefore,
             gapAfter: "",
-            key: stepKey(verb, src, structure, chainStart, dot, argsOpen, argsClose),
+            endLine: verbLine + (src.slice(dot, argsClose).match(/\n/g)?.length ?? 0),
+            value: firstArgument(structure, src, argsOpen + 1, argsClose),
+            key: stepKey(verb, src, structure, chainStart, dot, argsOpen, argsClose, params),
         });
     }
     for (let i = 0; i < steps.length; i++)
@@ -89,8 +102,10 @@ export function actionStepsOf(body, language = "typescript") {
     return steps;
 }
 /** The key of one action, or `undefined` when its locator or target is unreadable. */
-function stepKey(verb, src, structure, chainStart, dot, argsOpen, argsClose) {
+function stepKey(verb, src, structure, chainStart, dot, argsOpen, argsClose, params) {
     let chain = src.slice(chainStart, dot);
+    if (params?.size)
+        chain = chain.replace(PARAM_LOCATOR_RE, (m, head, id) => params.has(id) ? `${head}"${paramSlot(id)}"` : m);
     const args = src.slice(argsOpen + 1, argsClose);
     let target = "";
     if (!/\(/.test(structure.slice(chainStart, dot))) {
@@ -219,6 +234,147 @@ function hasDynamicSelector(text) {
                 return true;
     return false;
 }
+/** A locator argument or `name:` option that is a bare identifier. */
+const PARAM_LOCATOR_RE = /(\.(?:getBy\w+|locator|frameLocator)\s*\(\s*|\bname\s*:\s*)([A-Za-z_$][\w$]*)(?=\s*[,)}])/g;
+/** The text a parameter-fed locator argument keys as: a string no selector holds.
+ *  A key holding SLOT_MARK holds a wildcard. */
+export const SLOT_MARK = "\u0001";
+export function paramSlot(name) {
+    return `${SLOT_MARK}${name}${SLOT_MARK}`;
+}
+const LITERAL_RE = /^(?:"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|-?\d+(?:\.\d+)?)$/;
+const GET_VALUE_RE = /^getValue\s*\(\s*([A-Za-z_$][\w$]*)\s*,\s*(["'])([\w$ .-]*)\2\s*\)((?:\s*\.\s*[A-Za-z_$][\w$]*\s*\(\s*\))*)$/;
+/**
+ * An action's value (`ActionStep.value`) as the sibling scan compares it: a bare
+ * parameter of the helper, a literal, or the generated `getValue(playwrightRequestN,
+ * "key")` — a dotted key read through nested objects, a chained `.toString()` kept
+ * as `suffix` — read through the binding that holds it (`requestBindingsOf`), to
+ * the parameter or literal stored under that key. Anything else is an expression,
+ * compared as written.
+ */
+export function resolveStepValue(raw, bindings, params = new Set()) {
+    const text = raw.trim();
+    if (params.has(text))
+        return { kind: "param", text };
+    if (LITERAL_RE.test(text))
+        return { kind: "literal", text };
+    const get = GET_VALUE_RE.exec(text);
+    const object = get ? bindings.get(get[1]) : undefined;
+    if (get && object !== undefined) {
+        let field = fieldOf(object, get[3]);
+        if (field === undefined)
+            for (const [i, part] of get[3].split(".").entries())
+                field = fieldOf(i === 0 ? object : (field ?? ""), part);
+        if (field !== undefined)
+            return {
+                ...resolveStepValue(field, new Map(), params),
+                suffix: get[4].replace(/\s+/g, ""),
+            };
+    }
+    return { kind: "expr", text };
+}
+/** The value written under the TOP-LEVEL `key` of an object literal, or undefined. */
+function fieldOf(object, key) {
+    const text = object.trim();
+    if (!text.startsWith("{") || !text.endsWith("}"))
+        return undefined;
+    const structure = blankStringContents(text);
+    let depth = 0;
+    let from = 1;
+    for (let i = 1; i < text.length; i++) {
+        const ch = structure[i];
+        if ("([{".includes(ch))
+            depth++;
+        else if (depth > 0 && ")]}".includes(ch))
+            depth--;
+        else if (depth === 0 && (ch === "," || i === text.length - 1)) {
+            const colon = structure.indexOf(":", from);
+            if (colon !== -1 && colon < i) {
+                const name = text
+                    .slice(from, colon)
+                    .trim()
+                    .replace(/^(["'])(.*)\1$/, "$2");
+                if (name === key)
+                    return text.slice(colon + 1, i).trim();
+            }
+            from = i + 1;
+        }
+    }
+    return undefined;
+}
+/** The generator's `const playwrightRequestN: Record<…> = { … }` bindings in `text`,
+ *  by name, to the object literal as written. A name bound twice is left out. */
+export function requestBindingsOf(text) {
+    const structure = blankStringContents(text);
+    const out = new Map();
+    const twice = new Set();
+    for (const m of structure.matchAll(/\bconst\s+(playwrightRequest\d+)\s*(?::\s*Record\s*<[^>]*>)?\s*=\s*\{/g)) {
+        const open = m.index + m[0].length - 1;
+        const close = matchingClose(structure, open);
+        if (close === -1 || out.has(m[1]))
+            twice.add(m[1]);
+        else
+            out.set(m[1], text.slice(open, close + 1));
+    }
+    for (const name of twice)
+        out.delete(name);
+    return out;
+}
+/** The normalised arguments of every `page.waitForResponse(…)` in `text`. */
+export function responseWaitsOf(text) {
+    const structure = blankStringContents(text);
+    const out = [];
+    for (const m of structure.matchAll(/\bwaitForResponse\s*\(/g)) {
+        const open = m.index + m[0].length - 1;
+        const close = matchingClose(structure, open);
+        if (close !== -1)
+            out.push(normalize(text.slice(open + 1, close)));
+    }
+    return out;
+}
+/** A use of the identifier `name`: not part of a longer name or a property access. */
+export function identifierUseRe(name, flags = "") {
+    return new RegExp(`(?<![\\w$.])${escapeRegExp(name)}(?![\\w$])`, flags);
+}
+/** A declared parameter's name (see paramName), or `undefined` for a rest or
+ *  destructured one: no single value a call or a wildcard can carry. */
+export function simpleParamName(raw) {
+    if (/^\s*\.\.\./.test(raw))
+        return undefined;
+    const name = paramName(raw);
+    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : undefined;
+}
+/** The helper's ActionPattern, or `undefined` when a step stays unreadable with
+ *  its parameters as wildcards. `params` are the declared parameters as written. */
+export function actionPatternOf(body, language, params) {
+    // A parameter the body reassigns (`=`, `+=`, `++`, a destructuring) is not the
+    // value its caller passed.
+    const assigned = (text, name) => {
+        const id = escapeRegExp(name);
+        return [
+            `(?<![\\w$.])${id}\\s*(?:[-+*/%&|^]|\\*\\*|<<|>>>?|&&|\\|\\||\\?\\?)?(?<![!<>=])=(?![=>])`,
+            `(?:\\+\\+|--)\\s*${id}(?![\\w$])|(?<![\\w$.])${id}\\s*(?:\\+\\+|--)`,
+            `[[{][^=;]*(?<![\\w$.])${id}(?![\\w$])[^=;]*[\\]}]\\s*=(?![=>])`,
+        ].reduce((n, re) => n + (text.match(new RegExp(re, "g"))?.length ?? 0), 0);
+    };
+    const names = new Set(params
+        .map(simpleParamName)
+        .filter((n, i) => n !== undefined && assigned(body, n) <= assigned(params[i], n)));
+    const steps = actionStepsOf(body, language, names);
+    const keys = actionStepKeys(steps);
+    if (!keys)
+        return undefined;
+    const bindings = requestBindingsOf(body);
+    const uses = (text, name) => text.match(identifierUseRe(name, "g"))?.length ?? 0;
+    return {
+        steps: keys,
+        values: steps.map((s) => resolveStepValue(s.value, bindings, names)),
+        responseWaits: responseWaitsOf(body),
+        usedParams: params
+            .map(simpleParamName)
+            .filter((n, i) => n !== undefined && uses(body, n) > uses(params[i], n)),
+    };
+}
 /** Whitespace and braces dropped outside string literals, `'` normalised to `"` —
  *  the spelling a locator chain has inside a key. */
 export function normalizeChain(text) {

package/build/utils/utils-verify/action-sites.d.ts

@@ -25,6 +25,13 @@ import { type InlineCallSite, type SiblingScan } from "./call-sites.js";
  *    a sibling action with an undefined key equals nothing, so no run crosses it.
  *    Both fail open — no match, no finding — as STEP 3b's decline rule does.
  *
+ * Two widenings (SKYR-4537), each held to boundRun's checks, so that every such
+ * site names the exact call that replaces it: the generator's own per-step bindings
+ * (`const playwrightRequestN = {…}`, `const responsePromiseN =
+ * page.waitForResponse(…)`, `const responseN = await responsePromiseN`) are
+ * transparent between two actions, and a helper whose locator argument is one of
+ * its parameters matches with the sibling's literal in that place.
+ *
  * Where two helpers' keys start the same run, the longer wins; the run's actions are
  * consumed and the scan continues after it. A run inside the sibling's own local
  * helper is reported with that helper's name, as the API scan does.

package/build/utils/utils-verify/action-sites.js

@@ -1,7 +1,7 @@
 import * as path from "path";
-import { blankComments, localHelperAt, localHelpersOf, } from "./parse.js";
+import { blankComments, defaultAt, localHelperAt, localHelpersOf, } from "./parse.js";
 import { expectArgs, HELPER_FAMILIES, } from "./language-spec.js";
-import { actionStepsOf, blankStringContents, normalizeChain, statementSpans, } from "./action-key.js";
+import { actionStepsOf, blankStringContents, identifierUseRe, normalizeChain, paramSlot, requestBindingsOf, SLOT_MARK, resolveStepValue, responseWaitsOf, simpleParamName, statementSpans, } from "./action-key.js";
 import { realpath } from "./locate.js";
 import { nonUtilsSiblings, } from "./call-sites.js";
 /** A presence assertion as `[normalised locator, matcher]`, or undefined when the
@@ -38,6 +38,13 @@ function presenceWait(text, spec) {
  *    a sibling action with an undefined key equals nothing, so no run crosses it.
  *    Both fail open — no match, no finding — as STEP 3b's decline rule does.
  *
+ * Two widenings (SKYR-4537), each held to boundRun's checks, so that every such
+ * site names the exact call that replaces it: the generator's own per-step bindings
+ * (`const playwrightRequestN = {…}`, `const responsePromiseN =
+ * page.waitForResponse(…)`, `const responseN = await responsePromiseN`) are
+ * transparent between two actions, and a helper whose locator argument is one of
+ * its parameters matches with the sibling's literal in that place.
+ *
  * Where two helpers' keys start the same run, the longer wins; the run's actions are
  * consumed and the scan continues after it. A run inside the sibling's own local
  * helper is reported with that helper's name, as the API scan does.
@@ -55,25 +62,28 @@ export async function findSiblingInlineActionSites(testFile, helpersByFile, spec
         const localHelpers = localHelpersOf(content, spec);
         // Comments blanked, strings kept — the same reading the helper's key was made
         // from, so a commented-out click is not a step and the selectors compare.
-        const steps = actionStepsOf(blankComments(content, spec), spec.language);
+        const blanked = blankComments(content, spec);
+        const steps = actionStepsOf(blanked, spec.language);
         let i = 0;
         while (i < steps.length) {
-            const match = sequences.find((s) => runMatches(steps, i, s, spec));
-            if (!match) {
+            let run;
+            const match = sequences.find((s) => (run = runMatches(steps, i, s, spec, blanked)));
+            if (!match || !run) {
                 i++;
                 continue;
             }
-            const first = steps[i];
-            const last = steps[i + match.steps.length - 1];
-            const owner = localHelperAt(localHelpers, first.line);
+            const owner = localHelperAt(localHelpers, steps[i].line);
+            // A local helper named as the shared one: a call inside it would call itself.
+            const call = owner?.name === match.helper ? undefined : run.call;
             out.push({
                 kind: "sequence",
                 file,
-                line: first.line,
-                endLine: last.line,
-                actionKey: match.key,
+                line: run.line,
+                endLine: run.endLine,
+                actionKey: run.actionKey,
                 helper: match.helper,
                 utilsFile: match.utilsFile,
+                ...(call ? { call } : {}),
                 ...(owner ? { localHelper: owner.name } : {}),
             });
             i += match.steps.length;
@@ -81,29 +91,214 @@ export async function findSiblingInlineActionSites(testFile, helpersByFile, spec
     }
     return out;
 }
-/** Whether the helper's sequence is the run of actions starting at `at`, with
- *  nothing between its actions that a helper body could not hold, and no wait in
- *  or right after the run that contradicts one of the helper's own. */
-function runMatches(steps, at, helper, spec) {
+/** The helper's sequence as the run of actions starting at `at`, with nothing
+ *  between its actions that a helper body could not hold, and no wait in or right
+ *  after the run that contradicts one of the helper's own — or `undefined`. A run
+ *  that matches only through a generated binding or a wildcard is held to boundRun.
+ *  `sibling` is the sibling's source, comments blanked, as `steps` were read. */
+function runMatches(steps, at, helper, spec, sibling) {
     const want = helper.steps;
     if (at + want.length > steps.length)
-        return false;
+        return undefined;
+    const args = new Map();
+    const between = [];
     for (let k = 0; k < want.length; k++) {
         const step = steps[at + k];
-        if (step.key === undefined || step.key !== want[k])
-            return false;
+        if (step.key === undefined || !stepMatches(want[k], step.key, args))
+            return undefined;
         if (k > 0) {
-            const between = transparentStatements(step.gapBefore, spec);
-            if (between === undefined)
-                return false;
-            if (contradictsWaits(between, helper.waits, spec))
-                return false;
+            const gap = transparentStatements(step.gapBefore, spec);
+            if (gap === undefined)
+                return undefined;
+            if (contradictsWaits(gap, helper.waits, spec))
+                return undefined;
+            between.push(...gap);
         }
     }
     // The structural waits that follow the last action are the run's too: a wait the
     // helper would perform, or its opposite.
     const trailing = transparentStatements(steps[at + want.length - 1].gapAfter, spec, { prefix: true });
-    return !contradictsWaits(trailing ?? [], helper.waits, spec);
+    if (contradictsWaits(trailing ?? [], helper.waits, spec))
+        return undefined;
+    const run = steps.slice(at, at + want.length);
+    if (!helper.wildcard && !between.some(isGeneratedBinding)) {
+        // No call is named here, but the advisory still has the agent write one.
+        if (run.some((s, k) => liftsLiteralSecret(helper.values[k], s.value, resolveStepValue(s.value, new Map()))))
+            return undefined;
+        return {
+            line: run[0].line,
+            endLine: run[run.length - 1].endLine,
+            actionKey: helper.key,
+        };
+    }
+    return boundRun(steps[at - 1], run, between, helper, args, sibling, spec);
+}
+/** Whether a sibling step's key equals the helper's, a wildcard taking the literal
+ *  in its place — recorded in `args`, and refused when the same parameter has
+ *  already taken a different one. */
+function stepMatches(want, got, args) {
+    if (!want.includes(SLOT_MARK))
+        return want === got;
+    const parts = want.split(SLOT_RE);
+    const literal = new RegExp("^" +
+        parts
+            .map((p, i) => i % 2
+            ? '("(?:[^"\\\\]|\\\\.)*")'
+            : p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+            .join("") +
+        "$").exec(got);
+    if (!literal)
+        return false;
+    return parts
+        .filter((_, i) => i % 2)
+        .every((name, i) => bindArg(args, name, literal[i + 1]));
+}
+/** A wildcard in a key: the parameter's name between paramSlot's markers. */
+const SLOT_RE = new RegExp(`"${paramSlot("([A-Za-z_$][\\w$]*)")}"`);
+/** Records `value` as the argument for `name`; false when `name` already has a
+ *  different one — one parameter cannot carry two values. */
+function bindArg(args, name, value) {
+    const held = args.get(name);
+    if (held === undefined)
+        args.set(name, value);
+    return held === undefined || normalizeChain(held) === normalizeChain(value);
+}
+/**
+ * A run that matched through a generated binding or a wildcard: the call that
+ * replaces it, with the range that call replaces — or `undefined`, when one call
+ * cannot replace it exactly:
+ *
+ *  - **The range.** Grown back over the generated declarations right before the
+ *    first action and forward over the `await responsePromiseN` right after the
+ *    last, so a binding and its use go together.
+ *  - **No dangling name.** Every generated name the range uses is declared in it,
+ *    and no name it declares is used outside it.
+ *  - **Same response waits.** The range's `waitForResponse`s and the helper's are
+ *    equal as multisets: a wait the helper lacks would be lost, and one the range
+ *    lacks would wait for a response the sibling may never cause.
+ *  - **No lost assertion.** Between two actions, only generated bindings, waits and
+ *    the presence waits the helper itself performs: any other assertion would be
+ *    deleted with the range.
+ *  - **No lifted secret.** A password- or secret-named value is not lifted into a
+ *    literal argument of hand-maintained code.
+ *  - **Values.** A value the helper takes as a parameter becomes that argument —
+ *    a binding's literal lifted out of `getValue(playwrightRequestN, …)`; any other
+ *    value must equal the helper's. Each parameter maps to ONE value, and every
+ *    parameter but `page` and a trailing defaulted one is given one.
+ */
+function boundRun(before, run, between, helper, args, sibling, spec) {
+    for (const s of between) {
+        if (isGeneratedBinding(s))
+            continue;
+        const body = s.replace(/^await\s+/, "");
+        if (WAIT_STATEMENT_RE.test(blankStringContents(body)))
+            continue;
+        const wait = presenceWait(body, spec);
+        if (!wait || helper.waits.get(wait[0]) !== wait[1])
+            return undefined;
+    }
+    const first = run[0];
+    const last = run[run.length - 1];
+    let line = first.line;
+    let endLine = last.endLine;
+    const lead = before ? spansOf(before.gapAfter) : [];
+    let from = lead.length;
+    while (from > 0 && DECLARATION_RE.test(lead[from - 1].structure))
+        from--;
+    if (from < lead.length)
+        line = lead[from].line + before.endLine - 1;
+    const trail = spansOf(last.gapAfter);
+    let to = 0;
+    while (to < trail.length && RESPONSE_AWAIT_RE.test(trail[to].structure))
+        to++;
+    if (to > 0)
+        endLine = trail[to - 1].endLine + last.endLine - 1;
+    const range = [
+        ...lead.slice(from).map((s) => s.text),
+        ...between,
+        ...trail.slice(0, to).map((s) => s.text),
+    ];
+    const declared = new Set(range.flatMap((s) => [...s.matchAll(/\bconst\s+([A-Za-z_$][\w$]*)/g)].map((m) => m[1])));
+    const used = [...range, ...run.map((s) => s.value)].flatMap((s) => [...s.matchAll(GENERATED_NAME_RE)].map((m) => m[0]));
+    if (used.some((name) => !declared.has(name)))
+        return undefined;
+    const lines = sibling.split("\n");
+    for (const name of declared) {
+        const use = identifierUseRe(name);
+        if (lines.some((l, i) => (i + 1 < line || i + 1 > endLine) && use.test(l)))
+            return undefined;
+    }
+    const rangeWaits = range.flatMap(responseWaitsOf).sort();
+    const helperWaits = [...helper.responseWaits].sort();
+    if (rangeWaits.length !== helperWaits.length ||
+        rangeWaits.some((w, i) => w !== helperWaits[i]))
+        return undefined;
+    const bindings = requestBindingsOf(range.join("\n"));
+    for (let k = 0; k < run.length; k++) {
+        const want = helper.values[k];
+        const got = resolveStepValue(run[k].value, bindings);
+        // A value read through a generated binding this cannot resolve: the same
+        // `playwrightRequestN` text holds a different value in each spec.
+        const opaque = (v) => v.kind === "expr" && v.text.match(GENERATED_NAME_RE) !== null;
+        const ok = !liftsLiteralSecret(want, run[k].value, got) &&
+            !opaque(want) &&
+            !opaque(got) &&
+            (want.suffix ?? "") === (got.suffix ?? "") &&
+            (want.kind === "param"
+                ? ![...declared].some((n) => identifierUseRe(n).test(got.text)) &&
+                    bindArg(args, want.text, got.text)
+                : normalizeChain(want.text) === normalizeChain(got.text));
+        if (!ok)
+            return undefined;
+    }
+    const call = callOf(helper, args);
+    if (call === undefined)
+        return undefined;
+    return {
+        line,
+        endLine,
+        actionKey: helper.wildcard ? run.map((s) => s.key).join("; ") : helper.key,
+        call,
+    };
+}
+/** The statements of a gap, each with its text, its string-blanked text, and its
+ *  first and last line counted from the gap's own first line (1). */
+function spansOf(gap) {
+    const structure = blankStringContents(gap);
+    const lineAt = (i) => gap.slice(0, i).split("\n").length;
+    return statementSpans(structure)
+        .map(([from, to]) => ({
+        text: gap.slice(from, to).trim(),
+        structure: structure.slice(from, to).trim(),
+        line: lineAt(from),
+        endLine: lineAt(to),
+    }))
+        .filter((s) => s.text !== "await");
+}
+/** `await createOrder(page, "a@b.c", "option-1")`: the helper's call with each
+ *  parameter's argument, or `undefined` when a parameter has none — `page` is the
+ *  page, and a defaulted or optional parameter with nothing after it is left out —
+ *  unless the body reads it: `express = false` gating a click the sibling makes. */
+function callOf(helper, args) {
+    const out = [];
+    for (const param of helper.params) {
+        const name = simpleParamName(param);
+        if (!name)
+            return undefined;
+        const optional = /^\s*[\w$]+\s*\?/.test(param) || defaultAt(param) !== -1;
+        out.push(args.get(name) ??
+            (name === "page" || /:\s*Page\b/.test(param)
+                ? "page"
+                : optional && !helper.usedParams.includes(name)
+                    ? undefined
+                    : "\0"));
+    }
+    while (out.length > 0 && out[out.length - 1] === undefined)
+        out.pop();
+    if (out.some((a) => a === undefined || a === "\0"))
+        return undefined;
+    // The browser scan runs for TypeScript and JavaScript only (inlineCallSiteFamily).
+    return `await ${helper.helper}(${out.join(", ")})`;
 }
 /** Whether one of `statements` asserts an element the helper waits on with a
  *  different matcher or negation. */
@@ -120,8 +315,9 @@ function contradictsWaits(statements, waits, spec) {
 }
 /**
  * The statements of `gap` that a shared browser helper may hold — a permitted
- * structural wait, as the verify pass judges one (`HELPER_FAMILIES.browser`), or a
- * `waitFor…` — or `undefined` when one is not, or when the gap closes a bracket it
+ * structural wait, as the verify pass judges one (`HELPER_FAMILIES.browser`), a
+ * `waitFor…`, or between two actions one of the generator's per-step bindings
+ * (isGeneratedBinding; boundRun carries it) — or `undefined` when one is not, or when the gap closes a bracket it
  * did not open. With `prefix`, the leading transparent statements up to the first
  * that is not: the waits that follow a run, read until the run's own text ends.
  * Statements are cut as statementSpans cuts them, on a string-blanked copy, so a
@@ -140,6 +336,7 @@ function transparentStatements(gap, spec, opts = {}) {
             continue;
         const body = text.replace(/^await\s+/, "");
         const transparent = WAIT_STATEMENT_RE.test(blankStringContents(body)) ||
+            (!opts.prefix && isGeneratedBinding(text)) ||
             (spec.assertionRe.test(body) &&
                 HELPER_FAMILIES.browser.isAllowed(spec, body));
         if (!transparent)
@@ -161,9 +358,36 @@ function leavesBlock(structure) {
 }
 /** `page.waitForTimeout(3000)`, `page.waitForLoadState()`, `page.getByTestId("x")
  *  .waitFor({ state: "visible" })` — a wait on the page or on a locator chain, as a
- *  statement of its own (not bound: `const p = page.waitForResponse(…)` is used
- *  later, and the run cannot carry it). */
+ *  statement of its own (a BOUND wait is used later: only the generator's own, see
+ *  isGeneratedBinding, is carried, by boundRun). */
 const WAIT_STATEMENT_RE = /^(?:this\.)?page(?:\s*\.\s*[\w$]+\s*\([^;]*\))*\s*\.\s*(?:waitFor\w*|wait_for\w*)\s*\([^;]*\)\s*$/;
+/** The generator's per-step declarations, string-blanked: `const playwrightRequestN:
+ *  Record<string, any> = {…}` (the value the next fill reads) and `const
+ *  responsePromiseN = page.waitForResponse(…)`. A hand-written binding is not one. */
+const DECLARATION_RE = /^const\s+(?:playwrightRequest\d+\s*(?::\s*Record\s*<[^>]*>)?\s*=\s*\{[^;]*\}|responsePromise\d+\s*=\s*(?:this\.)?page\s*\.\s*waitForResponse\s*\([^;]*\))\s*;?$/;
+/** The generator's `const responseN = await responsePromiseN`, string-blanked. */
+const RESPONSE_AWAIT_RE = /^(?:const\s+response\d+\s*=\s*)?await\s+responsePromise\d+\s*;?$/;
+/** A parameter or binding key that holds a secret: its value stays out of a call. */
+const SECRET_NAME_RE = /password|passwd|secret|token|api_?key/i;
+/** Whether a step would lift a literal secret into a call argument — a password-
+ *  or secret-named parameter (or `getValue` key) given a literal — on either path:
+ *  the literal stays out of hand-maintained code. A variable (`loginPassword`) is
+ *  no secret in itself and may be passed. */
+function liftsLiteralSecret(want, raw, got) {
+    return (want.kind === "param" &&
+        got.kind === "literal" &&
+        (SECRET_NAME_RE.test(want.text) ||
+            SECRET_NAME_RE.test(GET_VALUE_KEY_RE.exec(raw)?.[1] ?? "")));
+}
+/** The key a `getValue(binding, "key")` step value reads. */
+const GET_VALUE_KEY_RE = /^\s*getValue\s*\([^,]*,\s*["']([^"']*)["']/;
+/** A name the generator binds per step. */
+const GENERATED_NAME_RE = /\b(?:playwrightRequest|responsePromise|response)\d+\b/g;
+/** One of the generator's per-step bindings (statement text as written). */
+function isGeneratedBinding(text) {
+    const structure = blankStringContents(text);
+    return DECLARATION_RE.test(structure) || RESPONSE_AWAIT_RE.test(structure);
+}
 /** A step whose receiver is the keyboard or the mouse rather than a locator. */
 function isElementlessStep(step) {
     return /^\w+ (?:this\.)?page\.(?:keyboard|mouse)(?:\s|$)/.test(step);
@@ -176,27 +400,45 @@ function helperSequences(helpersByFile, spec) {
     const seen = new Set();
     for (const [utilsFile, helpers] of helpersByFile)
         for (const h of helpers) {
-            if (!h.actionKey || !h.actionSteps || seen.has(h.actionKey))
+            const pattern = h.actionPattern;
+            // No key: a step whose locator is fed by a parameter is a wildcard (SKYR-4537).
+            const steps = h.actionSteps ?? pattern?.steps;
+            const key = h.actionKey ?? steps?.join("; ");
+            if (!key || !steps || !pattern || seen.has(key))
                 continue;
             // A key of bare keyboard or mouse steps names no element: `press "Escape"`
             // is what closes a dialog in one helper and a menu in the next, and every
             // Escape in every sibling matched it (measured: fixture 22, the advisory
             // named a menu close for a dialog-closing helper). One locator-bearing step
             // is enough to identify the sequence.
-            if (h.actionKey.split("; ").every(isElementlessStep))
+            if (key.split("; ").every(isElementlessStep))
+                continue;
+            // A wildcard widens what a step equals, so the sequence must still be named
+            // by its literal steps: at least two, and more than its wildcard steps — a
+            // `clickByTestId(page, id)` would otherwise equal every such click.
+            const wildcard = !h.actionSteps;
+            const literal = steps.filter((s) => !s.includes(SLOT_MARK) && !isElementlessStep(s)).length;
+            if (wildcard && (literal < 2 || literal <= steps.length - literal))
                 continue;
-            seen.add(h.actionKey);
+            seen.add(key);
             out.push({
                 helper: h.name,
                 utilsFile,
-                key: h.actionKey,
-                steps: h.actionSteps,
+                key,
+                steps,
+                wildcard,
+                params: h.params ?? [],
+                values: pattern.values,
+                responseWaits: pattern.responseWaits,
+                usedParams: pattern.usedParams,
                 waits: new Map(h.assertions
                     .map((a) => presenceWait(a.text, spec))
                     .filter((w) => w !== undefined)),
             });
         }
     // Longest first, so the run a longer sequence covers is not claimed by a shorter
-    // helper that shares its opening actions.
-    return out.sort((a, b) => b.steps.length - a.steps.length);
+    // helper that shares its opening actions; at equal length, a literal sequence
+    // before a wildcard one.
+    return out.sort((a, b) => b.steps.length - a.steps.length ||
+        Number(a.wildcard) - Number(b.wildcard));
 }

package/build/utils/utils-verify/call-sites.d.ts

@@ -35,7 +35,8 @@ export declare const REQUEST_CALL_RE: RegExp;
 interface InlineSiteBase {
     /** Absolute path of the sibling test. */
     file: string;
-    /** 1-based line of the request call, or of the first action of the sequence. */
+    /** 1-based line of the request call, or of the first action of the sequence (or
+     *  of the generated declaration that precedes it, SKYR-4537). */
     line: number;
     /** The utils helper that wraps the same method+path, or performs the same
      *  action sequence. */
@@ -58,8 +59,13 @@ export type InlineCallSite = (InlineSiteBase & {
     kind: "sequence";
     /** The action key the sequence and the helper share (see actionKeyOf). */
     actionKey: string;
-    /** 1-based line of the sequence's last action. */
+    /** 1-based line of the sequence's last action — or of the generated
+     *  `await responsePromiseN` that goes with it (SKYR-4537). */
     endLine: number;
+    /** The call that replaces lines `line`–`endLine`, arguments included, when
+     *  the run matched through a generated binding or a parameter-fed locator
+     *  (SKYR-4537): such a site is reported only when this can be named. */
+    call?: string;
 });
 /**
  * Inline request calls in OTHER Skyramp-generated tests beside `testFile` that a

package/build/utils/utils-verify/language-spec.js

@@ -355,7 +355,7 @@ export const HELPER_FAMILIES = {
         inlineSite: {
             noun: BROWSER_HELPERS.inlineSite.noun,
             already: "performs",
-            instruction: "Each is a candidate: the sequence's actions and locators equal the helper's, in order. Replace the sequence with a call to the helper only if the remaining differences are literals — fill values, option labels, literal arguments — which become the arguments (import the helper into that file; every assertion and the page-error guard stay in the test body where they are; change nothing else there).",
+            instruction: "Each is a candidate: the sequence's actions and locators equal the helper's, in order, except a locator the helper takes as a parameter, which becomes that argument. Replace the sequence with a call to the helper only if the remaining differences are literals — fill values, option labels, literal arguments — which become the arguments (import the helper into that file; every assertion and the page-error guard stay in the test body where they are; change nothing else there).",
             localCopy: "the sequence",
         },
     },

package/build/utils/utils-verify/parse.d.ts

@@ -1,4 +1,5 @@
 import { type UtilsLanguageSpec } from "./language-spec.js";
+import { type ActionPattern } from "./action-key.js";
 import { type HelperSleep } from "./fixed-sleep.js";
 import { type SourceSpan } from "../pom-scope/strip.js";
 export interface HelperAssertion {
@@ -56,6 +57,9 @@ export interface UtilsHelper {
      *  step per entry, for the sibling scan that matches step by step. */
     actionKey?: string;
     actionSteps?: string[];
+    /** The sequence as the sibling scan matches it, a parameter-fed locator as a
+     *  wildcard (SKYR-4537). See actionPatternOf. */
+    actionPattern?: ActionPattern;
 }
 /** The declared parameters of a signature, raw text trimmed, empty entries dropped
  *  (a trailing comma). Reads the signature from the definition line to its body

package/build/utils/utils-verify/parse.js

@@ -1,5 +1,5 @@
 import { normalizePath } from "./language-spec.js";
-import { actionStepKeys, actionStepsOf, } from "./action-key.js";
+import { actionPatternOf, actionStepKeys, actionStepsOf, } from "./action-key.js";
 /** A helper's action steps and their joined key, read once from its body. */
 function actionSequence(body, language) {
     const steps = actionStepsOf(body, language);
@@ -282,6 +282,7 @@ export function parseUtilsFile(content, spec) {
             // Comments blanked, strings kept: a commented-out click is not a step, and
             // the selector literals are the key.
             ...actionSequence(blankComments(body.join("\n"), spec), spec.language),
+            actionPattern: actionPatternOf(blankComments(body.join("\n"), spec), spec.language, params ?? []),
         };
         let requests = 0;
         for (let k = 0; k < body.length; k++) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/mcp",
-  "version": "0.5.0-rc.6",
+  "version": "0.5.0-rc.8",
   "main": "build/index.js",
   "exports": {
     ".": "./build/index.js",

package/plugin/skills/setup-testbot-target-sut/reference/deployed-environment.md

@@ -14,7 +14,9 @@ Take these from the guidance, and confirm them in the repositories (routes, conf
   header, basic auth, a session cookie, or a preview's bypass header). A token generated at run time is fine.
 - **Ready check:** the route and answer that mean it is ready, such as `GET /health → 200`. A page every route returns,
   like a single-page app's, proves nothing; use a route that returns real data.
-- **Running version,** if anything shows it: a version route, a response header, or a build-info file.
+- **How to tell what runs:** a mechanism that shows the commit each component runs, on every later run: a version
+  route, a platform API (Vercel, Netlify, Render, Heroku), GitHub Deployments, a GitOps manifest or Helm values file in
+  a Target repository, or Kubernetes metadata. Find the mechanism, never a list of commits.
 
 `localhost`, `127.0.0.1` or a container name is not a deployment: it only says where a local bring-up listens.
 
@@ -46,6 +48,18 @@ Say exactly what the user must add, and where:
 - `health-check.sh` runs the ready check, signed in when needed, and prints one line per part of at least 16 characters,
   with no secrets: `qa.acme.dev ready: GET /health -> 200`. `health.json` runs it.
 - `get-auth-token.sh`, when sign-in is needed, prints one token for this run. It never logs anyone out.
+- `deployed-revisions.sh` prints one JSON object and nothing else: each component a repository builds, mapped to the
+  full commit it runs, such as `{"api": "<40-character commit>"}`. For a source that says only what a deploy tool was
+  asked to deploy (GitHub Deployments, a deploy workflow run), give that component an object under its own name:
+  `{"api": "<commit>", "web": {"revision": "<commit>", "state": "requested"}}`.
+  Expand a short commit inside the script (`gh api repos/<owner>/<repo>/commits/<short> --jq .sha`).
+  - Testbot runs it with no agent, before and after each later run, in an empty directory with no checkout. It gets
+    the credentials in `environment` as environment variables of those names, `GH_TOKEN` (reads the Target's
+    repositories) and `GITHUB_API_URL`. Your own session has no `GH_TOKEN`.
+  - Testbot runs it twice at setup. Each commit must be the same in both runs and be a commit of the component's own
+    repository, so never print a config repository's commit (Argo CD, Flux) for an app component.
+  - A repository it reads that is not one of the Target's: ask to add it to the Target. A network a GitHub-hosted
+    runner cannot reach, such as a cluster API: report a blocker that it needs a self-hosted runner.
 
 **Otherwise: the prompt does not ask for `environment`, part of it is built, its address changes per PR (a preview), or
 reaching it needs something on the runner** (a tunnel, port-forward, proxy or client certificate):
@@ -62,13 +76,14 @@ reaching it needs something on the runner** (a tunnel, port-forward, proxy or cl
   "environment": {"address": "https://qa.acme.dev", "readyWhen": "GET /health → 200", "credentials": ["QA_TEST_USER"],
     "revisionSources": [{"method": "version_endpoint", "detail": "GET /version", "components": ["api"]}]}
   ```
-  - `deployed`: the revision the component runs, as its revision source shows it, or `null` when nothing does.
+  - `deployed`: the commit the component runs, as `deployed-revisions.sh` prints it, or `null` when nothing shows it.
   - A deployed part no repository of the Target builds, such as its database, is a component with
     `"repository": "shared"`.
-  - **Revision sources:** prefer a route Testbot can read on every run (`version_endpoint`, or `api` for a field of an
-    API response), named as `GET /version`. Use `deploy_workflow`, `kubernetes_labels` or `command` only when no route
-    shows it. Each component a repository builds needs one; if nothing shows what one runs, ask on the Setup page how
-    to tell, and if no answer comes, report a blocker asking for it in the Test Environment's notes.
+  - **Revision sources** describe what `deployed-revisions.sh` reads, such as `version_endpoint` with `GET /version`,
+    `deploy_workflow`, `kubernetes_labels`, or `command` when no method fits. Each component a repository builds needs
+    one. If nothing shows what one runs, ask on the Setup page with a `choose_source` question whose choices are the
+    mechanisms you found, never the commits; write the script from the answer. If no answer comes, report a blocker
+    asking for it in the Test Environment's notes.
 - Otherwise, leave `environment` and `deployed` out.
   Report each deployed part with these steps:
   - `start`: `Already deployed at <address>` (source `notes`)