@skyramp/mcp 0.4.2 → 0.4.3-rc.2

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

@@ -2,6 +2,7 @@ import { readFile } from "fs/promises";
 import * as path from "path";
 import { logger } from "../../utils/logger.js";
 import { isPomAwareTarget } from "../../utils/reuseRouting.js";
+import { pageObjectCandidates } from "../../utils/pom-scope/ownership.js";
 import { selectScopedPoms, } from "../../utils/pom-scope/index.js";
 import { stripComments, stripStrings } from "../../utils/pom-scope/strip.js";
 import { escapeRegExp } from "../../utils/regex.js";
@@ -174,10 +175,16 @@ classification = {
         return undefined;
     try {
         const specContent = await readFile(params.testFile, "utf8");
-        const { tier1, diagnostics } = await selectScopedPoms({
+        const scoped = await selectScopedPoms({
             testFile: params.testFile,
             specContent,
         });
+        const { diagnostics } = scoped;
+        // Both settings on: a free-function module is the in-house path's, so it is not
+        // a candidate this pass skipped — the same split discovery applied.
+        const tier1 = params.composed
+            ? await pageObjectCandidates(scoped.tier1)
+            : scoped.tier1;
         // Only fire on candidates found via conventional POM dirs (globs) — the selector-grep
         // discovery fallback also matches ordinary in-repo frontend source (app components
         // legitimately contain the spec's test-ids by construction), which is not evidence of

package/build/tools/generate-tests/generateContractRestTool.js

@@ -399,14 +399,14 @@ const CHAINING_SECTION = CONSUMER_MODE_ENABLED
 - \`parentStatusCode\`: expected HTTP status code for each parent provisioning call (e.g. \`{"id": "201"}\`). Not allowed with \`skipProvisionParents\`.`;
 export function registerContractTestTool(server) {
     server.registerTool(TOOL_NAME, {
-        description: `${getPersonaPrefix()}Before calling this tool, you MUST output a <thinking> block that covers:
+        description: `${getPersonaPrefix()}Before calling this tool, verify these test inputs and requirements against the codebase, workspace config, API schema, or user input:
 1. The endpoint URL and HTTP method being tested
-2. Whether the endpoint is a nested resource (URL contains a path parameter like \`{id}\`, \`{flow_id}\`, etc.) — if YES, decide: do I have the request body to provision the parent, or should I use skipProvisionParents?
-3. Assertion planning — answer all four:
-   a. Echo-back fields: which fields in the response are returned unchanged from the request body? (e.g. name, email, status) — these must be asserted with the exact sent value, not just not-null
-   b. Computed fields: are there any numeric fields derived from other values? (e.g. total_amount, discount_amount) — these must be asserted with the formula, never a hardcoded number
-   c. Test data isolation: does this test create its own resources via parentRequestData, or does it depend on pre-existing data? All IDs must come from provisioned resources, never hardcoded.
-   d. Edge cases and business logic bugs: if \`skyramp_analyze_changes\` already ran and returned recommendations for this endpoint, revisit them now — did the recommendation phase flag any boundary conditions, invalid-input behaviors, or business logic bugs? Each flagged risk should map to a targeted assertion in this test. A test that doesn't target a known risk is low-value.
+2. For a nested resource (URL contains a path parameter like \`{id}\`, \`{flow_id}\`, etc.), use the request body to provision the parent, or use skipProvisionParents when it cannot be provisioned.
+3. Assertion requirements:
+   a. Echo-back fields: assert response fields returned unchanged from the request body (e.g. name, email, status) with the exact sent value, not just not-null.
+   b. Computed fields: assert numeric fields derived from other values (e.g. total_amount, discount_amount) with the formula, never a hardcoded number.
+   c. Test data isolation: create the test's own resources via parentRequestData. All IDs must come from provisioned resources, never hardcoded.
+   d. Edge cases and business logic bugs: if \`skyramp_analyze_changes\` already ran and returned recommendations for this endpoint, map each flagged boundary condition, invalid-input behavior, or business logic risk to a targeted assertion in this test.
 4. Each required parameter and what value it will take, with source (workspace config / diff / schema / user input)
 NEVER use a hardcoded ID (UUID or integer) as a path parameter value. If a real resource ID is needed and cannot be provisioned, use skipProvisionParents instead.
 

package/build/tools/generate-tests/generateIntegrationRestTool.js

@@ -89,15 +89,15 @@ ${enhanceAssertionsStep("integration", "generated test file")}
 const TOOL_NAME = TOOL_INTEGRATION_TEST_GENERATION;
 export function registerIntegrationTestTool(server) {
     server.registerTool(TOOL_NAME, {
-        description: `${getPersonaPrefix()}Before calling this tool, you MUST output a <thinking> block that covers:
+        description: `${getPersonaPrefix()}Before calling this tool, verify these test inputs and requirements against the codebase, workspace config, API schema, or user input:
 1. The endpoint URL(s) and HTTP method(s) involved in this multi-step workflow
-2. Why an integration test (multi-step workflow validation) is the right choice for this intent
-3. Assertion planning — answer all four for each step:
-   a. Echo-back fields: which response fields are returned unchanged from the request body? List them by name — these get exact-value assertions, not just not-null checks
-   b. Computed fields: are there derived numeric fields (e.g. total_amount = price × quantity)? Name the formula — these get formula-based assertions, never hardcoded numbers
-   c. Chaining: which IDs in step N+1 come from step N's response? Name the JSON path (e.g. POST /orders response → order_id → GET /orders/{order_id}). Every ID must be dynamically chained — no hardcoded IDs anywhere in the test
-   d. Edge cases and business logic bugs: if \`skyramp_analyze_changes\` already ran and returned recommendations for these endpoints, revisit them now — did the recommendation phase flag any boundary conditions, invalid-input behaviors, or business logic bugs? Each flagged risk should map to a targeted assertion in this test. A test that doesn't target a known risk is low-value.
-4. Test data isolation: does this test create all its own resources from scratch, or does it depend on pre-existing database state? All prerequisite resources must be created within the test setup.
+2. The requested test exercises a multi-step workflow.
+3. Assertion requirements for each step:
+   a. Echo-back fields: assert response fields returned unchanged from the request body with the exact sent value, not just not-null.
+   b. Computed fields: assert derived numeric fields (e.g. total_amount = price × quantity) with the formula, never hardcoded numbers.
+   c. Chaining: use the relevant JSON path in step N's response for IDs in step N+1 (e.g. POST /orders response → order_id → GET /orders/{order_id}). Every ID must be dynamically chained — no hardcoded IDs anywhere in the test.
+   d. Edge cases and business logic bugs: if \`skyramp_analyze_changes\` already ran and returned recommendations for these endpoints, map each flagged boundary condition, invalid-input behavior, or business logic risk to a targeted assertion in this test.
+4. Test data isolation: create all prerequisite resources within the test setup, without depending on pre-existing database state.
 If any required parameter cannot be determined without guessing, STOP and ask the user before calling the tool.
 
 ---

package/build/tools/generate-tests/generateUIRestTool.js

@@ -101,10 +101,10 @@ export const uiTestSchema = {
 };
 export function registerUITestTool(server) {
     server.registerTool(TOOL_NAME, {
-        description: `${getPersonaPrefix()}Before calling this tool, you MUST output a <thinking> block that covers:
+        description: `${getPersonaPrefix()}Before calling this tool, verify these test inputs against the Playwright trace, codebase, and filesystem:
 1. The user-facing flow(s) captured in the Playwright trace (pages visited, actions taken)
-2. Why a UI test (Playwright-based interaction replay) is the right choice for this intent
-3. Which assertions this test should validate (page content, element state, navigation results)
+2. The intended behavior is covered by the recorded Playwright interactions.
+3. The expected page content, element state, or navigation results the test must assert
 4. The absolute path to the trace zip and the output directory, with source confirmation
 If the trace zip path cannot be confirmed as an absolute path to an existing file, STOP and re-export before calling this tool.
 

package/build/tools/submitReportTool.js

@@ -25,8 +25,10 @@ import { budgetExcuseRefusals, citesBudget, countBudgetExcuseRefusal, MAX_BUDGET
 import { countUiDeliveryRefusal, MAX_UI_DELIVERY_REFUSALS, traceExportAttempts, uiDeliveryRefusals, } from "../playwright/traceExportStore.js";
 import { getReportLanguage, isEnforcedReportLanguage, findLanguageViolations, findLanguageNearMisses, reportLanguageDisplayName, } from "../utils/reportLanguage.js";
 import { canonicalTestPath, findAssertionRecordByFileName, rederiveAssertionOutcome, } from "./code-refactor/assertion-state.js";
-import { rederiveReuse, deriveReuseFromDelivered, REUSE_SUBMIT_MAX_REFUSALS, reuseChainSkipped, samePath, } from "./code-refactor/reuse-state.js";
+import { canonPath, canonPathEvenIfGone, rederiveReuse, deriveReuseFromDelivered, REUSE_SUBMIT_MAX_REFUSALS, reuseChainSkipped, samePath, } from "./code-refactor/reuse-state.js";
+import { removedModulesFrom, } from "./code-refactor/removed-modules.js";
 import { retrofitGate, } from "./code-refactor/retrofit-state.js";
+import { changedHelpersForRow, deriveChangedHelpers, discloseChangedHelpers, } from "./code-refactor/changed-helper-report.js";
 import { onlyCommentLinesRemoved, stripGateMarkers, } from "./code-refactor/gate-markers.js";
 import { parseKeptInline } from "./code-refactor/reuse-outcome.js";
 import { hasUtilsHeader, locateUtilsFiles, parseUtilsAllows, realpath, utilsSpecForFile, } from "../utils/utils-verify/index.js";
@@ -705,21 +707,9 @@ function generatedPathFor(fileName, generated) {
         reason: `${matches.length} generated files match ${fileName} and this row does not say which, so its imports could not be read`,
     };
 }
-async function attachReuseOutcome(test, outcomes, handOffs, retrofits, 
-// A blocking verdict measured on the delivered files is collected here rather
-// than written into the row: the caller refuses the report on it. Required, not
-// defaulted — a caller that forgot it would ship the report with no refusal and
-// no compiler error. See the refusal below the row map.
-blocking, 
+async function attachReuseOutcome(test, ctx, 
 /** Declines this run removed from the delivered files. See stripDeliveredGateMarkers. */
 carriedDeclines, 
-/** Filled with the carried declines a finding consumed. What consumed nothing is
- *  retired: permission that covers no fault authorises the NEXT one instead. */
-consumed, 
-/** Filled with the files whose declines this pass actually MEASURED. Only those may
- *  be retired: a pass that read nothing consumes nothing, and deleting on that
- *  silence drops permission while the fault it covers is still in the file. */
-evaluated, 
 /** The row's absolute path when the caller has it (a maintenance row does; a
  *  newTestsCreated row carries a basename only). With it, a record or hand-off
  *  that names a same-named spec in another directory is not this row's. */
@@ -733,6 +723,8 @@ specPath,
  *  and the row states that reason. Omitting it altogether says the row has no
  *  delivered file to read — a VERIFY row, or one this run never wrote. */
 deliveredPath) {
+    const { outcomes, retrofits, changedHelpers, removedModules, blocking, consumed, evaluated, } = ctx;
+    let { handOffs } = ctx;
     // POM records describe browser specs; a basename collision with an API test's
     // fileName must not attach them there. A utils-path record is attachable anywhere.
     const byBasename = outcomes?.[path.basename(test.fileName)];
@@ -783,14 +775,66 @@ deliveredPath) {
     // So answer the row from the file instead. Only where there is nothing else to
     // report: a row that already carries a record or a chain claim is untouched, and
     // this can neither overwrite a measured value nor refuse a report.
+    // The row's own spec path, from the record when one attached and from the
+    // delivered file otherwise. Both disclosures below answer from it: gating on a
+    // stored record instead dropped every retrofit from a row answered by the
+    // fallback.
+    const rowSpecPath = found?.testFilePath ??
+        (typeof deliveredPath === "string" ? deliveredPath : undefined);
+    const changedHelperViews = rowSpecPath
+        ? changedHelpersForRow(changedHelpers, rowSpecPath)
+        : [];
     const fallback = !derived && !chainSkipped && deliveredPath && isUtilsReuseEnabled()
         ? typeof deliveredPath === "string"
             ? await deriveReuseFromDelivered(deliveredPath)
             : { notDerived: deliveredPath.reason }
         : undefined;
-    const reuse = derived || chainSkipped
+    const base = derived || chainSkipped
         ? { ...(derived ?? {}), ...(chainSkipped ? { chainSkipped } : {}) }
         : fallback;
+    // Two disclosures about a MODULE, layered over the assembled row rather than
+    // folded into `derived`, and outside the record branch, on purpose: a run that
+    // deleted or renamed the shared module has no helpers row to hang them on —
+    // verifyUtils locates nothing — and that is the case with the most to disclose.
+    // A row that would otherwise be answered by the import-derived fallback still
+    // gets that answer as well.
+    //  - `changedHelpers`: "this run rewrote code you already had, and here is who
+    //    calls it" — a statement the report has never made: it already names a
+    //    module that was CREATED, and nothing named one that was changed.
+    //  - `removedModules`: a module this run created beside this test and removed
+    //    again; without it the row reads "nothing to reuse" over a run that built a
+    //    module, rewired tests onto it and deleted it again. A row gets the modules
+    //    its own record located — wherever they lived — and those in its own
+    //    directory IN ITS OWN LANGUAGE, the tests the module was built beside: a
+    //    Python row beside a TypeScript module was not one of them. Both sides
+    //    canonical: the module path is a realpath from locateUtilsFiles, the spec
+    //    path is as supplied, and on a symlinked checkout (macOS /tmp) the two
+    //    never match raw.
+    const rowDir = rowSpecPath ? path.dirname(canonPath(rowSpecPath)) : undefined;
+    const rowLanguage = rowSpecPath
+        ? utilsSpecForFile(rowSpecPath)?.language
+        : undefined;
+    const listedByRecord = new Set((found?.utils?.modules ?? []).map((m) => canonPathEvenIfGone(m.file)));
+    const removedHere = removedModules.filter((m) => {
+        const file = canonPathEvenIfGone(m.file);
+        return (listedByRecord.has(file) ||
+            (path.dirname(file) === rowDir &&
+                rowLanguage !== undefined &&
+                utilsSpecForFile(file)?.language === rowLanguage));
+    });
+    const extras = {
+        ...(changedHelperViews.length > 0
+            ? {
+                changedHelpers: discloseChangedHelpers(changedHelperViews, changedHelpers.executions),
+            }
+            : {}),
+        ...(removedHere.length > 0
+            ? {
+                removedModules: removedHere.map(({ file: _file, ...entry }) => entry),
+            }
+            : {}),
+    };
+    const reuse = Object.keys(extras).length > 0 ? { ...(base ?? {}), ...extras } : base;
     if (!reuse)
         return test;
     // Pre-existing generated tests this spec's reuse pass rewired (SKYR-4276 A4): the
@@ -801,8 +845,6 @@ deliveredPath) {
     // path. Gating it on a stored record instead dropped every retrofit from a row
     // answered by the fallback — and the retrofit gate still refuses the report until
     // each one has run, so the run was blocked on a disclosure the report never made.
-    const rowSpecPath = found?.testFilePath ??
-        (typeof deliveredPath === "string" ? deliveredPath : undefined);
     if (reuse.helpers && rowSpecPath) {
         const mine = retrofits.filter((r) => samePath(r.testFile, rowSpecPath));
         if (mine.length > 0)
@@ -1737,6 +1779,14 @@ export function registerSubmitReportTool(server) {
         // rows below; an unexecuted one refuses the report (inside the SKYR-3883 block,
         // which already enumerates the working tree).
         let retrofitViews = [];
+        // The helpers this run changed in a module that already existed,
+        // and the tests that call them. Empty until the working-tree scan below runs —
+        // outside a testbot run there is no tree to compare against, and an empty set
+        // discloses nothing and demands nothing, which is the right silence.
+        let changedHelpers = {
+            byDir: new Map(),
+            executions: new Map(),
+        };
         /** Absolute paths this run changed. Undefined when they cannot be read — every
          *  reuse check falls back to acting on what it located. */
         let changedFilesAbs;
@@ -1749,8 +1799,18 @@ export function registerSubmitReportTool(server) {
         // verify against created/modified/untracked paths, not the eventual commit.
         if (isTestbotEnabled()) {
             const fullState = await stateManager.readFullState();
-            const repoRoot = fullState?.metadata?.repositoryPath;
-            if (repoRoot && repoRoot !== "unknown") {
+            const metadata = fullState?.metadata;
+            const repoRoot = metadata?.repositoryPath;
+            if (metadata && repoRoot && repoRoot !== "unknown") {
+                const { repository } = metadata;
+                // Every checkout this run may have written to, the primary first. Listed
+                // once, for the claim check, the changed-file scan and the changed-helper
+                // derivation.
+                const otherCheckouts = [
+                    getTestsRepoDir(),
+                    ...Object.values(fullState?.relatedRepos ?? {}).map((section) => section.repositoryPath),
+                ];
+                const checkoutRoots = [repoRoot, ...otherCheckouts];
                 const dependencyRoots = collectDependencyVerificationRoots(repoRoot, getTestsRepoDir(), fullState?.relatedRepos);
                 for (const dependencyRoot of dependencyRoots) {
                     try {
@@ -1783,10 +1843,7 @@ export function registerSubmitReportTool(server) {
                     // non-git one contributes nothing.
                     const changedFiles = [
                         ...(await listChangedFiles(repoRoot)),
-                        ...(await listChangedFilesAcross([
-                            getTestsRepoDir(),
-                            ...Object.values(fullState?.relatedRepos ?? {}).map((section) => section.repositoryPath),
-                        ])),
+                        ...(await listChangedFilesAcross(otherCheckouts)),
                     ];
                     // Primary verdicts only, by design: this checks UPDATEs, and
                     // skyramp_actions downgrades every actionable related-repo verdict to
@@ -1831,17 +1888,41 @@ export function registerSubmitReportTool(server) {
                             `Files with actual working-tree changes:\n${changedList || "  (none)"}`);
                         return errorResult;
                     }
-                    changedFilesAbs = await listChangedFilesAbs([
-                        repoRoot,
-                        getTestsRepoDir(),
-                        ...Object.values(fullState?.relatedRepos ?? {}).map((section) => section.repositoryPath),
-                    ]);
+                    changedFilesAbs = await listChangedFilesAbs(checkoutRoots);
                     const gate = await retrofitGate(stateData, changedFilesAbs, repoRoot);
                     retrofitViews = gate.views;
                     if (gate.refusal) {
                         errorResult = toolError(gate.refusal);
                         return errorResult;
                     }
+                    // A shared helper's change reaches every caller at once, and a caller the
+                    // run did not touch is never delivered — so nothing executed it and a
+                    // break in it reached the customer's continuous integration rather than
+                    // this report. Derived here, beside the retrofit gate, because both need
+                    // the same three things: the working tree's changed files, the test
+                    // inventory, and the repository root.
+                    // Derived from git, not from the reuse records, so a helper the
+                    // maintenance phase repaired with an UPDATE on the module is found the
+                    // same way as one the reuse pass rewrote. The refusal's remedy names
+                    // the repository section and state file `skyramp_execute_test` records
+                    // into.
+                    changedHelpers = await deriveChangedHelpers({
+                        roots: checkoutRoots,
+                        changedFilesAbs,
+                        state: stateData,
+                        repoRoot,
+                        repository,
+                        stateFile,
+                    });
+                    // An unexecuted caller refuses, because the remedy is one tool call the
+                    // agent can always make. A caller that RAN and FAILED does not: it is
+                    // disclosed with its result and the reviewer decides. Classifying it —
+                    // the helper's fault or the test's — is SKYR-4451's, and a cruder rule
+                    // stated here instead is the thing that ticket objected to.
+                    if (changedHelpers.refusal) {
+                        errorResult = toolError(changedHelpers.refusal);
+                        return errorResult;
+                    }
                 }
                 catch (err) {
                     // Never block a valid report because verification itself failed (path not a
@@ -1920,8 +2001,18 @@ export function registerSubmitReportTool(server) {
         const consumedDeclines = [];
         /** Files whose stored declines a re-derivation actually measured on this call. */
         const evaluatedDeclineFiles = new Set();
+        const reuseRowContext = {
+            outcomes: stateData.reuseOutcomes,
+            handOffs: stateData.reuseHandOffs,
+            retrofits: retrofitViews,
+            changedHelpers,
+            removedModules: await removedModulesFrom(stateData.reuseOutcomes),
+            blocking: reuseBlocking,
+            consumed: consumedDeclines,
+            evaluated: evaluatedDeclineFiles,
+        };
         const sanitizedNewTests = await Promise.all(dedupedNewTests.map(async ({ scenarioFile: _sf, traceFile: _tf, frontendTrace: _ft, ...rest }) => {
-            const row = await attachReuseOutcome(rest, stateData.reuseOutcomes, stateData.reuseHandOffs, retrofitViews, reuseBlocking, declinesBySpec.get(path.basename(rest.fileName)) ?? [], consumedDeclines, evaluatedDeclineFiles, undefined, generatedPathFor(rest.fileName, stateData.generatedTests ?? {}));
+            const row = await attachReuseOutcome(rest, reuseRowContext, declinesBySpec.get(path.basename(rest.fileName)) ?? [], undefined, generatedPathFor(rest.fileName, stateData.generatedTests ?? {}));
             return attachAssertionOutcome(row, stateData.assertionOutcomes ?? {}, assertionCheckouts);
         }));
         const maintenanceRows = testMaintenance
@@ -1952,7 +2043,7 @@ export function registerSubmitReportTool(server) {
                         ? { editedFileName: path.basename(pomFile) }
                         : {}),
                     ...(assertions ? { assertions } : {}),
-                }, stateData.reuseOutcomes, stateData.reuseHandOffs, retrofitViews, reuseBlocking, declinesBySpec.get(path.basename(testFilePath)) ?? [], consumedDeclines, evaluatedDeclineFiles, testFilePath, 
+                }, reuseRowContext, declinesBySpec.get(path.basename(testFilePath)) ?? [], testFilePath, 
                 // Only where the run edited the file and left a test standing.
                 // VERIFY and IGNORE read a repository-owned test and changed nothing,
                 // and DELETE removed it — none of the three has reuse to state, so a

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

@@ -13,6 +13,7 @@ import { REBASELINE_SNAPSHOT_NAME_RE, looksLikeOnDiskBaselineName, } from "../..
 import { buildRenameStrategy, buildFileRenameStrategy, buildUpdateStrategy, buildRebaselineStrategy, buildRegenerateStrategy, buildDeleteStrategy, buildUpdateFileInstruction, buildRegenerateFileInstruction, } from "../../prompts/test-maintenance/actionsInstructions.js";
 import { buildModularizeFirstNextSteps, isMaintenanceRegenerable, isModularizeFirstHandOffTarget, regenerateCodeReuse, } from "../../prompts/reuse-hand-off.js";
 import { recordReuseHandOff } from "../code-refactor/reuse-state.js";
+import { isPomFirstTarget } from "../../utils/reuseRouting.js";
 import { isPlanOnlyMode } from "../../utils/planOnlyMode.js";
 import { runTestCall } from "../../skills/runTestSkill.js";
 import { formatOwedFiles, testsOwedBeforeRun } from "./testsOwedBeforeRun.js";
@@ -612,6 +613,12 @@ export function registerActionsTool(server) {
                 if (!isModularizeFirstHandOffTarget(testType, language))
                     return undefined;
                 const framework = cataloged?.framework ?? "";
+                // Both reuse settings on: a maintained browser test is not composed here.
+                // The maintenance step edits the customer's page objects directly and never
+                // runs the page-object pass, so arming the pair would move the steps it just
+                // pointed at page-object members into a shared module. Generation composes.
+                if (isPomFirstTarget(language, testType))
+                    return undefined;
                 await recordReuseHandOff([rec.testFilePath], testType, language, framework, args.stateFile, "maintenance");
                 return buildModularizeFirstNextSteps({
                     testType,

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

@@ -823,6 +823,7 @@ export declare function buildRegistration(params: RegisterTestPlanParams, regist
  * case-sensitive one, so that is the answer a real run gets.
  */
 export declare function makeCitedFileCheck(state: RunState): (relativePath: string, repository?: string) => boolean;
+export declare function makeSpecFileReader(state: RunState): (relativePath: string) => string | undefined;
 /**
  * The route patterns that render a changed frontend file, across every repository
  * of the run.

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

@@ -8,6 +8,7 @@ import { StateManager, resolveOwnRunStatePath, } from "../../utils/AnalysisState
 import { toolError } from "../../utils/utils.js";
 import { TESTBOT_SUPPORTED_TEST_TYPES } from "../../types/TestTypes.js";
 import { changedFileNames, computeBranchDiff, } from "../../utils/branchDiff.js";
+import { collectChangedRuns } from "../../utils/changedRuns.js";
 import { LOCKFILE, NOT_SOURCE_DIR, } from "../../recommendation/verifiers/endpointGrounded.js";
 import { hasUITestTypeLabel, isHTTPStep, } from "../../recommendation/subjectStep.js";
 import { STEP_METHOD_DESCRIPTION, isUiStepVerb, normalizeStepMethod, stepMethodSchema, } from "../../types/StepMethod.js";
@@ -15,7 +16,7 @@ import { registerPlan } from "../../recommendation/registerPlan.js";
 import { targetElementSchema } from "../submitReportTool.js";
 import { capturedBlueprintDigests } from "../../playwright/blueprintDigestStore.js";
 import { pullRequestText } from "../../recommendation/pullRequestText.js";
-import { fileExistsWithinRoot } from "../../utils/containedPath.js";
+import { fileExistsWithinRoot, readFileWithinRoot, } from "../../utils/containedPath.js";
 import { createScreenRouteResolver } from "../../utils/screenRoutes.js";
 import { categoryMenu, SCENARIO_CATEGORIES, } from "../../types/TestRecommendation.js";
 const TOOL_NAME = TOOL_REGISTER_TEST_PLAN;
@@ -397,10 +398,17 @@ const registerTestPlanSchema = {
             .describe("The requirement in the words the pull request uses, when `source` is `pr-title` or `pr-description`. CHECKED on a change a `requirement_conflict` test cites: the quote must appear in the title or description."),
         source: z
             .string()
-            .refine((value) => /^(pr-title|pr-description|diff|spec:\S.*)$/i.test(value.trim()), {
+            .refine((value) => /^(pr-title|pr-description(#\d+(,\d+)*)?|diff|spec:\S.*)$/i.test(value.trim()), {
             message: "source must be `pr-title`, `pr-description`, `diff`, or `spec:<path>`",
         })
-            .describe("Where you read it: `pr-title`, `pr-description`, `spec:<path>` for a requirements file the description names, or `diff`."),
+            .describe("Where you read it: `pr-title`, `pr-description`, `spec:<path>` for a requirements file the description names or the diff adds, or `diff`. If the requirement is an item of a numbered or bulleted list, add its number: `spec:<path>#11` or `pr-description#3` (`#7,8` when one change covers two items). Number a bulleted list from 1."),
+        lines: z
+            .array(z
+            .string()
+            .regex(/^.+:\d+(-\d+)?$/, "a `lines` entry is `path:12` or `path:12-20`"))
+            .min(1)
+            .optional()
+            .describe("The changed lines this change is, as `path:12` or `path:12-20` in the new file's numbering, the path from the repository root. Every run of changed lines in a file a planned test covers belongs to some change, and that change states in a case what a test must see."),
         surfaces: z
             .array(z.enum(["api", "page"]))
             .min(1)
@@ -434,7 +442,7 @@ const registerTestPlanSchema = {
                 message: "expectedFrom must be `pr-title`, `pr-description`, `code`, `spec:<path>`, or `convention:<file:line>`",
             })
                 .optional()
-                .describe("Where you read `expectedValue` or `derived`: `pr-title`, `pr-description`, `spec:<path>` for a requirements file the description names, `convention:<file:line>` for a rule the application already follows in code this pull request did not change, or `code` for the code under test. `code` draws an objection — it is the one source that agrees with a defect — so name it only when nothing else states the value. A value read from the pull request has to be WRITTEN there — in the quoted sentence or elsewhere in the title or description. If the pull request states the rule and never writes the number, leave `expectedValue` out and put the rule in `derived`. A case that declares `expectedValue` or `derived` and names no source here draws an objection."),
+                .describe("Where you read `expectedValue` or `derived`: `pr-title`, `pr-description`, `spec:<path>` for a requirements file the description names, `convention:<file:line>` for a rule the application already follows in code this pull request did not change, or `code` for the code under test. `code` draws an objection — it is the one source that agrees with a defect — so name it only when nothing else states the value. On a change whose `source` is `diff` and whose `lines` name changed lines in a file a planned test covers, `code` is accepted: the diff is the only source such a change has. A value read from the pull request has to be WRITTEN there — in the quoted sentence or elsewhere in the title or description. If the pull request states the rule and never writes the number, leave `expectedValue` out and put the rule in `derived`. A case that declares `expectedValue` or `derived` and names no source here draws an objection."),
         })
             .strict()
             .refine((entry) => (entry.value !== undefined) !== (entry.absent === true), {
@@ -579,7 +587,7 @@ const registerTestPlanSchema = {
         blocker: z
             .string()
             .optional()
-            .describe("What stopped this run from writing the test: a service that is not running, a paired branch that no longer exists, the one credential the run holds. An objection about a change or a defect with no test closes only with this. A reason the change is not worth testing is not a blocker."),
+            .describe("What stopped this run from writing the test: a service that is not running, a paired branch that no longer exists, the one credential the run holds. An objection about a change or a defect with no test, or about a value a page and API change refuses that no UI test names, closes only with this. A reason the change is not worth testing is not a blocker."),
     })
         .strict())
         .default([])
@@ -645,20 +653,8 @@ function repoSections(state) {
         })),
     ];
 }
-/**
- * Whether a cited repository file EXISTS inside the checkout. Reads no content,
- * and never throws: a bad citation is an objection, not a crashed tool.
- *
- * CONFINEMENT IS THIS FUNCTION'S JOB. The sibling verifier's string check misses
- * `file://` and `http://` URLs, a drive-relative `C:routes.rb` and a
- * percent-encoded `..`, so the containment in `containedPath` is the only thing
- * between an agent-written path and a read outside the checkout.
- *
- * CASE IS THE FILESYSTEM'S RULE: a case-only misspelling passes on a
- * case-insensitive checkout and is not found on a case-sensitive one. CI is the
- * case-sensitive one, so that is the answer a real run gets.
- */
-export function makeCitedFileCheck(state) {
+/** The real path of each repository's checkout, keyed by `owner/repo`. */
+function checkoutPathByRepo(state) {
     // Keyed by `owner/repo`, like `makeScreenRouteResolver`: two repositories can hold
     // the same relative path.
     const rootsByRepo = new Map();
@@ -674,6 +670,23 @@ export function makeCitedFileCheck(state) {
             // A repository path that no longer resolves holds no readable file.
         }
     }
+    return rootsByRepo;
+}
+/**
+ * Whether a cited repository file EXISTS inside the checkout. Reads no content,
+ * and never throws: a bad citation is an objection, not a crashed tool.
+ *
+ * CONFINEMENT IS THIS FUNCTION'S JOB. The sibling verifier's string check misses
+ * `file://` and `http://` URLs, a drive-relative `C:routes.rb` and a
+ * percent-encoded `..`, so the containment in `containedPath` is the only thing
+ * between an agent-written path and a read outside the checkout.
+ *
+ * CASE IS THE FILESYSTEM'S RULE: a case-only misspelling passes on a
+ * case-insensitive checkout and is not found on a case-sensitive one. CI is the
+ * case-sensitive one, so that is the answer a real run gets.
+ */
+export function makeCitedFileCheck(state) {
+    const rootsByRepo = checkoutPathByRepo(state);
     return (relativePath, repository) => {
         if (typeof relativePath !== "string")
             return false;
@@ -688,6 +701,19 @@ export function makeCitedFileCheck(state) {
         return [...new Set(rootsByRepo.values())].some((root) => fileExistsWithinRoot(root, cited));
     };
 }
+/** A requirements file is a page of prose; past this it is not one. */
+const SPEC_FILE_MAX_BYTES = 256 * 1024;
+export function makeSpecFileReader(state) {
+    const roots = [...new Set(checkoutPathByRepo(state).values())];
+    return (relativePath) => {
+        for (const root of roots) {
+            const text = readFileWithinRoot(root, relativePath, SPEC_FILE_MAX_BYTES);
+            if (text !== undefined)
+                return text;
+        }
+        return undefined;
+    };
+}
 /**
  * The route patterns that render a changed frontend file, across every repository
  * of the run.
@@ -719,14 +745,34 @@ export function makeScreenRouteResolver(state) {
 /** Which files each repository's branch diff changed. NAMES ONLY, never persisted.
  *  Lockfiles and non-source directories are dropped, so a planned test cannot cite
  *  `package-lock.json` and nothing demands a test for one. */
+/** The runs of changed lines, read from the full diff against the ref the name
+ *  listing resolved, so both describe the same comparison. A failure costs only
+ *  the changed-lines check: the file names still reach every other one. */
+async function changedRunsAgainst(repositoryPath, baseBranch) {
+    try {
+        const diff = await computeBranchDiff(repositoryPath, baseBranch, false);
+        return collectChangedRuns(diff.diffContent).filter((run) => !(LOCKFILE.test(run.file) || NOT_SOURCE_DIR.test(run.file)));
+    }
+    catch (error) {
+        logger.warning("Verify-time diff failed; the changed-lines check sees no changed lines", {
+            repositoryPath,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return [];
+    }
+}
 async function changedFilesForVerification(section) {
     const repositoryPath = section.repositoryPath;
     if (!repositoryPath || repositoryPath === "unknown")
         return undefined;
     const baseBranch = section.data?.repositoryAnalysis?.diff?.baseBranch;
     try {
-        const files = changedFileNames(await computeBranchDiff(repositoryPath, baseBranch, false, true)).filter((file) => !(LOCKFILE.test(file.path) || NOT_SOURCE_DIR.test(file.path)));
-        return files.length > 0 ? files : undefined;
+        const diff = await computeBranchDiff(repositoryPath, baseBranch, false, true);
+        const files = changedFileNames(diff).filter((file) => !(LOCKFILE.test(file.path) || NOT_SOURCE_DIR.test(file.path)));
+        return {
+            files: files.length > 0 ? files : undefined,
+            runs: await changedRunsAgainst(repositoryPath, diff.baseBranch),
+        };
     }
     catch (error) {
         // A repository git cannot read yields no changed files, which
@@ -756,10 +802,11 @@ export async function buildVerifyContext(state) {
     // Per repository, so a planned test is checked against the one it names. Every
     // planned test names one; a single-repository run names that one repository.
     return {
-        changedFiles: Object.fromEntries(sections.map((section, i) => [section.repo, listings[i] ?? []])),
+        changedFiles: Object.fromEntries(sections.map((section, i) => [section.repo, listings[i]?.files ?? []])),
         reposWithoutDiff: sections
-            .filter((_s, i) => !listings[i]?.length)
+            .filter((_s, i) => !listings[i]?.files?.length)
             .map((s) => s.repo),
+        changedRuns: Object.fromEntries(sections.map((section, i) => [section.repo, listings[i]?.runs ?? []])),
         // From the process, not the state file: the browser tools and this one are
         // registered on the same server, so captures and reader share a process.
         uiCaptures: capturedBlueprintDigests(),
@@ -772,6 +819,7 @@ export async function buildVerifyContext(state) {
         removedUiElements: sections.flatMap((section) => section.data?.uiContext?.removedElements ?? []),
         retiredUiElements: sections.flatMap((section) => section.data?.uiContext?.retiredElements ?? []),
         citedFileExists: makeCitedFileCheck(state),
+        readSpecFile: makeSpecFileReader(state),
         routesRenderingFile: makeScreenRouteResolver(state),
     };
 }