@skyramp/mcp 0.4.1 → 0.4.2-rc.2

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

@@ -4,36 +4,48 @@ import * as path from "path";
 import { TOOL_REGISTER_TEST_PLAN } from "../../toolNames.js";
 import { logger } from "../../utils/logger.js";
 import { canonicalJson, isPlainObject } from "../../utils/canonicalJson.js";
-import { StateManager, resolveRunStatePath } from "../../utils/AnalysisStateManager.js";
+import { StateManager, resolveOwnRunStatePath, } from "../../utils/AnalysisStateManager.js";
 import { toolError } from "../../utils/utils.js";
-import { TestType } from "../../types/TestTypes.js";
-import { changedFileNames, computeBranchDiff } from "../../utils/branchDiff.js";
-import { LOCKFILE, NOT_SOURCE_DIR } from "../../recommendation/verifiers/endpointGrounded.js";
-import { hasUITestTypeLabel, isHTTPStep } from "../../recommendation/subjectStep.js";
-import { STEP_METHOD_DESCRIPTION, normalizeStepMethod, stepMethodSchema } from "../../types/StepMethod.js";
+import { TESTBOT_SUPPORTED_TEST_TYPES } from "../../types/TestTypes.js";
+import { changedFileNames, computeBranchDiff, } from "../../utils/branchDiff.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";
 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 { createScreenRouteResolver } from "../../utils/screenRoutes.js";
-import { categoryMenu, SCENARIO_CATEGORIES } from "../../types/TestRecommendation.js";
+import { categoryMenu, SCENARIO_CATEGORIES, } from "../../types/TestRecommendation.js";
 const TOOL_NAME = TOOL_REGISTER_TEST_PLAN;
 // ── Zod schema ──────────────────────────────────────────────────────────────
 /** One sentence, shared by the step fields that carry a value and by the case
  *  that names one, so the two sides state the same convention. A plan that spells
  *  the same created value two different ways reads as a case no step sends. */
 const CREATED_VALUE_PLACEHOLDER = "Write a value an earlier step creates as a placeholder in braces, and use the same name wherever else the test names it.";
