@skyramp/mcp 0.4.2 → 0.4.3-rc.1

package/build/execution/wrapperConfig.d.ts

@@ -26,6 +26,10 @@ export declare function findRepoPlaywrightConfig(testFile: string, cwd: string):
  *   refuses `--browser` when the config defines projects (`common/config.js`:
  *   "Cannot use --browser option when configuration file defines projects").
  *   See `utils/rebaselineSnapshots.ts` for the layout.
+ * - `channel: "chromium"` on every Chromium project that names no channel. Without it
+ *   headless Chromium runs Playwright's separate headless-shell binary, which crashed
+ *   on `newPage` on a host where the full browser ran (SKYR-4509). A project that
+ *   inherits a channel or another browser from the top level gets none.
  * No reporter: the verdict is the exit code.
  */
 export declare function buildWrapperConfig(opts: {

package/build/execution/wrapperConfig.js

@@ -57,6 +57,10 @@ export function findRepoPlaywrightConfig(testFile, cwd) {
  *   refuses `--browser` when the config defines projects (`common/config.js`:
  *   "Cannot use --browser option when configuration file defines projects").
  *   See `utils/rebaselineSnapshots.ts` for the layout.
+ * - `channel: "chromium"` on every Chromium project that names no channel. Without it
+ *   headless Chromium runs Playwright's separate headless-shell binary, which crashed
+ *   on `newPage` on a host where the full browser ran (SKYR-4509). A project that
+ *   inherits a channel or another browser from the top level gets none.
  * No reporter: the verdict is the exit code.
  */
 export function buildWrapperConfig(opts) {
@@ -71,7 +75,7 @@ export function buildWrapperConfig(opts) {
     // the flag when the config declares projects, so there it must stay empty.
     const chromiumProject = (useExpr) => opts.commandPassesBrowserFlag
         ? ""
-        : `{ name: "chromium", outputDir: ${outputDir}, use: { ...${useExpr}, browserName: "chromium" } }`;
+        : `{ name: "chromium", outputDir: ${outputDir}, use: { channel: "chromium", ...${useExpr}, browserName: "chromium" } }`;
     const testMatchOverlay = opts.testFile
         ? `...(base.testMatch ? { testMatch: [...asList(base.testMatch), ${JSON.stringify(opts.testFile)}] } : {}),`
         : "";
@@ -91,6 +95,14 @@ export default config;
     return `import base from ${JSON.stringify(`./${opts.repoConfigBasename}`)};
 
 const withVideo = (use) => ({ ...(use ?? {}), video: "on" });
+// A project also inherits the top-level use, so both decide its browser and channel.
+const withChannel = (use) => {
+  const seen = { ...(base.use ?? {}), ...(use ?? {}) };
+  const browser = seen.browserName ?? seen.defaultBrowserType ?? "chromium";
+  return seen.channel !== undefined || browser !== "chromium"
+    ? use
+    : { ...(use ?? {}), channel: "chromium" };
+};
 const reuseServer = (server) => ({ ...server, reuseExistingServer: true });
 
 const asList = (m) => (Array.isArray(m) ? m : [m]);
@@ -112,7 +124,7 @@ const config = {
         projects: base.projects.map((p) => ({
           ...p,
           outputDir: ${outputDir},
-          use: withVideo(p.use),
+          use: withVideo(withChannel(p.use)),
         })),
       }
     : ${chromiumProject("withVideo(base.use)")

package/build/prompts/code-reuse.d.ts

@@ -1,2 +1,6 @@
+import { type ReuseRoute } from "../utils/reuseRouting.js";
 import type { ScopedPomInput } from "../utils/pom-scope/index.js";
-export declare function getCodeReusePrompt(testFile: string, language: string, framework?: string, scopedPoms?: ScopedPomInput, testType?: string): string;
+export declare function getCodeReusePrompt(testFile: string, language: string, framework: string | undefined, scopedPoms: ScopedPomInput | undefined, testType: string | undefined, 
+/** Resolved once by the caller (reuseRouteFor): which pass this call serves, and
+ *  whether the two passes compose for this target. */
+route: ReuseRoute): string;

package/build/prompts/code-reuse.js

@@ -1,8 +1,8 @@
 import { generateSkyrampHeader, SKYRAMP_UTILS_HEADER } from "../utils/utils.js";
 import { isUtilsReuseEnabled } from "../utils/featureFlags.js";
-import { inlineCallSiteFamily, isModularizeFirstTarget, isPomAwareTarget, } from "../utils/reuseRouting.js";
+import { inlineCallSiteFamily, isModularizeFirstTarget, } from "../utils/reuseRouting.js";
 import { getPomAwareCodeReusePrompt } from "./pom-aware-code-reuse.js";
-import { NO_SHADOWING_RULE, SELECTOR_OWNING_MODULE_RULE, selectHelperPolicy, } from "./shared-helper-policy.js";
+import { AFTER_POM_PASS_RULE, NO_SHADOWING_RULE, SELECTOR_OWNING_MODULE_RULE, selectHelperPolicy, } from "./shared-helper-policy.js";
 import { UTILS_LANGUAGE_SPECS } from "../utils/utils-verify/language-spec.js";
 /** The prescribed module name comes from the verifier's language table, which is the
  *  ONE declaration of it: the instruction the agent reads and the name the verify pass
@@ -73,10 +73,13 @@ const pyImportRule = (fileName) => {
     return `**Import form (Python)**: if the test's directory contains \`__init__.py\`, a bare \`from ${stem} import …\` will NOT resolve when the customer runs pytest from their repo root — the test dies at collection. Write the fallback pair, which works there AND in the Skyramp executor: \`try:\` / \`    from .${stem} import …\` / \`except ImportError:\` / \`    from ${stem} import …\` — with \`…\` the names this test actually uses, unchanged between the two arms. Without \`__init__.py\` the bare form alone is correct — do not add the fallback.`;
 };
 const pyImportRuleLine = (fileName) => `- ${pyImportRule(fileName)}`;
-export function getCodeReusePrompt(testFile, language, framework, scopedPoms, testType) {
+export function getCodeReusePrompt(testFile, language, framework, scopedPoms, testType, 
+/** Resolved once by the caller (reuseRouteFor): which pass this call serves, and
+ *  whether the two passes compose for this target. */
+route) {
     const lang = language.toLowerCase();
-    if (isPomAwareTarget(lang, framework, testType)) {
-        return getPomAwareCodeReusePrompt(testFile, lang, scopedPoms);
+    if (route.pass === "pom") {
+        return getPomAwareCodeReusePrompt(testFile, lang, scopedPoms, route.composed);
     }
     const languageEntry = LANGUAGE_MAP[lang] ?? LANGUAGE_MAP.python;
     const ext = languageEntry.extension;
@@ -116,12 +119,15 @@ export function getCodeReusePrompt(testFile, language, framework, scopedPoms, te
         : `**STOP HERE IF NO OTHER SKYRAMP-GENERATED TEST FILES FOUND**
 **IF NO OTHER SKYRAMP-GENERATED TEST FILES ARE FOUND, SKIP TO STEP 6 - DO NOT CREATE ANY UTILS FILES.**`;
     // The repository's own browser helper modules. UI only, and only on the seeded
-    // (utils reuse on, page-object reuse off) flow: a browser test and the helpers it
+    // (utils reuse on) flow — after the page-object pass when that is on too: a browser test and the helpers it
     // calls drive one library, so the verifier's action key compares a step to the
     // customer's helper; the API side has no such key and is a separate change.
     const inHouseBrowser = seedsUtils && policy.kind === "browser";
+    // Both reuse settings on: this flow runs after the page-object pass on the same
+    // test, and takes only what that pass left inline.
+    const pomFirst = route.composed;
     const inHouseDiscoveryStep = inHouseBrowser
-        ? inHouseDiscovery(testFile, fileName)
+        ? inHouseDiscovery(testFile, fileName, pomFirst)
         : "";
     const inHouseMatchStep = inHouseBrowser
         ? inHouseMatch(testFile, fileName, policy)
@@ -203,7 +209,7 @@ ${site.afterSteps}
     const precondition = modularizeFirst
         ? `
 **PRECONDITION — check your own tool-call history, not the file**: this flow moves the helpers skyramp_modularization created into \`${fileName}\` (STEP 5b)${inHouseBrowser ? " — or into the repository's own browser helper module when it has one (STEP 3b)" : ""}. If you have NOT called skyramp_modularization on ${testFile} in this run, STOP: call it now with \`testFile\` set to ${testFile}, \`testType: "${testType}"\`, and \`isTraceBased: true\`, apply its instructions, then call skyramp_reuse_code again with the same arguments as this call. If you HAVE called it and the file still defines no helper functions, that is a legitimate outcome — proceed; STEP 5b will simply have nothing to move.
-`
+${pomFirst ? `\n${AFTER_POM_PASS_RULE}\n` : ""}`
         : "";
     return `# CODE REUSE - 6 CLEAR STEPS 
 **CRITICAL WARNING: VIOLATION OF THESE RULES WILL RESULT IN ERROR**
@@ -409,13 +415,13 @@ SUMMARIZE THE CODE REUSE PROCESS AND THE RESULTS.
  * so a module nobody enumerated is still found; a module not written for Playwright
  * is then reported as unreadable rather than filtered out in silence.
  */
-function inHouseDiscovery(testFile, fileName) {
+function inHouseDiscovery(testFile, fileName, pomFirst) {
     return `
 ## STEP 2b: FIND THE REPOSITORY'S OWN BROWSER HELPER MODULES
 
 The header grep in STEP 2 finds only modules Skyramp wrote. The repository may already hold browser helpers of its own — a module the team wrote, carrying no Skyramp header — and a test that ignores it ends with two helper layers for the same steps. Find them.
 
-1. **Search the directory of ${testFile} and each of its parent directories up to the repository root.** Use Grep for Playwright locator and action calls (\`getBy\`, \`.locator(\`, \`page.\`, \`.click(\`, \`.fill(\`) in files that are NOT test files. Do NOT limit the search to a fixed list of file or directory names (\`pages/\`, \`helpers/\`, \`*.page.ts\` are hints, not the search), and do NOT limit it to one extension or language. Exclude \`node_modules\`, \`${fileName}\` and every other file carrying the \`${SKYRAMP_UTILS_HEADER}\` header (STEP 2 owns those), and test files — by BASENAME only: a basename ending in \`.spec.ts\`, \`.spec.js\`, \`.test.ts\`, \`.test.js\` is a test; a directory called \`tests/\` is not.
+1. **Search the directory of ${testFile} and each of its parent directories up to the repository root.** Use Grep for Playwright locator and action calls (\`getBy\`, \`.locator(\`, \`page.\`, \`.click(\`, \`.fill(\`) in files that are NOT test files. Do NOT limit the search to a fixed list of file or directory names (\`pages/\`, \`helpers/\`, \`*.page.ts\` are hints, not the search), and do NOT limit it to one extension or language. Exclude \`node_modules\`, \`${fileName}\` and every other file carrying the \`${SKYRAMP_UTILS_HEADER}\` header (STEP 2 owns those), and test files — by BASENAME only: a basename ending in \`.spec.ts\`, \`.spec.js\`, \`.test.ts\`, \`.test.js\` is a test; a directory called \`tests/\` is not.${pomFirst ? " Exclude every module that declares a class as well: that is a page object, and the page-object pass already owned it." : ""}
 2. **Read every candidate.** ${SELECTOR_OWNING_MODULE_RULE} A module written for a browser library other than Playwright shares no vocabulary with this test: read it, record it, and report it as unreadable — do not call it and do not extend it.
 3. **Catalog each qualifying module** to chat before changing anything: for each helper its name, **whether the module exports it UNDER THAT NAME** (an \`export\` on the definition, or an unaliased entry in an \`export { … }\` list of its own bindings — a default export and an aliased one export something else, and a helper this test cannot import is one it cannot call), its parameters (with defaults), what it returns, and its ACTION KEY — the sequence of Playwright actions it performs, in body order, each as the verb plus the locator chain it is called on (\`fill page.getByTestId("email"); click page.getByRole("button", { name: "Sign in" })\`). Argument VALUES are not part of the key, with two exceptions that ARE: a \`goto\` target and a \`dragTo\` destination — where a navigation goes and where a drag lands are the identity of those steps, so a helper that opens another page never matches. The key is UNDEFINED for a helper whose locator is not built from plain string literals — a variable, a template literal, a regex, a parameter; record it as undefined.
 4. **Record every file the search read** — qualifying or not — as a repository-relative path. You pass this list to the verify call at the end (\`inHouse.filesRead\`). A file you did not read is not on it.

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

@@ -1,6 +1,6 @@
-import { isModularizeFirstTarget } from "../../utils/reuseRouting.js";
+import { isModularizeFirstTarget, isPomFirstTarget, } from "../../utils/reuseRouting.js";
 import { PromptPlan } from "../test-recommendation/promptPlan.js";
-import { ASSERTION_BOUNDARY_RULE_EXTRACT, BROWSER_HELPERS, BROWSER_VALUE_ASSERTIONS, } from "../shared-helper-policy.js";
+import { AFTER_POM_PASS_RULE, ASSERTION_BOUNDARY_RULE_EXTRACT, BROWSER_HELPERS, BROWSER_VALUE_ASSERTIONS, } from "../shared-helper-policy.js";
 import { renderModularizationPrompt, } from "./render.js";
 // On modularize-first UI flows (utils reuse on, POM reuse off), downstream
 // skyramp_reuse_code consolidates this file's helpers into the shared
@@ -196,12 +196,19 @@ export function getModularizationPrompt(filePath, testType, language) {
         filePath,
         utilsReuse: isModularizeFirstTarget(testType, language),
     };
+    // Both reuse settings on: this file already went through the page-object pass.
+    const afterPomPassRules = isPomFirstTarget(language, testType)
+        ? [
+            `DO NOT MOVE A PAGE-OBJECT CALL, OR A STEP UNDER A \`// kept inline:\` LINE, INTO A HELPER. ${AFTER_POM_PASS_RULE}`,
+        ]
+        : [];
     return renderModularizationPrompt({
         title: "UI TEST MODULARIZATION - IMPROVE READABILITY AND REDUCE DUPLICATION",
         forbidden: [
             "DO NOT CREATE INTERFACES, CLASSES, TYPES, NEW FILES, OR NEW DATA STRUCTURES",
             `DO NOT CHANGE TEST LOGIC, DATA VALUES, CALCULATIONS, OR ASSERTIONS${params.utilsReuse ? " (moving a value assertion out of a helper into the test body, verbatim, is a placement — not a change)" : ""}`,
             "DO NOT CREATE/UPDATE  DEPENDENCY FILES package.json, requirements.txt, pom.xml, build.gradle file",
+            ...afterPomPassRules,
         ],
         plan: _plan,
         params,

package/build/prompts/pom-aware-code-reuse.d.ts

@@ -1,2 +1,5 @@
 import type { ScopedPomInput } from "../utils/pom-scope/index.js";
-export declare function getPomAwareCodeReusePrompt(testFile: string, language?: string, scopedPoms?: ScopedPomInput): string;
+export declare function getPomAwareCodeReusePrompt(testFile: string, language?: string, scopedPoms?: ScopedPomInput, 
+/** Both reuse settings on (isPomFirstTarget): this is the FIRST pass, and the
+ *  SkyrampUtils flow takes what it leaves inline. */
+pomFirst?: boolean): string;

package/build/prompts/pom-aware-code-reuse.js

@@ -2,7 +2,30 @@ import { generateSkyrampHeader, SKYRAMP_UTILS_HEADER } from "../utils/utils.js";
 import { resolvePomCatalogPath } from "../utils/pom-catalog.js";
 import { UTILS_LANGUAGE_SPECS } from "../utils/utils-verify/language-spec.js";
 import { SELECTOR_OWNING_MODULE_RULE } from "./shared-helper-policy.js";
-export function getPomAwareCodeReusePrompt(testFile, language = "typescript", scopedPoms) {
+/** Both reuse settings on: which modules this pass owns, and what it leaves for the
+ *  SkyrampUtils flow that runs after it. The ownership rule is the one
+ *  pom-scope/ownership.ts applies to detection and to the in-house verifier. */
+const COMPOSED_PASS_RULE = `
+**This is the FIRST of two reuse passes on this test.** This pass maps the test onto the repository's page-object CLASSES. A module that declares no class — a free-function helper library such as \`support/pageActions.ts\` or \`testUtils.ts\` — is NOT a page object on this path: do not map onto it, even when STEP 1 lists it; the second pass reuses such modules. The second pass (skyramp_modularization, then skyramp_reuse_code again) moves the steps this pass leaves inline into a shared helper module. Page-object calls you write here stay in the test body in that pass.
+`;
+/** Nick's routing for a step no page-object member covers, on a page the page objects
+ *  model: it stays inline and is marked, so the second pass leaves it there. A step on
+ *  a page nothing models needs no marker — the second pass moves it. */
+const KEPT_INLINE_ON_MODELED_PAGE = `Where an action is on a page one of the page-object classes models but no member of that class covers it, keep it inline and put \`// kept inline: <that file's basename> — <reason>\` on a line of its own above it: such a step stays inline in the delivered test, and the second pass leaves it where it is. Do NOT add a member or a class to the customer's page objects. An action on a page no page object models needs no marker — the second pass moves it into the shared helper module.`;
+function composedFallback(testFile) {
+    return `## STEP 6: FALLBACK — NO PAGE-OBJECT MAPPING
+
+**You should only reach this step if:**
+- No page-object class was detected in STEP 1, OR
+- Zero locators/actions in the test mapped to any page-object member in STEP 2
+
+Make no change to the test's actions, and do NOT create a shared helper file or extract helpers in this pass. If STEP 1 listed page-object files, document each one with \`// kept inline: <file basename> — <reason it cannot cover this test>\` on a line of its own in ${testFile}. Then call \`skyramp_reuse_code\` with the same \`testFile\`/\`language\`/\`framework\`/\`testType\` and \`verify: true\`, and follow its report until it reports PASSED. The page-object pass is then finished: continue with the next step the generation result named for this file.
+`;
+}
+export function getPomAwareCodeReusePrompt(testFile, language = "typescript", scopedPoms, 
+/** Both reuse settings on (isPomFirstTarget): this is the FIRST pass, and the
+ *  SkyrampUtils flow takes what it leaves inline. */
+pomFirst = false) {
     // Resolved here, not left to the agent: the catalog only survives to the next
     // run if it lands where delivery stages it (SKYR-4141).
     const catalogPath = resolvePomCatalogPath(testFile);
@@ -14,6 +37,11 @@ export function getPomAwareCodeReusePrompt(testFile, language = "typescript", sc
     const codegenMarker = "// Generated by Skyramp v";
     const headerLang = isJs ? "javascript" : "typescript";
     const scopedActive = scopedPoms && scopedPoms.tier1.length + scopedPoms.tier2.length > 0;
+    if (!scopedActive && scopedPoms?.scannedNoOverlap && pomFirst) {
+        return `No reusable POM layer detected: no page-object class in this repository shares a selector with this test. The page-object pass for ${testFile} is finished — make no change to the file here, and do NOT call this tool with \`verify: true\` for this answer.
+
+Continue with the next step the generation result named for this file. The steps after it — skyramp_modularization, then skyramp_reuse_code again — move this test's steps into the shared helper module, or call the repository's own browser helpers where it has them.`;
+    }
     if (!scopedActive && scopedPoms?.scannedNoOverlap) {
         return `No reusable POM layer detected: a repo-wide scan found zero overlap between this test's selectors and any non-test source file. Code reuse is skipped — continue with the generated test as-is.
 
@@ -78,7 +106,7 @@ If you catch yourself about to skip a step, stop and execute it.
 **POM-Aware Code Reuse** means refactoring a generated test to use the project's existing Page Object Model (POM) classes and methods, replacing raw inline locators and action sequences with the proper abstractions the customer already has.
 
 This is NOT the same as SkyrampUtils consolidation. Do NOT create a SkyrampUtils file on the POM path.
-
+${pomFirst ? COMPOSED_PASS_RULE : ""}
 ---
 
 ${step1Section}
@@ -376,7 +404,9 @@ Do not skip this lookup for any action. The mapping table is your source of trut
 - Screenshot assertions (\`toHaveScreenshot\`): always keep inline; if mid-method sequence, inline that method's steps around it
 - Page readiness checks: use module methods such as \`pageToBeVisible()\` if they exist
 
-**IMPORTANT:** Do NOT create a \`${utilsFile}\` or any SkyrampUtils file on this path. Do NOT call \`skyramp_modularization\` after completing POM-aware code reuse — POM refactoring replaces that step.
+${pomFirst
+        ? `**IMPORTANT:** Do NOT create a \`${utilsFile}\` or any SkyrampUtils file in this pass, and do NOT extract helper functions. Every action no page-object member covers stays raw and inline in this pass — a later pass handles it. ${KEPT_INLINE_ON_MODELED_PAGE}`
+        : `**IMPORTANT:** Do NOT create a \`${utilsFile}\` or any SkyrampUtils file on this path. Do NOT call \`skyramp_modularization\` after completing POM-aware code reuse — POM refactoring replaces that step.`}
 
 ---
 
@@ -388,11 +418,13 @@ Do not output a section breakdown, modularization summary, or any analysis to th
 
 **A low substitution count can be the correct outcome.** When many actions stay inline because the POM layer simply does not model that flow (iframe-gate rejections, orphan frames, vocabulary drift from the cataloged classes), that is honest reuse, not a shortfall — do not pad the mapping table to inflate the count. In your one-line confirmation, state how many actions were substituted vs. kept inline and why in one clause (e.g. "6 substituted; 9 kept inline — POM layer does not model the apply-from-asset flow").
 
-**Do NOT run the test.** After writing the file, you MUST call \`skyramp_reuse_code\` once more with the same \`testFile\`/\`language\`/\`framework\` and \`verify: true\`, and follow its report: re-verify after every fix pass; a violation may be remapped at most once — if flagged again, demote it to the raw inline form; finish only when it reports PASSED (unverifiable notes are acceptable). Include \`verification: passed\` (or the unresolved count) in your final confirmation line.
+**Do NOT run the test.** After writing the file, you MUST call \`skyramp_reuse_code\` once more with the same \`testFile\`/\`language\`/\`framework\` and \`verify: true\`, and follow its report: re-verify after every fix pass; a violation may be remapped at most once — if flagged again, demote it to the raw inline form; finish only when it reports PASSED (unverifiable notes are acceptable). Include \`verification: passed\` (or the unresolved count) in your final confirmation line.${pomFirst ? ` When it reports PASSED, the page-object pass is finished: continue with the next step the generation result named for this file.` : ""}
 
 ---
 
-## STEP 6: FALLBACK — STANDARD SKYRAMPUTILS PATH
+${pomFirst
+        ? composedFallback(testFile)
+        : `## STEP 6: FALLBACK — STANDARD SKYRAMPUTILS PATH
 
 **You should only reach this step if:**
 - No POM files were detected in STEP 1, OR
@@ -604,6 +636,6 @@ For each helper defined locally in ${testFile}:
 
 **Do NOT call skyramp_modularization.** Code reuse is complete. The test file has been refactored in place — no further tools should be called on this FALLBACK path. (If you took the POM-aware path instead, STEP 5's verification requirement still applies.)
 
-SUMMARIZE THE CODE REUSE PROCESS AND THE RESULTS.
+`}SUMMARIZE THE CODE REUSE PROCESS AND THE RESULTS.
 `;
 }

package/build/prompts/reuse-hand-off.d.ts

@@ -61,4 +61,8 @@ export declare function buildModularizeFirstNextSteps(params: {
     language: UtilsLanguage;
     framework: string;
     enhanceFirst: boolean;
+    /** Both reuse settings on (isPomFirstTarget): the page-object pass comes first,
+     *  so its gates judge the spec while its selectors are all still inline, and
+     *  the enhancer keeps the place it has on the page-object path — after it. */
+    pomFirst?: boolean;
 }): string;

package/build/prompts/reuse-hand-off.js

@@ -110,7 +110,7 @@ function handOffStep(heading, values) {
     return fillPlaceholders(sectionBody(HAND_OFF_MD, `## ${heading}`), values);
 }
 export function buildModularizeFirstNextSteps(params) {
-    const { testType, language, framework, enhanceFirst } = params;
+    const { testType, language, framework, enhanceFirst, pomFirst } = params;
     const enhanceCall = enhanceAssertionsCall(testType, "generated test file");
     const values = {
         testType,
@@ -118,13 +118,18 @@ export function buildModularizeFirstNextSteps(params) {
         enhanceCall: enhanceCall.charAt(0).toUpperCase() + enhanceCall.slice(1),
     };
     const steps = [
-        ...(enhanceFirst ? [handOffStep("Enhance first", values)] : []),
+        ...(pomFirst ? [handOffStep("Page-object pass", values)] : []),
+        ...(enhanceFirst ? [handOffStep("Assertion enhancement", values)] : []),
         handOffStep("Modularize", values),
         handOffStep("Reuse", values),
     ];
-    const ordering = handOffStep(enhanceFirst
-        ? "Ordering with the enhancer"
-        : "Ordering without the enhancer", values);
+    const ordering = handOffStep(pomFirst
+        ? enhanceFirst
+            ? "Page objects with the enhancer"
+            : "Page objects without the enhancer"
+        : enhanceFirst
+            ? "Ordering with the enhancer"
+            : "Ordering without the enhancer", values);
     return `⏭️**CRITICAL NEXT STEPS — ${ordering}**:
 ${steps.map((text, i) => `${String.fromCharCode(97 + i)}. ${text}`).join("\n")}`;
 }

package/build/prompts/shared-helper-policy.d.ts

@@ -85,6 +85,11 @@ export declare const SELECTOR_OWNING_MODULE_RULE = "**A reuse target does not ha
  * and the local definition would then describe two different behaviours under
  * one name, and a later reader (or a deterministic gate) cannot tell which runs.
  */
+/** Both reuse settings on: the page-object pass already ran on this test. Stated at
+ *  the top of the seeded flow and in the modularization prompt, because both passes
+ *  that move code could otherwise carry a page-object call into a helper, where the
+ *  page-object record no longer sees it. */
+export declare const AFTER_POM_PASS_RULE = "**This test already went through the page-object pass.** Its calls on page-object instances (a method or property of a page-object class) stay in the test body, exactly where they are \u2014 never move one into a helper or into a shared module. A step under a `// kept inline:` line stays inline, with its line: it is on a page a page object models, and it is not moved. Everything else still inline is what this pass works on.";
 export declare const NO_SHADOWING_RULE = "If a helper stays local for any reason, it must NOT share a name with any export of the utils file \u2014 rename the local one to state what differs (e.g. `submitEditOrderFormNoWait`). A test file never defines a helper with the same name as a utils export.";
 export interface HelperPolicy {
     kind: "api" | "browser";

package/build/prompts/shared-helper-policy.js

@@ -163,6 +163,11 @@ export const SELECTOR_OWNING_MODULE_RULE = `**A reuse target does not have to be
  * and the local definition would then describe two different behaviours under
  * one name, and a later reader (or a deterministic gate) cannot tell which runs.
  */
+/** Both reuse settings on: the page-object pass already ran on this test. Stated at
+ *  the top of the seeded flow and in the modularization prompt, because both passes
+ *  that move code could otherwise carry a page-object call into a helper, where the
+ *  page-object record no longer sees it. */
+export const AFTER_POM_PASS_RULE = `**This test already went through the page-object pass.** Its calls on page-object instances (a method or property of a page-object class) stay in the test body, exactly where they are — never move one into a helper or into a shared module. A step under a \`// kept inline:\` line stays inline, with its line: it is on a page a page object models, and it is not moved. Everything else still inline is what this pass works on.`;
 export const NO_SHADOWING_RULE = "If a helper stays local for any reason, it must NOT share a name with any export of the utils file — rename the local one to state what differs (e.g. `submitEditOrderFormNoWait`). A test file never defines a helper with the same name as a utils export.";
 export const API_HELPERS = {
     kind: "api",

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

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

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

@@ -45,7 +45,7 @@ Build a detection list first: for each matched diff line, write one line: \`{pat
 **Rules (assign exactly one action per test; severity order above):**
 - **DELETE** when the test's target is gone: all routes/pages it covers no longer exist; all critical selectors were removed with no migration path; or, for a component/widget test, the component it renders was deleted (source removed with no re-export; report-only for external tests).
 - **REGENERATE** when the interaction model changed so fundamentally that the test's action sequence is broken with no migration path: the flow itself changed, not just selector values (e.g. a form replaced by a modal, buttons replaced by a dropdown, a click-to-update button replaced by an auto-updating stepper). Re-recording from scratch is the only viable approach. Broken-selector count alone does not decide REGENERATE; if the flow still works with targeted edits, it is UPDATE.
-- **UPDATE** when the test's flow still holds but something it relies on shifted on a page or component it exercises: a selector (className, data-testid, aria-*) was renamed or moved, a new selector was added that the test should adopt or assert (including a dynamic class like \`+ \`btn--\${variant}\`\`), an assertion needs adjusting, or a \`toHaveScreenshot()\` baseline captures something whose appearance the diff changed (see **Visual-snapshot baselines** above — name the stale files in \`rebaselineSnapshots\`). Fix it in place in the existing file, never a new spec for the same page or component. An added selector is still drift, not a no-op. Read the test/POM to confirm the component is targeted and prefer UPDATE; fall back to VERIFY only when reading leaves impact undetermined.
+- **UPDATE** when the test's flow still holds but something it relies on shifted on a page or component it exercises: a selector (className, data-testid, aria-*) was renamed or moved, a new selector was added that the test should adopt or assert (including a dynamic class like \`+ \`btn--\${variant}\`\`), an assertion needs adjusting, or a \`toHaveScreenshot()\` baseline captures something whose appearance the diff changed (see **Visual-snapshot baselines** above — name the stale files in \`rebaselineSnapshots\`). Fix it in place in the existing file, never a new spec for the same page or component. An added selector is still drift, not a no-op. Read the test/POM to confirm the component is targeted and prefer UPDATE; fall back to VERIFY only when reading leaves impact undetermined. If the UPDATE changes the value the test enters or selects, keep the assertion only if the diff, the PR description, or a referenced spec gives that same result for the new value. If they give a different result, change the assertion to that result. Do not choose a value because the running app still gives the old result for it.
 - **VERIFY** when the test may be impacted but you cannot confirm breakage without reading more context (e.g. the affected selectors live in a page object or indirect import you have not read). Read that file before escalating to UPDATE.
 - **IGNORE** when the changed code cannot reach this test's routes or rendered components (the diff touches different routes or components). If you cannot point to a diff line affecting this test's routes, selectors, or rendered components, the action is IGNORE or VERIFY, not UPDATE.
 </ui_decision_rules>`;
@@ -113,6 +113,7 @@ Page objects can live anywhere in the repo (not just \`page-objects/\` or \`fixt
 2. For each imported file, read it and extract the selectors it encapsulates — \`locator()\`, \`getByTestId()\`, \`getByRole()\`, \`getByLabel()\`, \`data-test-*\`, \`aria-label\`, CSS class strings.
 3. Compare those selectors against the diff: if a selector value the page object uses was renamed or removed in a \`-\` diff line → the page object needs **UPDATE**.
 4. **Update the page object file, not the spec file** — the page object is the selector source of truth. In the recommendation: set \`testFile\` to the **spec file** (so it shows correctly in the maintenance report) and set \`pomFile\` to the **page object path** (so \`skyramp_actions\` edits the right file). If the edit is rejected at action time, the agent or developer can address it separately.
+   **Exception — Skyramp's own shared helper module is never a page object.** An imported file whose first lines carry the \`Generated by Skyramp on\` header (e.g. \`skyrampUtils.ts\`, wherever it lives, \`tests/lib/\` included) never goes in \`pomFile\`. When a selector it holds was renamed or removed, give the module its OWN recommendation: an **UPDATE** whose \`testFilePath\` is the module itself, and repair the helper there — change its body, keep its name and parameter list exactly as they are, because other tests call it. Each spec that calls the helper keeps its own recommendation with \`testFilePath\` set to the spec.
 5. If the imported file is missing or unreadable → **VERIFY** (cannot confirm without the file).
 
 A clean spec with no raw selector calls is not a reason to assign VERIFY — it is expected when page objects are used. Assign the action based on the POM's selectors.

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

@@ -45,11 +45,14 @@ const UTILS_REUSE_ENABLED = isUtilsReuseEnabled();
 const FIX_ERRORS_RETRY_HINT = isSkillsLoaded()
     ? ` — ${fixErrorsInstruction()} before the retry`
     : "";
-// The UI flow seeds a shared utils file (modularize-first) only with utils reuse
-// on and the POM path off — the same condition isModularizeFirstTarget applies
-// server-side. Every UI-chain statement in this prompt keys on this constant so
-// no line can ban the modularization call the generation result instructs.
+// The UI flow seeds a shared utils file (modularize-first) whenever utils reuse is
+// on — the condition isModularizeFirstTarget applies server-side. With the POM path
+// also on, the page-object pass runs first and the seeded flow takes what it left
+// inline (isPomFirstTarget). Every UI-chain statement in this prompt keys on these
+// constants so no line can ban the modularization call the generation result
+// instructs.
 const UI_UTILS_REUSE = UTILS_REUSE_ENABLED && !POM_REUSE_ENABLED;
+const UI_COMPOSED_REUSE = UTILS_REUSE_ENABLED && POM_REUSE_ENABLED;
 // ── Hand-numbered list labels ─────────────────────────────────────────────────
 // Each list below is hand-written in the prompt body, so PromptPlan cannot number
 // it without changing what the agent reads. The definition site and every
@@ -128,23 +131,37 @@ export const EXEC_FAIL = orderedLabels([
 function capitalize(text) {
     return text.charAt(0).toUpperCase() + text.slice(1);
 }
-// The UI enhance entry of the post-generation list. On the modularize-first UI
-// flow the enhance call is the first sub-step of the generation result's chain — but
+// The UI enhance entry of the post-generation list. On a modularize-first UI
+// flow the enhance call is a sub-step of the generation result's chain — but
 // that chain exists only for a TS/JS UI generation with enhanceAssertions on,
 // which this prompt cannot see per call. So the step keeps the call and lets
-// the agent skip it only when it already made it for that file.
+// the agent skip it only when it already made it for that file. `chainPosition`
+// names where in that chain the call sits; absent, the call stands alone.
+function uiEnhanceStep(chainPosition) {
+    const call = capitalize(enhanceAssertionsCall("ui", "generated UI test file"));
+    if (!chainPosition)
+        return `${call}.`;
+    return `${call} — UNLESS you already did it for this file as ${chainPosition} of step ${POSTGEN.UI_CODE_REUSE}'s chain, in which case skip it (never enhance the same file twice; never leave a generated UI test un-enhanced). The guidance below on which assertions to add applies to whichever call enhances the file.`;
+}
 const UI_ENHANCE_STEP = UI_UTILS_REUSE
-    ? `${capitalize(enhanceAssertionsCall("ui", "generated UI test file"))} — UNLESS you already did it for this file as the first sub-step of step ${POSTGEN.UI_CODE_REUSE}'s chain, in which case skip it (never enhance the same file twice; never leave a generated UI test un-enhanced). The guidance below on which assertions to add applies to whichever call enhances the file.`
-    : `${capitalize(enhanceAssertionsCall("ui", "generated UI test file"))}.`;
+    ? uiEnhanceStep("the first sub-step")
+    : UI_COMPOSED_REUSE
+        ? uiEnhanceStep("a sub-step")
+        : uiEnhanceStep();
 // Post-generation code-reuse step for UI tests. The POM catalog, the `verify: true`
 // loop and the `.raw.bak` restore only exist on the POM-aware path — when that path
 // is flagged off, `skyramp_reuse_code` returns the SkyrampUtils workflow instead, so
 // the agent must not be sent looking for artifacts nothing produces.
-const UI_CODE_REUSE_STEP = POM_REUSE_ENABLED
-    ? `${POSTGEN.UI_CODE_REUSE}. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result directs you to call \`skyramp_reuse_code\` — do this BEFORE enhancing assertions. Two outcomes: (1) a response starting "No reusable POM layer detected" — this is a normal outcome, continue immediately (do NOT retry); (2) a refactoring workflow — follow it to completion INCLUDING its verification loop (\`skyramp_reuse_code\` with \`verify: true\`), finish only when it reports PASSED. If a reused test later fails execution and the failure points at a substituted POM call, restore the saved \`<testFile>.raw.bak\` over the test file and re-run — do NOT hand-edit the customer's POM methods (this re-run counts toward the per-file execution attempt cap; when the budget allows no re-run, restore the file for delivery and report the failure instead of executing again — prefer this restore over the generic timeout fix-up when the failing locator came from a POM substitution). **Cleanup before reporting:** \`.raw.bak\` files are internal scratch — after ALL test executions are complete (pass or fail) and before calling \`skyramp_submit_report\`, delete every \`*.raw.bak\` you created so they are not committed to the customer-facing branch. The \`skyramp-pom-catalog.md\` is NOT scratch — leave it in place (later runs reuse it).`
-    : UI_UTILS_REUSE
-        ? `${POSTGEN.UI_CODE_REUSE}. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result carries three CRITICAL NEXT STEPS — \`skyramp_enhance_assertions\` (on the freshly generated file, while its selectors are still inline), then \`skyramp_modularization\`, then \`skyramp_reuse_code\` — with the exact arguments for each. Do all three, in that order and to completion, for EVERY generated UI test file — the enhance sub-step is that file's step ${POSTGEN.UI_ENHANCE} below (do not call \`skyramp_enhance_assertions\` a second time for the same file, and do not skip it for later files). Sibling tests offering nothing to reuse is a normal outcome, but the reuse steps still move this test's own helpers into the shared utils file — or, where the repository already has a browser helper module of its own, call its helpers and add to that module what it lacks — and import them back, so the test file IS expected to change. Then continue (do NOT retry).`
-        : `${POSTGEN.UI_CODE_REUSE}. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result directs you to call \`skyramp_reuse_code\` — do this BEFORE enhancing assertions. Follow the returned steps exactly. If it finds no existing helper functions to reuse, that is a normal outcome — leave the test file unchanged and continue immediately (do NOT retry).`;
+// The `.raw.bak` restore and the cleanup that follows it: the page-object pass
+// writes the backup whether or not the SkyrampUtils flow runs after it.
+const POM_RESTORE_AND_CLEANUP = `If a reused test later fails execution and the failure points at a substituted POM call, restore the saved \`<testFile>.raw.bak\` over the test file and re-run — do NOT hand-edit the customer's POM methods (this re-run counts toward the per-file execution attempt cap; when the budget allows no re-run, restore the file for delivery and report the failure instead of executing again — prefer this restore over the generic timeout fix-up when the failing locator came from a POM substitution). **Cleanup before reporting:** \`.raw.bak\` files are internal scratch — after ALL test executions are complete (pass or fail) and before calling \`skyramp_submit_report\`, delete every \`*.raw.bak\` you created so they are not committed to the customer-facing branch. The \`skyramp-pom-catalog.md\` is NOT scratch — leave it in place (later runs reuse it).`;
+const UI_CODE_REUSE_STEP = UI_COMPOSED_REUSE
+    ? `${POSTGEN.UI_CODE_REUSE}. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: for a TypeScript or JavaScript Playwright test, the generation result carries CRITICAL NEXT STEPS — \`skyramp_reuse_code\` (the page-object pass, INCLUDING its verification loop until it reports PASSED, or its "No reusable POM layer detected" answer), then \`skyramp_enhance_assertions\` when it lists it, then \`skyramp_modularization\`, then \`skyramp_reuse_code\` again — with the exact arguments for each. Do them all, in that order and to completion, for EVERY generated UI test file; the enhance sub-step, when listed, is that file's step ${POSTGEN.UI_ENHANCE} below (do not call \`skyramp_enhance_assertions\` a second time for the same file). The page-object pass maps the test onto the repository's page objects; the second reuse call moves what it left inline into the shared helper module — or calls the repository's own browser helpers where it has them — so the test file IS expected to change twice. Where the generation result names only \`skyramp_reuse_code\`, follow that one call exactly. ${POM_RESTORE_AND_CLEANUP}`
+    : POM_REUSE_ENABLED
+        ? `${POSTGEN.UI_CODE_REUSE}. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result directs you to call \`skyramp_reuse_code\` — do this BEFORE enhancing assertions. Two outcomes: (1) a response starting "No reusable POM layer detected" — this is a normal outcome, continue immediately (do NOT retry); (2) a refactoring workflow — follow it to completion INCLUDING its verification loop (\`skyramp_reuse_code\` with \`verify: true\`), finish only when it reports PASSED. ${POM_RESTORE_AND_CLEANUP}`
+        : UI_UTILS_REUSE
+            ? `${POSTGEN.UI_CODE_REUSE}. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result carries three CRITICAL NEXT STEPS — \`skyramp_enhance_assertions\` (on the freshly generated file, while its selectors are still inline), then \`skyramp_modularization\`, then \`skyramp_reuse_code\` — with the exact arguments for each. Do all three, in that order and to completion, for EVERY generated UI test file — the enhance sub-step is that file's step ${POSTGEN.UI_ENHANCE} below (do not call \`skyramp_enhance_assertions\` a second time for the same file, and do not skip it for later files). Sibling tests offering nothing to reuse is a normal outcome, but the reuse steps still move this test's own helpers into the shared utils file — or, where the repository already has a browser helper module of its own, call its helpers and add to that module what it lacks — and import them back, so the test file IS expected to change. Then continue (do NOT retry).`
+            : `${POSTGEN.UI_CODE_REUSE}. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result directs you to call \`skyramp_reuse_code\` — do this BEFORE enhancing assertions. Follow the returned steps exactly. If it finds no existing helper functions to reuse, that is a normal outcome — leave the test file unchanged and continue immediately (do NOT retry).`;
 // Generation-call clause for the integration pipeline: only ask for codeReuse when
 // utils reuse is enabled — with the flag off, integration generation behaves exactly
 // as it did before the feature existed (no file-rewriting post-steps).
@@ -567,7 +584,7 @@ ${CONTRACT_MODE_GUIDANCE}
 
   **The Blueprint Citation Invariant applies during recording too.** Every assertion you emit cites element names — those names must come from blueprint captures, not invention. For N user-intent-level actions, expect about N+1 \`browser_blueprint\` calls (the first returns full, the rest return deltas). Nothing counts them. Traces that follow the pattern produce assertions grounded in observable state changes; traces that skip captures fall back to author-inferred assertions and risk citing names that don't exist in the rendered DOM.
 
-  The rest of the UI workflow stays the same: trace plan, browser auth, navigation, export (\`skyramp_export_zip\`), generation (\`skyramp_ui_test_generation\`), then the post-calls the generation result lists (${UI_UTILS_REUSE ? "`skyramp_enhance_assertions`, `skyramp_modularization`, `skyramp_reuse_code`, in that order" : "`skyramp_reuse_code` (when `codeReuse: true`) and `skyramp_enhance_assertions`"}). Capture-act-capture adds blueprint captures alongside the existing steps; it doesn't replace anything.
+  The rest of the UI workflow stays the same: trace plan, browser auth, navigation, export (\`skyramp_export_zip\`), generation (\`skyramp_ui_test_generation\`), then the post-calls the generation result lists (${UI_UTILS_REUSE ? "`skyramp_enhance_assertions`, `skyramp_modularization`, `skyramp_reuse_code`, in that order" : UI_COMPOSED_REUSE ? "`skyramp_reuse_code` (the page-object pass), `skyramp_enhance_assertions`, `skyramp_modularization`, `skyramp_reuse_code` again, in that order" : "`skyramp_reuse_code` (when `codeReuse: true`) and `skyramp_enhance_assertions`"}). Capture-act-capture adds blueprint captures alongside the existing steps; it doesn't replace anything.
 - **E2E**: Only if BOTH a backend trace \`.json\` AND a Playwright \`.zip\` already exist in the repo. Without both, leave the planned test in your plan and say in \`businessCaseAnalysis\` that both traces have to be recorded first.
 - Skip smoke tests entirely.
 
@@ -678,7 +695,7 @@ ${task3CountRule ? `${task3CountRule}\n\n` : ""}${reportLanguageBlock}Call \`sky
         ? ` Items derived from a related repo's diff (from the \`<related_repositories>\` analysis) carry that repo's \`repository\` value. In \`businessCaseAnalysis\`, include a short per-repo subsection and call out any cross-repo correlations you found.`
         : ""}
 
-${getTraceRecordingPromptText({ outputDir: `${repositoryPath}/.skyramp`, modularize: false, modularizeViaGenerationResult: UI_UTILS_REUSE })}`;
+${getTraceRecordingPromptText({ outputDir: `${repositoryPath}/.skyramp`, modularize: false, modularizeViaGenerationResult: UI_UTILS_REUSE || UI_COMPOSED_REUSE })}`;
     // Neither path reaches the agent any more: SKYR-4147 made the report derive from the
     // state file's directory, and that directory comes from the environment via
     // runArtifactDir(). Keep it that way — a path the model retypes out of this prose is a

package/build/recommendation/fakeVerifyContext.d.ts

@@ -0,0 +1,3 @@
+import { VerifyContext } from "./types.js";
+/** A stand-in VerifyContext for tests: every field empty or answering "no", overridden per test. */
+export declare function verifyContext(over?: Partial<VerifyContext>): VerifyContext;

package/build/recommendation/fakeVerifyContext.js

@@ -0,0 +1,16 @@
+/** A stand-in VerifyContext for tests: every field empty or answering "no", overridden per test. */
+export function verifyContext(over = {}) {
+    return {
+        changedFiles: {},
+        reposWithoutDiff: [],
+        uiCaptures: [],
+        removedUiElements: [],
+        retiredUiElements: [],
+        changedRuns: {},
+        pullRequest: { title: "", description: "" },
+        citedFileExists: () => false,
+        readSpecFile: () => undefined,
+        routesRenderingFile: () => undefined,
+        ...over,
+    };
+}

package/build/recommendation/runVerifiers.js

@@ -10,6 +10,7 @@ import { expectedValueSourced } from "./verifiers/expectedValueSourced.js";
 import { removedElementGuarded } from "./verifiers/removedElementGuarded.js";
 import { requirementSourced } from "./verifiers/requirementSourced.js";
 import { defects } from "./verifiers/defects.js";
+import { changedLinesClaimed } from "./verifiers/changedLinesClaimed.js";
 /** Verifiers that need only the plan and the run's facts. The order is the order
  *  objections are reported in; it carries no priority. */
 export const PLAN_TIME_VERIFIERS = [
@@ -25,6 +26,7 @@ export const PLAN_TIME_VERIFIERS = [
     removedElementGuarded,
     requirementSourced,
     defects,
+    changedLinesClaimed,
 ];
 /** How a crashed verifier reads back. The id is the verifier's name plus a fixed
  *  word, so it stays stable across registrations and can be answered. */

package/build/recommendation/types.d.ts

@@ -39,6 +39,7 @@ export interface PlannedScenario {
 }
 import type { BlueprintCaptureDigest } from "../types/BlueprintDigest.js";
 import type { RemovedUiElement } from "../utils/removedUiElements.js";
+import type { ChangedRun } from "../utils/changedRuns.js";
 /** One element a UI planned test targets. EVERY field is optional and three are
  *  nullable: a declaration reaches a verifier unvalidated, so a missing or null
  *  field is an objection, not a crash. Not `Partial<BlueprintElementDigest>` —
@@ -66,6 +67,9 @@ export interface PlanChange {
     /** Where a user or caller meets this change. Every change states it: an optional
      *  field the agent skips gives the check nothing to read. */
     surfaces: Array<"api" | "page">;
+    /** The changed lines this change is: `path:12` or `path:12-20`, in the new file's
+     *  numbering. The changed-lines check reads it. */
+    lines?: string[];
     /** The inputs that prove this change: what a route must accept and what it must
      *  reject. Exactly one of `value` and `absent` per entry. The coverage check reads
      *  it; nothing else on the server does. */
@@ -237,6 +241,9 @@ export interface VerifyContext {
     /** Identifiers a rename replaced, empty when the diff renames nothing. Only the
      *  server pairs the two sides of a diff. */
     retiredUiElements: RemovedUiElement[];
+    /** Per repository, every run of changed lines the diff holds, in the new file's
+     *  numbering. Read from the same diff as `changedFiles`. */
+    changedRuns: Record<string, ChangedRun[]>;
     /** The pull request's title and description, as the run rendered its prompt with.
      *  The plan tool fills it from the process the prompt was rendered in. Both fields
      *  blank MEANS the run had no title and no description. */
@@ -248,6 +255,11 @@ export interface VerifyContext {
      *  the verifiers filesystem-free. Named a repository it asks that one, and a name
      *  this run does not know answers false. Omitted, it asks every one. */
     citedFileExists(relativePath: string, repository?: string): boolean;
+    /** The text of a `spec:` file a plan change cites, from the first repository that
+     *  holds it. UNDEFINED for a path no repository holds, a path outside every
+     *  checkout, or a file too large to read. Injected for the same reason as
+     *  `citedFileExists`. */
+    readSpecFile(relativePath: string): string | undefined;
     /** The route patterns that mount a changed frontend file, as the framework
      *  spells them (`/secrets/$envSlug`, `/orders/:id`). Injected for the same
      *  reason as `citedFileExists`: the scan reads the repository, the verifier

package/build/recommendation/verifierContracts.d.ts

@@ -255,8 +255,16 @@ export declare const REQUIREMENT_SOURCED_CONTRACT: {
             readonly suggestion: "Cite a change you read in the pull request or in a requirements file, or report this test as something other than a requirement conflict.";
         };
         readonly notNamed: {
-            readonly message: "Change `{change}` cites `{source}`, and the pull request names no such file.";
-            readonly suggestion: "Cite a file the title or description names. If neither names it, you read the change in the repository, so set `source` to `diff`.";
+            readonly message: "Change `{change}` cites `{source}`, and the pull request neither names nor changes such a file.";
+            readonly suggestion: "Cite a file the title or description names, or one the diff changes. If none does, you read the change in the repository, so set `source` to `diff`.";
+        };
+        readonly itemUnlinked: {
+            readonly message: "`{source}` lists item {number}, \"{item}\", and no change in this plan names it.";
+            readonly suggestion: "Set `source` to `{source}#{number}` on the change that covers this item, or answer with the reason it needs no test.";
+        };
+        readonly unnumbered: {
+            readonly message: "`{source}` lists {count} items, and no change names one of them by its number.";
+            readonly suggestion: "Name the item each change covers in its source, as `{source}#<number>` (`#7,8` for two), so each item can be checked.";
         };
         readonly emptyPullRequest: {
             readonly message: "Change `{change}` says it was read from the pull request, and the pull request has no title or description.";
@@ -307,6 +315,20 @@ export declare const DEFECTS_CONTRACT: {
     };
     readonly suggestion: "Which planned test proves each defect the review found, and for one nothing proves, why does it need no test?";
 };
+export declare const CHANGED_LINES_CLAIMED_CONTRACT: {
+    readonly id: "changedLinesClaimed";
+    readonly objections: {
+        readonly unclaimed: {
+            readonly message: "These changed lines are in a file a planned test covers, and no change in the plan names them in its `lines`.";
+            readonly suggestion: "Add these lines to the `lines` of the change they belong to, or declare a change for them, with a case that states what a test must see. If the lines change nothing a test can observe, say so as the answer.";
+        };
+        readonly noCase: {
+            readonly message: "These changed lines belong to a change that states no case, so no test is held to what they do.";
+            readonly suggestion: "Give the change a case whose `expectedValue` or `derived` states what a test must see after these lines. If the lines change nothing a test can observe, say so as the answer.";
+        };
+    };
+    readonly suggestion: "Which change owns each run of changed lines in a tested file, and what must a test see because of it?";
+};
 /** Fills a contract sentence's `{placeholder}` spans from the run's or the
  *  planned test's own values. A placeholder with no value is left as written rather
  *  than blanked, so a missed key shows up as `{knob}` instead of reading as a gap