-const registerStepSchema = z.object({
-    order: z.number().int().positive().describe("This step's position in the scenario, from 1. `stepUnderTest` and `routes` name a step by this number."),
+const registerStepSchema = z
+    .object({
+    order: z
+        .number()
+        .int()
+        .positive()
+        .describe("This step's position in the scenario, from 1. `stepUnderTest` and `routes` name a step by this number."),
     method: stepMethodSchema.describe(`${STEP_METHOD_DESCRIPTION} A \`ui\` or \`e2e\` step is a page interaction.`),
     path: z
         .string()
-        .refine((value) => value.trim().length > 0, { message: "path must not be blank" })
+        .refine((value) => value.trim().length > 0, {
+        message: "path must not be blank",
+    })
         .describe("Request path as the running service serves it, mount prefix included — `/ghost/api/admin/site/stats`, not the `/site/stats` the router file declares. For a page interaction, its target instead (`checkout button`); for an `OPERATION` step, the operation's name."),
-    description: z.string().optional().describe("What this step does, in one line."),
-    interactionType: z.string().optional().describe("success, error, or another label for what this step exercises."),
-    requestBody: z.unknown().optional().describe(`Request payload for this step, when it sends one. ${CREATED_VALUE_PLACEHOLDER}`),
+    description: z
+        .string()
+        .optional()
+        .describe("What this step does, in one line."),
+    requestBody: z
+        .unknown()
+        .optional()
+        .describe(`Request payload for this step, when it sends one. ${CREATED_VALUE_PLACEHOLDER}`),
     queryParams: z
         .unknown()
         .optional()
@@ -43,7 +55,11 @@ const registerStepSchema = z.object({
         .min(1)
         .optional()
         .describe("Parameters this step leaves out on purpose."),
-    expectedStatusCode: z.number().int().optional().describe("Status code this step expects."),
+    expectedStatusCode: z
+        .number()
+        .int()
+        .optional()
+        .describe("Status code this step expects."),
 })
     // A `navigate` step's path is the screen the runner opens, so it has to be a
     // thing a browser can be pointed at. Runs have written "the login page" there,
@@ -53,7 +69,67 @@ const registerStepSchema = z.object({
         return true;
     const target = step.path.trim().toLowerCase();
     return target.startsWith("/") || target.startsWith("http");
-}, { message: "a navigate step's path is a URL path such as /login", path: ["path"] });
+}, {
+    message: "a navigate step's path is a URL path such as /login",
+    path: ["path"],
+})
+    // A page interaction sends no request, so these four describe one that is not
+    // there. Accepting them let a step read as an asserted response while the runner
+    // only clicked. `OPERATION` is untouched: it calls the app without an HTTP verb.
+    .superRefine((step, ctx) => {
+    if (!isUiStepVerb(step.method))
+        return;
+    for (const field of [
+        "requestBody",
+        "queryParams",
+        "omits",
+        "expectedStatusCode",
+    ]) {
+        if (step[field] === undefined)
+            continue;
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [field],
+            message: `\`${field}\` belongs to a step that sends a request; \`${step.method}\` is a page interaction, which sends none. Assert the page through \`declarations.elements\`, or write the request as its own step.`,
+        });
+    }
+});
+/** The `owner/repo` a plan entry names. The SHAPE is checked, not just "not blank":
+ *  a run keys each repository by the slug read off its origin remote. */
+function repositorySlugField(subject, purpose) {
+    return z
+        .string()
+        .trim()
+        .regex(/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/, {
+        message: `${subject}'s repository must be an \`owner/repo\` slug`,
+    })
+        .describe(`The github repository slug, \`owner/repo\`, ${purpose}.`);
+}
+/** The `changes` and `defects` id lists a plan entry cites, written once. The two
+ *  copies drifted whenever either was edited. */
+function citationFields({ changesSubject, defectsSubject, changesExtra = "", defectsExtra = "", }) {
+    const cite = (list, subject, extra) => `The ids of the declared ${list} this ${subject}, spelled as your own \`${list}\` list gives them.${extra}`;
+    return {
+        // BOTH required as returned. A planned test relaxes each with `.optional()`; a
+        // `maintains` entry states both, and either list may be empty.
+        changes: z
+            .array(z.string())
+            .describe(cite("changes", changesSubject, changesExtra)),
+        defects: z
+            .array(z.string())
+            .describe(cite("defects", defectsSubject, defectsExtra)),
+    };
+}
+const maintainedCitations = citationFields({
+    changesSubject: "maintenance covers",
+    defectsSubject: "maintained test proves",
+});
+const plannedTestCitations = citationFields({
+    changesSubject: "test proves",
+    defectsSubject: "test proves",
+    changesExtra: " This test proves one behaviour: list the id of every change that the behaviour covers. The server checks that each declared change has a planned test that cites it, or an answer. The server does not check that the test exercises the change. CHECKED on a `requirement_conflict` test: at least one cited change must have been read from the pull request or a requirements file, never only from the diff.",
+    defectsExtra: " The server checks that each declared defect has a planned test that cites it and expects to fail, or a blocker naming what stopped the test. The server does not check that the test reaches the defect. CHECKED on a `requirement_conflict` test: it must cite at least one defect.",
+});
 // The fields `declarations` accepts. Named on its own so one list of them can be
 // derived from it — a hand-written second copy had already fallen behind.
 export const declarationFieldsSchema = z.object({
@@ -61,17 +137,12 @@ export const declarationFieldsSchema = z.object({
         .string()
         .optional()
         .describe("The changed file this test is about, repository-relative and spelled as the diff spells it — `src/routes/orders.ts`, not `./src/routes/orders.ts`. Checked: the name is one this pull request changed. Not checked: which line, so name the changed line in `description`."),
-    changes: z
-        .array(z.string())
-        .optional()
-        .describe("The ids of the changes that this test proves. Take the ids from your `changes` list. This test proves one behaviour: list the id of every change that the behaviour covers. The server checks that each declared change has a planned test that cites it, or an answer. The server does not check that the test exercises the change. CHECKED on a `requirement_conflict` test: at least one cited change must have been read from the pull request or a requirements file, never only from the diff."),
-    defects: z
-        .array(z.string())
-        .optional()
-        .describe("The ids of the defects that this test proves. Take the ids from your `defects` list. The server checks that each declared defect has a planned test that cites it and expects to fail, or a blocker naming what stopped the test. The server does not check that the test reaches the defect. CHECKED on a `requirement_conflict` test: it must cite at least one defect."),
-    asserts: z
-        .string()
-        .describe("What this test checks."),
+    // A planned test may cite no change and no defect. A `maintains` entry always
+    // states `changes`, and the list may be EMPTY: an entry that only proves defects
+    // covers no change.
+    changes: plannedTestCitations.changes.optional(),
+    defects: plannedTestCitations.defects.optional(),
+    asserts: z.string().describe("What this test checks."),
     stepUnderTest: z
         .number()
         .int()
@@ -89,17 +160,27 @@ export const declarationFieldsSchema = z.object({
         .strict()
         .describe("What this test does against the app as it stands, and why."),
     differsFrom: z
-        .array(z.object({
-        plannedTestId: z.string().describe("The other planned test this one is distinct from, named by its `scenarioName`."),
+        .array(z
+        .object({
+        plannedTestId: z
+            .string()
+            .describe("The other planned test this one is distinct from, named by its `scenarioName`."),
         difference: z.string().describe("How the two differ."),
-    }).strict())
+    })
+        .strict())
         .optional()
         .describe("For another planned test in THIS plan whose subject step calls the same method and path, what this one asserts that it does not."),
     existingTests: z
-        .array(z.object({
-        file: z.string().describe("Repository-relative path of an existing test you read that exercises this change."),
-        differsBy: z.string().describe("What this planned test checks that the existing test does not."),
-    }).strict())
+        .array(z
+        .object({
+        file: z
+            .string()
+            .describe("Repository-relative path of an existing test you read that exercises this change."),
+        differsBy: z
+            .string()
+            .describe("What this planned test checks that the existing test does not."),
+    })
+        .strict())
         .optional()
         .describe("The existing tests you read on this change. Naming none is an answer. Checked: each file named is in the checkout. Not checked: what the file contains."),
     startState: z
@@ -107,15 +188,24 @@ export const declarationFieldsSchema = z.object({
         .optional()
         .describe("The state the record this test mutates is in when the mutation runs, in one sentence. A record with no rows yet is a state. The test puts the record in that state itself. Checked: present. Not checked: the sentence."),
     routes: z
-        .array(z.object({
-        step: z.number().int().describe("The `order` of the step this file declares."),
-        file: z.string().describe("Repository-relative path of the file that declares what that step calls."),
-    }).strict())
+        .array(z
+        .object({
+        step: z
+            .number()
+            .int()
+            .describe("The `order` of the step this file declares."),
+        file: z
+            .string()
+            .describe("Repository-relative path of the file that declares what that step calls."),
+    })
+        .strict())
         .optional()
         .describe("One entry per step that calls the app, naming the repository file that declares what it calls. Checked: the file is in the checkout. Not checked: whether the route appears in it — frameworks build paths from scopes and prefixes, so it often does not."),
     screenEvidence: z
         .object({
-        file: z.string().describe("Repository-relative path of the changed file that renders this screen."),
+        file: z
+            .string()
+            .describe("Repository-relative path of the changed file that renders this screen."),
     })
         .strict()
         .optional()
@@ -147,7 +237,11 @@ const declarationsSchema = declarationFieldsSchema
     if (!Array.isArray(items))
         return;
     items.forEach((element, index) => {
-        const identifies = [element.accessibleName, element.testId, element.stableId].some((value) => typeof value === "string" && value.trim().length > 0);
+        const identifies = [
+            element.accessibleName,
+            element.testId,
+            element.stableId,
+        ].some((value) => typeof value === "string" && value.trim().length > 0);
         if (identifies)
             return;
         ctx.addIssue({
@@ -157,8 +251,6 @@ const declarationsSchema = declarationFieldsSchema
         });
     });
 });
-// A plan drafts only these four; `TestType`'s others are maintenance outcomes.
-const PLAN_TEST_TYPES = [TestType.CONTRACT, TestType.INTEGRATION, TestType.E2E, TestType.UI];
 /** Whether an `elements.pageUrl` names a screen `uiElementGrounded` can look up: a
  *  route path or an absolute http URL. Constrained here and never on the shared
  *  `pageContextSchema`, which the report fills from a capture carrying any url. */
@@ -189,7 +281,9 @@ export function hoistDeclarationFields(value) {
     if (value.declarations !== undefined && !isPlainObject(value.declarations))
         return value;
     const plannedTest = { ...value };
-    const original = isPlainObject(plannedTest.declarations) ? plannedTest.declarations : undefined;
+    const original = isPlainObject(plannedTest.declarations)
+        ? plannedTest.declarations
+        : undefined;
     const declarations = { ...(original ?? {}) };
     let hoisted = false;
     for (const field of DECLARATION_FIELDS) {
@@ -211,21 +305,23 @@ export function hoistDeclarationFields(value) {
         plannedTest.declarations = declarations;
     return plannedTest;
 }
-const registerPlannedTestSchema = z.preprocess(hoistDeclarationFields, z.object({
+const registerPlannedTestSchema = z.preprocess(hoistDeclarationFields, z
+    .object({
     scenarioName: z
         .string()
-        .refine((value) => value.trim().length > 0, { message: "scenarioName must not be blank" })
+        .refine((value) => value.trim().length > 0, {
+        message: "scenarioName must not be blank",
+    })
         .describe("Short name for this test, and its id: objections name it, `differsFrom` refers to it, and the report joins delivered tests on it. Keep it stable across registrations."),
-    repository: z
+    repository: repositorySlugField("a planned test", "which has the change this test is targeting"),
+    description: z
         .string()
-        .optional()
-        .describe("On a multi-repo run, the `owner/repo` this test is for — the same value you passed to `skyramp_analyze_changes`."),
-    description: z.string().describe("What this test does, in one or two lines."),
+        .describe("What this test does, in one or two lines."),
     category: z
         .enum(SCENARIO_CATEGORIES)
         .describe(`What kind of test this is. Write one of:\n${categoryMenu()}`),
     testType: z
-        .enum(PLAN_TEST_TYPES)
+        .enum(TESTBOT_SUPPORTED_TEST_TYPES)
         .describe("contract, integration, e2e or ui."),
     steps: z
         .array(registerStepSchema)
@@ -275,9 +371,11 @@ const registerPlannedTestSchema = z.preprocess(hoistDeclarationFields, z.object(
 const registerTestPlanSchema = {
     stateFile: z
         .string()
-        .refine((p) => path.isAbsolute(p), { message: "stateFile must be an absolute path" })
+        .refine((p) => path.isAbsolute(p), {
+        message: "stateFile must be an absolute path",
+    })
         .optional()
-        .describe("Optional. A Testbot run finds its own state file, so leave this out. Give an absolute path only to name a state file the run would not find by itself."),
+        .describe("Optional, and a Testbot run leaves it out: the run finds its own state file. A path is accepted only when it names that same file — one from another run holds another run's analysis and plan, and the call is refused."),
     // `.default([])`, where `plannedTests` is required: an empty list here cannot pass
     // in silence the way an empty planned test list did. It raises `coverage:noChanges`,
     // which is exactly the objection a plan that states no change should draw.
@@ -286,9 +384,13 @@ const registerTestPlanSchema = {
         .object({
         id: z
             .string()
-            .refine((value) => value.trim().length > 0, { message: "a change id must not be blank" })
+            .refine((value) => value.trim().length > 0, {
+            message: "a change id must not be blank",
+        })
             .describe("Short slug for this change. A planned test cites it by this id."),
-        text: z.string().describe("The change in one sentence, as the pull request must make it."),
+        text: z
+            .string()
+            .describe("The change in one sentence, as the pull request must make it."),
         quote: z
             .string()
             .optional()
@@ -303,7 +405,7 @@ const registerTestPlanSchema = {
             .array(z.enum(["api", "page"]))
             .min(1)
             .describe("Where a user or caller meets this change: `api` for a request and response, `page` for something rendered, both when both."),
-        cases: z
+        testCases: z
             .array(z
             .object({
             param: z.string().describe("The parameter this case sets."),
@@ -311,7 +413,10 @@ const registerTestPlanSchema = {
                 .union([z.string(), z.number(), z.boolean(), z.null()])
                 .optional()
                 .describe(`The value a test sends for that parameter. ${CREATED_VALUE_PLACEHOLDER}`),
-            absent: z.literal(true).optional().describe("The parameter is left out of the request."),
+            absent: z
+                .literal(true)
+                .optional()
+                .describe("The parameter is left out of the request."),
             expect: z
                 .enum(["accept", "reject"])
                 .describe("Whether the route must accept this value or reject it."),
@@ -337,11 +442,14 @@ const registerTestPlanSchema = {
         })
             // The description called them alternatives and the schema took both,
             // which left generation told to pin a number AND to compute it.
-            .refine((entry) => entry.expectedValue === undefined || String(entry.derived ?? "").trim().length === 0, {
+            .refine((entry) => entry.expectedValue === undefined ||
+            String(entry.derived ?? "").trim().length === 0, {
             message: "a case states either `expectedValue` or `derived`, never both: `derived` is the case saying no source writes the value",
             path: ["derived"],
         }))
-            .min(1, { message: "a `cases` list with no entry states no input — leave it out instead" })
+            .min(1, {
+            message: "a `testCases` list with no entry states no input — leave it out instead",
+        })
             .optional()
             .describe("The inputs that prove this change: for each parameter the change constrains, the values the route must accept and the values it must reject. A range gives the last accepted value and the first rejected one at each end; a set gives each allowed value and one outside it; a required field gives the field left out. A case names a query parameter, a body field, a path segment, or `method` for the HTTP verb; the steps of the test that cites this change say which route it is, and a rejection that depends on who calls belongs in the change text instead."),
     })
@@ -373,10 +481,19 @@ const registerTestPlanSchema = {
         .object({
         id: z
             .string()
-            .refine((value) => value.trim().length > 0, { message: "a defect id must not be blank" })
+            .refine((value) => value.trim().length > 0, {
+            message: "a defect id must not be blank",
+        })
             .describe("Short id for this defect, such as `D1`. A planned test cites it by this id, and the report's `issuesFound` entry names it as `defectId`."),
-        file: z.string().describe("Repository-relative path of the file that holds the defect, spelled as the diff spells it."),
-        line: z.number().int().positive().optional().describe("1-based line of the wrong statement. Advisory; nothing checks it."),
+        file: z
+            .string()
+            .describe("Repository-relative path of the file that holds the defect, spelled as the diff spells it."),
+        line: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("1-based line of the wrong statement. Advisory; nothing checks it."),
         description: z.string().describe("What is wrong, in one line."),
         severity: z
             .enum(["critical", "high", "medium", "low"])
@@ -402,7 +519,7 @@ const registerTestPlanSchema = {
         });
     })
         .default([])
-        .describe("The defects your code review found in the code that serves each change, whether or not the diff contains the line. Every defect gets a planned test that cites it in `defects` and expects to fail, or a blocker naming what stopped the test. A pre-existing defect in a file this pull request touches belongs on this list. An empty list says the review found none; the check asks you to confirm that in one line. A requirement conflict is a defect: list it here, and the `requirement_conflict` test cites it."),
+        .describe("The defects your code review found in the code that serves each change, whether or not the diff contains the line. Every defect closes one of three ways: a planned test that cites it in `defects` and expects to fail, a `maintains` entry that cites it because your edit to an existing test covers it, or a blocker naming what stopped the test. A pre-existing defect in a file this pull request touches belongs on this list. An empty list says the review found none; the check asks you to confirm that in one line. A requirement conflict is a defect: list it here, and the `requirement_conflict` test cites it."),
     // REQUIRED, not `.default([])`. The MCP SDK wraps this shape in a plain
     // `z.object`, which STRIPS an undeclared top-level key, so with a default
     // `planned test:` for `planned tests:` stored an EMPTY plan and counted the
@@ -437,26 +554,34 @@ const registerTestPlanSchema = {
     maintains: z
         .array(z
         .object({
+        repository: repositorySlugField("a maintenance entry", "which holds the test this run edits"),
         file: z
             .string()
-            .describe("Repository-relative path of the existing test this run edits. It has to resolve in the checkout: a change is credited as covered only when it does, and `existingCoverage` objects when it does not."),
-        differsBy: z.string().describe("What your edit changes in that test, in one sentence."),
-        changes: z
-            .array(z.string())
-            .describe("The ids of the declared changes this maintenance covers, spelled as your own `changes` list gives them."),
+            .describe("Repository-relative path of the existing test this run edits. It has to resolve in the repository named above: a change is credited as covered only when it does, and `existingCoverage` objects when it does not."),
+        differsBy: z
+            .string()
+            .describe("What your edit changes in that test, in one sentence."),
+        changes: maintainedCitations.changes,
+        defects: maintainedCitations.defects,
     })
         .strict())
         .optional()
-        .describe("Existing tests this run edits instead of planning new ones. Coverage counts the changes these cite, so a change already covered by a spec you are updating needs no planned test — and a duplicate spec beside the one you edited is the mistake. Declare maintenance here even when the plan holds no planned tests at all: a maintenance-only plan is a complete plan."),
+        .describe("Existing tests this run edits instead of planning new ones. Coverage counts the changes these cite, and the defect check counts the defects they cite, so a change or a defect already covered by a spec you are updating needs no planned test — and a duplicate spec beside the one you edited is the mistake. Declare maintenance here even when the plan holds no planned tests at all: a maintenance-only plan is a complete plan."),
     answers: z
-        .array(z.object({
-        objectionId: z.string().describe("The objection's id, exactly as this tool reported it. Answers are matched by id, never by position."),
-        answer: z.string().describe("Why the objection does not apply, or what you decided instead."),
+        .array(z
+        .object({
+        objectionId: z
+            .string()
+            .describe("The objection's id, exactly as this tool reported it. Answers are matched by id, never by position."),
+        answer: z
+            .string()
+            .describe("Why the objection does not apply, or what you decided instead."),
         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."),
-    }).strict())
+    })
+        .strict())
         .default([])
         .describe("One answer per objection from your previous registration that you do not intend to fix. There is no registration limit."),
 };
@@ -487,14 +612,18 @@ export function buildRegistration(params, registrationNumber) {
                 // TRIMMED: the report side joins on `plannedTestId.trim()`.
                 plannedTestId: input.scenarioName.trim(),
                 scenario,
-                ...(input.repository ? { repository: input.repository } : {}),
+                repository: input.repository,
                 // Passed through, never rebuilt field by field: a field the schema accepts
                 // and this function forgot to copy was dead once. Absent stays absent, so
                 // a field the agent did not write reads back as missing, not as a default
                 // the checks would then judge. `elements: null` is the model's "not
                 // applicable" habit and is dropped; `elements.items: null` MEANS capture
                 // failed and is kept.
-                declarations: { ...rest, asserts: declared?.asserts ?? "", ...(elements ? { elements } : {}) },
+                declarations: {
+                    ...rest,
+                    asserts: declared?.asserts ?? "",
+                    ...(elements ? { elements } : {}),
+                },
             };
         }),
     };
@@ -504,7 +633,11 @@ function repoSections(state) {
     if (!state)
         return [];
     return [
-        { repo: state.metadata?.repository ?? "the primary repository", repositoryPath: state.metadata?.repositoryPath, data: state },
+        {
+            repo: state.metadata.repository,
+            repositoryPath: state.metadata?.repositoryPath,
+            data: state,
+        },
         ...Object.entries(state.relatedRepos ?? {}).map(([repo, section]) => ({
             repo,
             repositoryPath: section?.repositoryPath,
@@ -526,61 +659,61 @@ function repoSections(state) {
  * case-sensitive one, so that is the answer a real run gets.
  */
 export function makeCitedFileCheck(state) {
-    const roots = [];
+    // Keyed by `owner/repo`, like `makeScreenRouteResolver`: two repositories can hold
+    // the same relative path.
+    const rootsByRepo = new Map();
     for (const section of repoSections(state)) {
         // The literal "unknown" means unresolved; resolving against it would read
         // the process working directory instead of a checkout.
         if (!section.repositoryPath || section.repositoryPath === "unknown")
             continue;
         try {
-            const real = fs.realpathSync(section.repositoryPath);
-            if (!roots.includes(real))
-                roots.push(real);
+            rootsByRepo.set(section.repo, fs.realpathSync(section.repositoryPath));
         }
         catch {
             // A repository path that no longer resolves holds no readable file.
         }
     }
-    return (relativePath) => {
+    return (relativePath, repository) => {
         if (typeof relativePath !== "string")
             return false;
         const cited = relativePath.trim();
         if (!cited)
             return false;
-        return roots.some((root) => fileExistsWithinRoot(root, cited));
+        const named = String(repository ?? "").trim();
+        if (named) {
+            const root = rootsByRepo.get(named);
+            return root !== undefined && fileExistsWithinRoot(root, cited);
+        }
+        return [...new Set(rootsByRepo.values())].some((root) => fileExistsWithinRoot(root, cited));
     };
 }
 /**
  * The route patterns that render a changed frontend file, across every repository
  * of the run.
  *
- * Built like {@link makeCitedFileCheck}: one resolver per checkout, asked in turn,
- * so a planned test does not have to say which repository its file lives in. The
- * scan is lazy inside each resolver and reused across planned tests, so a plan with
- * ten UI tests reads a repository once.
+ * One resolver per checkout, keyed by repository, and only the named repository is
+ * asked. The scan is lazy inside each resolver and reused across planned tests, so
+ * a plan with ten UI tests reads a repository once.
  *
- * A repository that CAN speak for the file wins: `undefined` from a resolver means
- * "not my file, or not a framework I read", so it is skipped, and the first
- * definite answer is returned. Every resolver saying `undefined` is the answer the
- * check stays silent on.
+ * KEYED, not asked in turn, for the reason {@link changedFilesFor} is: two
+ * repositories can hold the same relative file, and answering from whichever was
+ * scanned first checked a planned test against another repository's routes.
+ *
+ * A repository this run does not know answers `undefined`, so the check stays
+ * silent — `changedFile:unknownRepository` is what objects to the name. There is no
+ * fallback for a single-repository run: every run keys its repositories by the
+ * `owner/repo` read off the origin remote, so the name is always matchable.
  */
 export function makeScreenRouteResolver(state) {
-    const resolvers = repoSections(state)
+    const resolvers = new Map(repoSections(state)
         .filter((section) => section.repositoryPath && section.repositoryPath !== "unknown")
-        .map((section) => createScreenRouteResolver(section.repositoryPath));
-    return (relativePath) => {
-        let unmounted;
-        for (const resolve of resolvers) {
-            const routes = resolve(relativePath);
-            if (routes === undefined)
-                continue;
-            // A non-empty answer is a fact about a real mount; an empty one is only the
-            // answer when no repository found a mount at all.
-            if (routes.length > 0)
-                return routes;
-            unmounted = routes;
-        }
-        return unmounted;
+        .map((section) => [
+        section.repo,
+        createScreenRouteResolver(section.repositoryPath),
+    ]));
+    return (relativePath, repository) => {
+        return resolvers.get(String(repository ?? "").trim())?.(relativePath);
     };
 }
 /** Which files each repository's branch diff changed. NAMES ONLY, never persisted.
@@ -620,12 +753,13 @@ function recordedPullRequest() {
 export async function buildVerifyContext(state) {
     const sections = repoSections(state);
     const listings = await Promise.all(sections.map((section) => changedFilesForVerification(section)));
-    // Per repository, so a planned test that names one is checked against it alone.
-    // A planned test that names none reads every entry, which is every planned test of a
-    // single-repository run.
+    // 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] ?? []])),
-        reposWithoutDiff: sections.filter((_s, i) => !listings[i]?.length).map((s) => s.repo),
+        reposWithoutDiff: sections
+            .filter((_s, i) => !listings[i]?.length)
+            .map((s) => s.repo),
         // 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(),
@@ -721,7 +855,7 @@ export function registerRegisterTestPlanTool(server) {
         description: "Register your complete test plan for this run, with the changes that make each planned test checkable. " +
             "The planning procedure in your prompt says how to decide and declare the plan. " +
             "Every registration the schema accepts is stored, and no check ever refuses one. " +
-            "The schema refuses the whole call on ordinary field validation, and on three rules that read more than one field: a non-UI planned test with an empty `steps` list, a `ui` or `e2e` planned test whose steps make no HTTP call and names no `elements.pageUrl`, and an `elements.items` entry carrying no name and no identifier. " +
+            "The schema refuses the whole call, and names the field and the rule that refused it. " +
             "An undeclared key is refused by name on a planned test and on `declarations`, so a declaration written one level too high is corrected rather than dropped in silence. " +
             "Checks run against the stored plan and return objections. Fix one and register it again as often as you like, or answer it by id through `answers`. " +
             "There is no fallback plan: if you never register, this run has no plan.",
@@ -729,7 +863,9 @@ export function registerRegisterTestPlanTool(server) {
     }, async (params) => {
         // The run's own state file, unless the agent named one. Outside a run there
         // is no path to fall back to, and no analysis to check a plan against.
-        const stateFile = resolveRunStatePath(params.stateFile);
+        const { path: stateFile, refusal } = resolveOwnRunStatePath(params.stateFile);
+        if (refusal)
+            return toolError(refusal);
         if (!stateFile) {
             return toolError("This run has no state file. Call skyramp_analyze_changes first — it writes the state file this plan is checked against.");
         }
@@ -749,13 +885,21 @@ export function registerRegisterTestPlanTool(server) {
                 const result = registerPlan(registration, await buildVerifyContext(fullState), fullState.plan);
                 try {
                     const { metadata: _metadata, relatedRepos: _sections, ...rootData } = fullState;
-                    await stateManager.writeData({ ...rootData, plan: result.plan, registrationCount: registrationNumber }, { step: TOOL_NAME });
+                    await stateManager.appendData({
+                        ...rootData,
+                        plan: result.plan,
+                        registrationCount: registrationNumber,
+                    }, { step: TOOL_NAME });
                 }
                 catch (error) {
                     return toolError(`Failed to persist the test plan to the state file: ${error.message}. Retry this call.`);
                 }
                 logger.info(`${TOOL_NAME}: registration ${registrationNumber}, ${result.plan.plannedTests.length} planned test(s), ${result.objections.length} objection(s)`);
-                return { content: [{ type: "text", text: renderPlanResult(result) }] };
+                return {
+                    content: [
+                        { type: "text", text: renderPlanResult(result) },
+                    ],
+                };
             }
             catch (error) {
                 return toolError(`${TOOL_NAME} failed: ${error?.message ?? String(error)}`);