@skyramp/mcp 0.3.8 → 0.4.0-rc.1

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

@@ -1,608 +1,675 @@
 import { z } from "zod";
-import { TOOL_BATCH_SCENARIO_TEST_GENERATION, TOOL_CONTRACT_TEST_GENERATION, TOOL_E2E_TEST_GENERATION, TOOL_INTEGRATION_TEST_GENERATION, TOOL_REGISTER_TEST_PLAN, TOOL_UI_TEST_GENERATION, } from "../../toolNames.js";
+import * as fs from "fs";
 import * as path from "path";
-import * as crypto from "crypto";
+import { TOOL_REGISTER_TEST_PLAN } from "../../toolNames.js";
 import { logger } from "../../utils/logger.js";
-import { StateManager, } from "../../utils/AnalysisStateManager.js";
+import { StateManager, resolveRunStatePath } from "../../utils/AnalysisStateManager.js";
 import { toolError } from "../../utils/utils.js";
-import { buildApprovedPlanItem } from "../../utils/planMatchKeys.js";
-import { SCENARIO_CATEGORIES, CATEGORY_PRIORITY, Novelty, PriorityTier } from "../../types/TestRecommendation.js";
-import { HttpMethod, TestType } from "../../types/TestTypes.js";
-import { CandidateSource, computeCandidateId, scenarioMergeKey, DiscriminatorKind } from "../../types/Recommendation.js";
-import { selectPlan } from "../../recommendation/planRanker.js";
-import { resolveSubjectEndpoints } from "../../utils/subjectEndpoints.js";
-import { collectChangedRouteLines } from "../../utils/changedRoutes.js";
-import { generateFloors } from "../../recommendation/budgeters/shared.js";
-import { inferScenarioType } from "../../recommendation/diversity.js";
-import { validateDiscriminator } from "../../recommendation/discriminators.js";
-import { isAttackSurfaceSecurityBoundary } from "../../prompts/test-recommendation/recommendationShared.js";
-import { MAX_RECOMMENDATIONS, MAX_TESTS_TO_GENERATE } from "../../prompts/test-recommendation/recommendationSections.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 { registerPlan } from "../../recommendation/registerPlan.js";
+import { targetElementSchema } from "../submitReportTool.js";
+import { capturedBlueprintDigests } from "../../playwright/blueprintDigestStore.js";
+import { fileExistsWithinRoot } 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;
 // ── Zod schema ──────────────────────────────────────────────────────────────
-/** Test types eligible for a registered test plan — a subset of TestType
- *  (excludes smoke/fuzz/load/mock/unit/unknown, which this checkpoint doesn't
- *  govern). */
-const PLAN_TEST_TYPES = new Set([
-    TestType.CONTRACT,
-    TestType.INTEGRATION,
-    TestType.E2E,
-    TestType.UI,
-]);
-const chainingRefSchema = z.object({
-    sourceStep: z.number().int(),
-    sourceField: z.string(),
-    sourceLocation: z.enum(["body", "header", "cookie"]),
-    targetParam: z.string(),
-    targetLocation: z.enum(["path", "body", "query", "header", "cookie"]),
-});
+/** 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().min(1).describe("Order of this step within the scenario, starting at 1."),
-    method: z.nativeEnum(HttpMethod).describe("HTTP method of this step's request."),
-    path: z.string().describe("Endpoint path, e.g. '/api/v1/products/{product_id}'."),
-    description: z.string().describe("What this step does."),
-    interactionType: z
-        .enum(["success", "error", "edge-case"])
-        .describe("Whether this step exercises the happy path, an expected error, or an edge case."),
-    requestBody: z
-        .record(z.any())
-        .optional()
-        .describe("Request body fields with concrete values. Used to verify boundary_equality claims (two distinct fields with equal values)."),
+    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" })
+        .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}`),
     queryParams: z
-        .record(z.any())
-        .optional()
-        .describe("Query parameters with concrete values. Also scanned for boundary_equality and negative_match verification."),
-    responseBody: z
-        .union([z.record(z.any()), z.array(z.any())])
+        .unknown()
         .optional()
-        .describe("Expected response body shape/values, when asserted. An array for a collection/list endpoint that returns a JSON array."),
-    expectedStatusCode: z.number().int().describe("HTTP status code this step asserts (e.g. 201, 400, 404)."),
-    expectedResponseFields: z
+        .describe(`Query-string parameters for this step, when it sends any. ${CREATED_VALUE_PLACEHOLDER}`),
+    omits: z
         .array(z.string())
+        .min(1)
+        .optional()
+        .describe("Parameters this step leaves out on purpose."),
+    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,
+    // which no runner can open and no later check refused.
+    .refine((step) => {
+    if (normalizeStepMethod(step.method) !== "navigate")
+        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"] });
+// 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({
+    changedFile: z
+        .string()
         .optional()
-        .describe("Response fields (optionally with expected values, e.g. 'account_count=2') this step asserts. Used to verify multi_record_aggregate claims."),
-    bodyMustInclude: z
+        .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("Fields that MUST appear in the request body for this step."),
-    chainsFrom: z.union([chainingRefSchema, z.array(chainingRefSchema)]).optional(),
-});
-const discriminatorClaimSchema = z.object({
-    kind: z.nativeEnum(DiscriminatorKind),
-    changedCodeAnchor: z
+        .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."),
+    asserts: z
         .string()
-        .min(1)
-        .describe("Verbatim snippet copied EXACTLY from the diff that this test probes. Must occur character-for-character in the PR diff to verify — a paraphrase or reconstruction will fail verification and demote the claim."),
-});
-const registerCandidateSchema = z.object({
-    scenarioName: z.string().min(1).describe("Name for this test/scenario. Reused as the match key against the generation tool's scenarioName — keep it identical when you later call the generation tool."),
-    description: z.string().min(1),
-    category: z.enum(SCENARIO_CATEGORIES).describe("Test category — drives ranking (never your own priority tag). `bug_caught` targets a `<bug_found>` flaw from code review. `requirement_conflict` asserts a requirement the PR title/description (or a requirements file it references) states and the implemented behavior contradicts — it fails on the current code by design. Both rank in the top tier but are carved out independently, so a requirement conflict never loses its slot to a code-review bug."),
-    priority: z.enum(["high", "medium", "low"]).describe("Your own assessment — recorded, but ranking is derived from category, not this field."),
-    testType: z.nativeEnum(TestType).refine((t) => PLAN_TEST_TYPES.has(t), {
-        message: `testType must be one of ${[...PLAN_TEST_TYPES].join(", ")}`,
-    }),
-    steps: z.array(registerStepSchema).min(1),
-    discriminator: discriminatorClaimSchema
+        .describe("What this test checks."),
+    stepUnderTest: z
+        .number()
+        .int()
+        .optional()
+        .describe("The `order` of the step this test is really about. Required whenever the planned test makes more than one call; one call is its own subject. In a create-then-verify pair the write is the subject, not the read-back. Two checks read it; nothing infers it."),
+    expected: z
+        .object({
+        outcome: z
+            .enum(["fail", "pass"])
+            .describe("Whether this test should fail or pass against the app as it stands."),
+        why: z
+            .string()
+            .describe("Why it has that outcome. A test that documents a defect asserts what the FIXED code returns — the rejection, the preserved value, the correct status — so it is red today and green after the fix, never today's defective response as correct."),
+    })
+        .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`."),
+        difference: z.string().describe("How the two differ."),
+    }).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())
+        .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
+        .string()
+        .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())
         .optional()
-        .describe("Declare when this candidate specifically probes changed logic (a structural bug-shape). Verified against `steps[]` and the PR diff — a failed claim demotes (with a reason) but never rejects the candidate."),
+        .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."),
+    })
+        .strict()
+        .optional()
+        .describe("UI planned tests only: the changed file that renders the screen `elements.pageUrl` opens. Checked: it is one of the files this pull request changed. Not checked: whether it really renders that screen."),
+    // The report's own schemas, reused so the two spellings cannot drift.
+    elements: z
+        .object({
+        pageUrl: z
+            .string()
+            .optional()
+            .describe("The page this test opens, spelled either as a route path starting with `/` or as an absolute `http` URL. Required on a `ui` or `e2e` planned test whose steps make no HTTP call."),
+        items: z
+            .array(targetElementSchema)
+            .nullish()
+            .describe("The elements this test targets, each one copied out of a `browser_blueprint` captured during this run. `null` when no capture holds them. Checked: each entry appears in a capture this run took of `pageUrl`. Not checked: whether the test needs that element."),
+    })
+        .strict()
+        .nullish()
+        .describe("UI planned tests only: the page this test opens and the elements it targets on it."),
+});
+// STRICT, here and on the planned test around it: zod strips an unrecognised key,
+// so a misplaced declaration vanished and the check then objected to its absence.
+const declarationsSchema = declarationFieldsSchema
+    .strict()
+    .superRefine((declared, ctx) => {
+    // Refuse a malformed shape; a judgment call gets an objection instead. An entry
+    // naming no element cannot be looked up, so there is nothing to report on.
+    const items = declared.elements?.items;
+    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);
+        if (identifies)
+            return;
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["elements", "items", index],
+            message: "every `elements.items` entry needs at least one of `accessibleName`, `testId` or `stableId` with a value in it — an entry with none names no element that can be looked up in a capture.",
+        });
+    });
 });
+// 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. */
+function namesAScreen(url) {
+    if (url.startsWith("/"))
+        return true;
+    try {
+        return ["http:", "https:"].includes(new URL(url).protocol);
+    }
+    catch {
+        return false;
+    }
+}
+/** The fields that belong under `declarations`. Read by the hoist below only.
+ *  Derived from the schema, not written out again: the hand-written copy was
+ *  missing `stepUnderTest`, so a stray one stayed at planned test level and zod
+ *  dropped it. */
+const DECLARATION_FIELDS = Object.keys(declarationFieldsSchema.shape);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** One value as text with object keys sorted, so the same declaration written
+ *  twice by hand is not a conflict merely because its keys are ordered
+ *  differently. List order still counts: two orders are two different lists. */
+function canonicalJson(value) {
+    return JSON.stringify(value, (_key, entry) => isPlainObject(entry)
+        ? Object.fromEntries(Object.keys(entry).sort().map((key) => [key, entry[key]]))
+        : entry);
+}
+/** Move a declaration field written one level too high into `declarations`.
+ *  MEASURED: about one planned test in five did this across 141 eval planned tests, and
+ *  every stray planned test-level key was a declaration field. A field in BOTH places
+ *  with different values stays put, so `.strict()` refuses it by name. */
+export function hoistDeclarationFields(value) {
+    if (!isPlainObject(value))
+        return value;
+    // A non-object `declarations` is left as written: hoisting would discard it
+    // and the error would name a field the agent never wrote.
+    if (value.declarations !== undefined && !isPlainObject(value.declarations))
+        return value;
+    const plannedTest = { ...value };
+    const original = isPlainObject(plannedTest.declarations) ? plannedTest.declarations : undefined;
+    const declarations = { ...(original ?? {}) };
+    let hoisted = false;
+    for (const field of DECLARATION_FIELDS) {
+        if (!(field in plannedTest))
+            continue;
+        const atCandidateLevel = plannedTest[field];
+        if (declarations[field] === undefined) {
+            declarations[field] = atCandidateLevel;
+            delete plannedTest[field];
+            hoisted = true;
+            continue;
+        }
+        if (canonicalJson(declarations[field]) === canonicalJson(atCandidateLevel)) {
+            // The same value twice says the same thing; drop the copy.
+            delete plannedTest[field];
+        }
+    }
+    if (hoisted || original)
+        plannedTest.declarations = declarations;
+    return plannedTest;
+}
+const registerPlannedTestSchema = z.preprocess(hoistDeclarationFields, z.object({
+    scenarioName: z
+        .string()
+        .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
+        .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."),
+    category: z
+        .enum(SCENARIO_CATEGORIES)
+        .describe(`What kind of test this is. Write one of:\n${categoryMenu()}`),
+    testType: z
+        .enum(PLAN_TEST_TYPES)
+        .describe("contract, integration, e2e or ui."),
+    steps: z
+        .array(registerStepSchema)
+        .describe("The requests this test makes, in order. At least one, unless `testType` is `ui` or `e2e` and the test makes no HTTP call."),
+    declarations: declarationsSchema
+        .optional()
+        .describe("The changes that make this planned test checkable. Every change belongs under THIS key; one written beside `steps` is moved here for you and reported as `declarations.<field>`."),
+})
+    .strict()
+    .superRefine((plannedTest, ctx) => {
+    // Three checks read the steps for the subject endpoint, so an empty list
+    // passed all three in silence.
+    const isUILabel = hasUITestTypeLabel(plannedTest.testType);
+    if (plannedTest.steps.length === 0 && !isUILabel) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["steps"],
+            message: "steps must not be empty for a contract, integration or other non-UI planned test: the route, duplicate and existing-coverage checks all read the steps to find the endpoint this test is about. List the requests the test makes.",
+        });
+    }
+    // Ruling A: a ui or e2e planned test whose steps make no HTTP call opens a
+    // screen instead of a request, so it must name that screen. Empty steps
+    // stay legal for it — a planned test naming no request and no screen is not
+    // a plan the server can read either.
+    const hasHTTPStep = plannedTest.steps.some((step) => isHTTPStep(step));
+    const rawUrl = plannedTest.declarations?.elements?.pageUrl;
+    const url = typeof rawUrl === "string" ? rawUrl.trim() : "";
+    if (isUILabel && !hasHTTPStep && url.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["declarations", "elements", "pageUrl"],
+            message: "a ui or e2e planned test whose steps make no HTTP call must set `declarations.elements.pageUrl` to the screen it opens: a planned test naming no request and no screen is not a plan the server can read.",
+        });
+    }
+    // The other half of Ruling A. Naming a screen and naming SOMETHING are
+    // different obligations: a one-word url passed this rule, and the page
+    // match and the relatedness check both compare it as written, so it named
+    // no page either could look up and drew no objection from either.
+    if (isUILabel && url.length > 0 && !namesAScreen(url)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["declarations", "elements", "pageUrl"],
+            message: "`declarations.elements.pageUrl` is accepted in two spellings and no others: a route path starting with `/`, e.g. `/orders/1`, or an absolute `http` or `https` URL, e.g. `http://localhost:5173/orders/1`. Give the path when this run has no host to name.",
+        });
+    }
+}));
 const registerTestPlanSchema = {
     stateFile: z
         .string()
         .refine((p) => path.isAbsolute(p), { message: "stateFile must be an absolute path" })
-        .describe("Path to state file from skyramp_analyze_changes"),
-    // No `repository` argument, deliberately (SKYR-4204 reopen). The approved
-    // plan is run-wide — one pooled registration covers every repository in the
-    // run — so unlike the per-repo tools (analyze_test_health, actions,
-    // execute_test) there is no section to select: the tool reads the root and
-    // derives run-wide facts (diff union, budget flags, scenario lookup) itself.
-    // A legacy caller still passing `repository` has it stripped harmlessly.
-    candidates: z
-        .array(registerCandidateSchema)
+        .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."),
+    // `.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.
+    changes: z
+        .array(z
+        .object({
+        id: z
+            .string()
+            .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."),
+        source: z
+            .string()
+            .describe("Where you read it: `pr-description`, `spec:<path>` for a requirements file the description names, or `diff`."),
+        surfaces: z
+            .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
+            .array(z
+            .object({
+            param: z.string().describe("The parameter this case sets."),
+            value: z
+                .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."),
+            expect: z
+                .enum(["accept", "reject"])
+                .describe("Whether the route must accept this value or reject it."),
+        })
+            .strict()
+            .refine((entry) => (entry.value !== undefined) !== (entry.absent === true), {
+            message: "a case states either `value` or `absent`, never both and never neither",
+        }))
+            .min(1, { message: "a `cases` 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."),
+    })
+        .strict())
+        .superRefine((changes, ctx) => {
+        const first = new Map();
+        changes.forEach((change, index) => {
+            const key = String(change?.id ?? "").trim();
+            if (!key)
+                return;
+            const seen = first.get(key);
+            if (seen === undefined) {
+                first.set(key, index);
+                return;
+            }
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [index, "id"],
+                message: `change id "${change.id}" is already used by change ${seen + 1}. Every change needs its own id — planned tests cite it by that id.`,
+            });
+        });
+    })
+        .default([])
+        .describe("The changes the pull request must make, read out of the pull request title and description, a requirements file they name, or the diff itself. Coverage per file is the basic minimum; coverage per change is the target, and anything more is a bonus."),
+    // 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
+    // registration. A run that warrants no test sends `[]` deliberately.
+    plannedTests: z
+        .array(registerPlannedTestSchema)
+        // A duplicated `scenarioName` is REFUSED here rather than objected to later,
+        // because the name is the planned test's id: two entries carrying one id share
+        // every objection about them and one answer closes both. Compared on the
+        // TRIMMED name and otherwise exactly — case is NOT folded, because the report
+        // joins on the exact id, and folding here would make "Login" and "LOGIN" one
+        // name to the plan and two ids to the report.
+        .superRefine((plannedTests, ctx) => {
+        const seen = new Map();
+        plannedTests.forEach((plannedTest, index) => {
+            const key = String(plannedTest?.scenarioName ?? "").trim();
+            if (!key)
+                return;
+            const first = seen.get(key);
+            if (first === undefined) {
+                seen.set(key, index);
+                return;
+            }
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [index, "scenarioName"],
+                message: `scenarioName "${plannedTest.scenarioName}" is already used by planned test ${first + 1}. Every planned test needs its own name — the name is its id.`,
+            });
+        });
+    })
+        .describe("Your complete plan, unordered. Nothing ranks, dedups, reorders or trims it, and the server adds no planned test of its own."),
+    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."),
+        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 with no test closes only with this. A reason the change is not worth testing is not a blocker."),
+    }).strict())
         .default([])
-        .describe("Your COMPLETE candidate list — every test you would generate OR recommend this run, including ones already suggested by skyramp_analyze_changes. Merged with any server pre-ranked candidates, re-ranked, and split into GENERATE vs ADDITIONAL. Call this again (with your full updated list) if you want to add or change candidates — each call replaces your previous submission."),
+        .describe("One answer per objection from your previous registration that you do not intend to fix. There is no registration limit."),
 };
-// ── Handler helpers ─────────────────────────────────────────────────────────
-function derivePriorityTier(scenario) {
-    if (isAttackSurfaceSecurityBoundary(scenario))
-        return PriorityTier.CRITICAL;
-    return CATEGORY_PRIORITY[scenario.category] ?? PriorityTier.LOW;
-}
-function toScenarioStep(step) {
+// ── Registration ──────────────────────────────────────────────────────────────
+/** Map the schema-validated input onto a `PlanInput`. `subjectEndpoints` is
+ *  deliberately not resolved: every verifier derives the subject from `steps`
+ *  through one helper. The planned test id IS the scenario name, so an objection
+ *  names the plan entry in the words the agent wrote for it. */
+export function buildRegistration(params, registrationNumber) {
     return {
-        order: step.order,
-        method: step.method,
-        path: step.path,
-        description: step.description,
-        interactionType: step.interactionType,
-        requestBody: step.requestBody,
-        queryParams: step.queryParams,
-        responseBody: step.responseBody,
-        expectedStatusCode: step.expectedStatusCode,
-        expectedResponseFields: step.expectedResponseFields,
-        bodyMustInclude: step.bodyMustInclude,
-        chainsFrom: step.chainsFrom,
+        changes: params.changes ?? [],
+        answers: params.answers ?? [],
+        // The tool counts the run's registrations; whatever the caller sent is ignored.
+        registrationNumber,
+        plannedTests: (params.plannedTests ?? []).map((input) => {
+            const scenario = {
+                scenarioName: input.scenarioName,
+                description: input.description,
+                category: input.category,
+                steps: input.steps,
+                testType: input.testType,
+            };
+            const declared = input.declarations;
+            const { elements, ...rest } = declared ?? {};
+            return {
+                // TRIMMED: the report side joins on `plannedTestId.trim()`.
+                plannedTestId: input.scenarioName.trim(),
+                scenario,
+                ...(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 } : {}) },
+            };
+        }),
     };
 }
-function toDraftedScenario(input, changedRoutes) {
-    const scenario = {
-        scenarioName: input.scenarioName,
-        description: input.description,
-        category: input.category,
-        priority: input.priority,
-        steps: input.steps.map(toScenarioStep),
-        chainingKeys: [],
-        requiresAuth: false,
-        estimatedComplexity: "moderate",
-        testType: input.testType,
-    };
-    // Resolved here, at the one boundary that has both the steps and the diff, so
-    // every later dedup stage reads one recorded value (SKYR-4214).
-    return { ...scenario, subjectEndpoints: resolveSubjectEndpoints(scenario, { changedRoutes }) };
+/** The primary repository plus every related one, in that order. */
+function repoSections(state) {
+    if (!state)
+        return [];
+    return [
+        { repo: state.metadata?.repository ?? "the primary repository", repositoryPath: state.metadata?.repositoryPath, data: state },
+        ...Object.entries(state.relatedRepos ?? {}).map(([repo, section]) => ({
+            repo,
+            repositoryPath: section?.repositoryPath,
+            data: section?.data,
+        })),
+    ];
 }
-/** Build the agent-submitted candidates. Discriminator claims are verified
- *  later, by {@link applyDiscriminatorClaims}, once the merge has settled which
- *  scenario each name resolves to. Exported for the direct unit test in
- *  registerTestPlanTool.test.ts — a candidate that does not survive selection
- *  never reaches the persisted plan, so its subjectEndpoints fill is not
- *  observable through the tool's output, and testing here avoids coupling the
- *  fill to what selection happens to keep. */
-export function buildAgentCandidates(candidates, changedRoutes) {
-    return candidates.map((input) => {
-        const scenario = toDraftedScenario(input, changedRoutes);
-        return {
-            scenario,
-            priority: derivePriorityTier(scenario),
-            novelty: Novelty.NEW,
-            source: CandidateSource.AGENT,
-            candidateId: computeCandidateId(scenario),
-        };
-    });
+/**
+ * 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 roots = [];
+    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);
+        }
+        catch {
+            // A repository path that no longer resolves holds no readable file.
+        }
+    }
+    return (relativePath) => {
+        if (typeof relativePath !== "string")
+            return false;
+        const cited = relativePath.trim();
+        if (!cited)
+            return false;
+        return roots.some((root) => fileExistsWithinRoot(root, cited));
+    };
 }
 /**
- * Verify each declared discriminator against the candidate that actually won
- * the merge, and mark it. Failed claims demote (never reject).
+ * The route patterns that render a changed frontend file, across every repository
+ * of the run.
  *
- * Runs AFTER the merge, not while building the agent's candidates: a server
- * pre-seeded candidate wins the name, so verifying the agent's copy first
- * attaches the result to a candidate that is about to be discarded — silently
- * stripping the verification. Verification is against the WINNER's
- * steps, so a claim that only held for the agent's rewrite is correctly refused
- * rather than carried across.
+ * 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.
  *
- * The marker is cleared before the current claim is applied. Each call replaces
- * the agent's previous submission (see the `candidates` schema), and
- * recoverServerCandidates restores whatever the LAST plan recorded — so keeping
- * it would let a boost earned by an earlier registration outlive the claim that
- * earned it, on a submission that no longer makes that claim or whose new claim
- * fails.
+ * 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.
  */
-function applyDiscriminatorClaims(candidates, claimsByKey, diffText, reposWithoutDiff = []) {
-    const demotions = [];
-    const marked = candidates.map((candidate) => {
-        const { verifiedDiscriminator: _stale, ...unmarked } = candidate;
-        const claim = claimsByKey.get(scenarioMergeKey(candidate.scenario.scenarioName) || candidate.candidateId);
-        if (!claim)
-            return unmarked;
-        const result = validateDiscriminator(candidate.scenario, claim, diffText, reposWithoutDiff);
-        if (result.verified) {
-            return { ...unmarked, verifiedDiscriminator: claim.kind };
+export function makeScreenRouteResolver(state) {
+    const resolvers = 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;
         }
-        demotions.push({
-            candidateId: candidate.candidateId,
-            reason: result.reason ?? `${claim.kind} discriminator claim could not be verified.`,
-        });
-        return unmarked;
-    });
-    return { candidates: marked, demotions };
+        return unmounted;
+    };
 }
-/** Recover full Candidates for pre-seeded ("server") plan items by matching
- *  candidateId back to the analyzed scenarios (repositoryAnalysis.scenarios) —
- *  ApprovedPlanItem is deliberately slim and doesn't carry steps[]. */
-function recoverServerCandidates(priorPlan, allScenarios) {
-    if (!priorPlan)
-        return [];
-    const scenarioById = new Map();
-    for (const scenario of allScenarios) {
-        scenarioById.set(computeCandidateId(scenario), scenario);
+/** 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. */
+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 serverItems = [...priorPlan.generate, ...priorPlan.additional].filter((item) => item.source === CandidateSource.SERVER);
-    const recovered = [];
-    for (const item of serverItems) {
-        const scenario = scenarioById.get(item.candidateId);
-        if (!scenario) {
-            logger.warning(`${TOOL_NAME}: pre-seeded server candidate ${item.candidateId} not found in repositoryAnalysis.scenarios — dropping`);
-            continue;
-        }
-        recovered.push({
-            scenario,
-            priority: derivePriorityTier(scenario),
-            novelty: Novelty.EXISTING,
-            source: CandidateSource.SERVER,
-            candidateId: item.candidateId,
-            ...(item.verifiedDiscriminator ? { verifiedDiscriminator: item.verifiedDiscriminator } : {}),
+    catch (error) {
+        // A repository git cannot read yields no changed files, which
+        // `reposWithoutDiff` already reports to the agent — it must not fail the
+        // registration.
+        logger.warning("Verify-time changed-file listing failed; this repository has no diff for the checks", {
+            repositoryPath,
+            error: error instanceof Error ? error.message : String(error),
         });
+        return undefined;
     }
-    return recovered;
-}
-/** Whether a repo section's persisted diff classification contains any new,
- *  modified, or removed endpoint — the same signal `computeScoredCandidates`
- *  derives `hasApiChanges` from at analyze time. */
-function sectionHasApiChanges(data) {
-    const diff = data?.repositoryAnalysis?.diff;
-    return ((diff?.newEndpoints?.length ?? 0) > 0 ||
-        (diff?.modifiedEndpoints?.length ?? 0) > 0 ||
-        (diff?.removedEndpoints?.length ?? 0) > 0);
 }
-function resolveBudgetContext(stateData, fullState) {
-    const pbc = stateData.planBudgetContext;
-    const base = {
-        maxGenerate: pbc?.maxGenerate ?? MAX_TESTS_TO_GENERATE,
-        maxTotal: pbc?.maxTotal ?? MAX_RECOMMENDATIONS,
-        isUIOnlyPR: pbc?.isUIOnlyPR ?? false,
-        hasFrontendChanges: pbc?.hasFrontendChanges ?? false,
-        externalCoverage: new Set(pbc?.externalCoverageKeys ?? []),
-        // `true` for the same reason `computeDiffChangesTestFiles` answers `true` with
-        // no diff: an unknown must shut the reserve, not open it. State written by an
-        // older MCP build carries no such field, and if that PR did add its own tests
-        // the reserve would recommend duplicates of them — the failure this flag
-        // exists to stop, reached by version skew alone. It is also the pre-reserve
-        // behaviour: covered candidates were dropped.
-        diffChangesTestFiles: pbc?.diffChangesTestFiles ?? true,
-    };
-    const relatedSections = Object.values(fullState?.relatedRepos ?? {}).map((section) => section.data);
-    if (relatedSections.length === 0)
-        return base;
-    // SKYR-4204: isUIOnlyPR/hasFrontendChanges are per-SECTION facts — each
-    // analyze call computes them from its own repo's diff. The approved plan is
-    // one run-wide decision, so a frontend-only PRIMARY diff must not put the
-    // budgeter on its all-UI branch (backendGenerateCount() = 0) while a related
-    // repo carries endpoint changes; that pinned GENERATE to UI placeholders and
-    // left every API candidate in ADDITIONAL regardless of maxGenerate. Derive
-    // the flags across ALL sections. A related repo checked out on its default
-    // branch classifies no endpoint changes, so it leaves a UI-only run UI-only.
-    // Budget numbers come from the root (primary) section: the testbot prompt
-    // passes topN/maxGenerate only to the primary analyze call, so related
-    // sections carry defaults.
-    const sections = [fullState ?? undefined, ...relatedSections];
-    const hasFrontendChanges = sections.some((s) => s?.planBudgetContext?.hasFrontendChanges ?? false);
-    const hasApiChanges = sections.some(sectionHasApiChanges);
-    const rootPbc = fullState?.planBudgetContext;
-    // SKYR-4211: external-test coverage is also a per-section fact — a backend
-    // candidate already covered by an external test recorded in a RELATED repo's
-    // section must dedup the same as one covered in the primary. Union the keys
-    // across all sections, like the flags above.
-    const externalCoverage = new Set(sections.flatMap((s) => s?.planBudgetContext?.externalCoverageKeys ?? []));
+/** Every fact the verifiers check against, gathered once per registration. */
+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.
     return {
-        maxGenerate: rootPbc?.maxGenerate ?? base.maxGenerate,
-        maxTotal: rootPbc?.maxTotal ?? base.maxTotal,
-        isUIOnlyPR: hasFrontendChanges && !hasApiChanges,
-        hasFrontendChanges,
-        externalCoverage,
-        // Unioned across sections like the flags above: a pull request that adds
-        // its own tests in ANY repo of the run must shut the reserve, or that repo's
-        // own coverage becomes grounds to recommend duplicates of it. A section with
-        // no budget context is an unknown, and an unknown shuts the reserve — the
-        // same direction `computeDiffChangesTestFiles` takes with no diff.
-        diffChangesTestFiles: sections.some((s) => s?.planBudgetContext?.diffChangesTestFiles ?? true),
+        changedFiles: Object.fromEntries(sections.map((section, i) => [section.repo, listings[i] ?? []])),
+        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(),
+        // From the analyze result on the state file, across every repository: a
+        // removal guard names an element that renders nowhere, so this list is the
+        // only thing that can tell an honest one from an invented element.
+        removedUiElements: sections.flatMap((section) => section.data?.uiContext?.removedElements ?? []),
+        citedFileExists: makeCitedFileCheck(state),
+        routesRenderingFile: makeScreenRouteResolver(state),
     };
 }
-function describeGenerationCall(item) {
-    switch (item.testType) {
-        case "contract":
-            return item.scenarioName
-                ? `call ${TOOL_CONTRACT_TEST_GENERATION} with scenarioName "${item.scenarioName}"`
-                : `call ${TOOL_CONTRACT_TEST_GENERATION}`;
-        case "integration":
-            return `call ${TOOL_BATCH_SCENARIO_TEST_GENERATION}, then ${TOOL_INTEGRATION_TEST_GENERATION} with the returned scenarioFile`;
-        case "e2e":
-            return `call ${TOOL_E2E_TEST_GENERATION}`;
-        case "ui":
-            return `call ${TOOL_UI_TEST_GENERATION}`;
-        default:
-            return "use the generation tool matching this testType";
-    }
-}
-function renderPlanItem(item, rank) {
-    const discriminatorNote = item.verifiedDiscriminator ? `, verified discriminator: ${item.verifiedDiscriminator}` : "";
-    return `${rank}. [${item.testType}] "${item.scenarioName}" (${item.category}${discriminatorNote}) — ${describeGenerationCall(item)}`;
-}
+// ── Output ──────────────────────────────────────────────────────────────────
 /**
- * Whether this run generates UI/E2E tests is a deterministic property of the
- * approved plan, so it is decided here rather than left to the agent to resolve
- * from prompt prose. The prompt owns HOW to record a UI trace and the runtime
- * conditions the server cannot know (app unreachable, unintegrated component);
- * this directive owns WHETHER and HOW MANY.
+ * What the agent reads back. Every objection carries its id so it can be answered,
+ * and the text says the plan is stored either way — a objections list without that
+ * line reads as a rejection and invites a needless second registration.
  */
-function renderGenerationDirective(plan) {
-    const uiCount = plan.generate.filter((item) => item.testType === TestType.UI || item.testType === TestType.E2E).length;
-    const nonUICount = plan.generate.length - uiCount;
-    const tests = (n) => `${n} test${n === 1 ? "" : "s"}`;
-    if (plan.generate.length === 0) {
-        return [
-            "### Generation directive: GENERATE NOTHING",
-            "Create zero new tests of any type this run and proceed to the report. An empty `newTestsCreated` is the CORRECT " +
-                "result for this PR — there is no new observable surface to cover. Do not record a browser trace and do not invent " +
-                "a spec to have something to report; report your maintenance work and the ADDITIONAL candidates as recommendations instead.",
-        ];
-    }
-    if (uiCount === 0) {
-        return [
-            "### Generation directive: NO UI/E2E GENERATION",
-            `This plan allocates no UI/E2E generation. Generate the ${tests(nonUICount)} listed above and create zero UI tests ` +
-                "— do not record a browser trace and do not add a UI spec to fill `newTestsCreated`.",
-        ];
-    }
-    return [
-        `### Generation directive: UI/E2E GENERATION REQUIRED (${uiCount})`,
-        `This plan allocates ${tests(uiCount)} of type UI/E2E. You MUST attempt to record and generate each one — do not ` +
-            "downgrade them to recommendations while the app is reachable." +
-            (nonUICount > 0 ? ` Generate the ${tests(nonUICount)} of other types as well.` : ""),
-    ];
-}
-/** SKYR-4292: the server cannot count the diff's changed behaviors, so an
- *  under-budget plan is flagged (not rejected) with what a missing candidate looks
- *  like. Wipro PR #24 registered 3 candidates against a 20-slot UI-only budget and
- *  the tool answered "AUTHORITATIVE and FINAL" with no pushback. */
-function renderBudgetCheck(plan, maxTotal) {
-    const filled = plan.generate.length + plan.additional.length;
-    if (filled >= maxTotal)
-        return [];
-    return [
-        "",
-        `### Budget check: ${filled} of ${maxTotal} slots filled`,
-        "Every observable behavior this diff changes — each option value added, removed, renamed or reordered; each label, " +
-            "element, route, state, validation rule, computed value or style value (spacing, size, color, radius, font weight, " +
-            "class name) that renders differently; each removed element, asserted absent — needs a candidate above, however " +
-            "small the change. A change is covered only when an existing test asserts the changed value, not when a test merely " +
-            "reaches the component. If any changed behavior has no candidate, call skyramp_register_test_plan again with your " +
-            "full updated list. If the diff truly changes fewer behaviors than the budget, this plan stands as-is.",
-    ];
-}
-function renderPlanText(plan, dropped, maxTotal) {
+export function renderPlanResult(result) {
     const lines = [];
-    lines.push(`## Approved Test Plan (${plan.planId})`);
-    lines.push("");
-    lines.push("This plan is AUTHORITATIVE and FINAL. Generation tools reject scenarios that are not in the GENERATE list below. " +
-        "If you need to add, drop, or change a candidate, call skyramp_register_test_plan again with your full updated candidate list.");
-    lines.push("");
-    lines.push(`### GENERATE (${plan.generate.length}) — generate exactly these, in this order`);
-    if (plan.generate.length === 0) {
-        lines.push("  (none — nothing to generate this run)");
-    }
-    else {
-        plan.generate.forEach((item, i) => lines.push(renderPlanItem(item, i + 1)));
-    }
-    lines.push("");
-    lines.push(`### ADDITIONAL (${plan.additional.length}) — report as recommendations; only generate if backfilling a failed GENERATE item`);
-    if (plan.additional.length === 0) {
-        lines.push("  (none)");
-    }
-    else {
-        plan.additional.forEach((item, i) => lines.push(renderPlanItem(item, plan.generate.length + i + 1)));
+    lines.push(`Registration ${result.plan.registrationNumber} stored as this run's plan.`);
+    lines.push(`Plan: ${result.plan.plannedTests.length} planned test(s).`);
+    // A convenience: `differsFrom` also accepts a `scenarioName`.
+    for (const plannedTest of result.plan.plannedTests) {
+        lines.push(`- ${plannedTest.plannedTestId} — ${plannedTest.scenario?.scenarioName ?? "(unnamed)"}`);
     }
-    if (plan.demotions.length > 0) {
-        // A demotion (failed discriminator claim) and a drop (removed by the
-        // budgeter for an unrelated reason — coverage or budget) are independent:
-        // a candidate can suffer both. Split so the report never claims a
-        // dropped candidate is "still registered".
-        const dropReasonByCandidateId = new Map(dropped.map((d) => [d.candidateId, d.reason]));
-        const registeredDemotions = plan.demotions.filter((d) => !dropReasonByCandidateId.has(d.candidateId));
-        const removedDemotions = plan.demotions.filter((d) => dropReasonByCandidateId.has(d.candidateId));
-        if (registeredDemotions.length > 0) {
-            lines.push("");
-            lines.push(`### Demotions (${registeredDemotions.length}) — discriminator claims that did NOT verify (candidate still registered, claim dropped)`);
-            for (const demotion of registeredDemotions) {
-                lines.push(`- ${demotion.candidateId}: ${demotion.reason}`);
-            }
-        }
-        if (removedDemotions.length > 0) {
-            lines.push("");
-            lines.push(`### Demoted AND removed (${removedDemotions.length}) — the claim failed to verify AND the candidate left the plan. It is NOT registered.`);
-            for (const demotion of removedDemotions) {
-                lines.push(`- ${demotion.candidateId}: claim failed — ${demotion.reason}; removed — ${dropReasonByCandidateId.get(demotion.candidateId)}`);
-            }
-        }
+    lines.push(result.summary);
+    // The agent sends the answers it wants read; these came off the stored plan, and
+    // the plan they answered has changed since.
+    if (result.carried) {
+        lines.push("");
+        lines.push(`Answers carried from registration ${result.carried.registrationNumber} — recheck each; revise it if the plan change made it wrong:`);
+        for (const { objectionId, answer } of result.carried.answers)
+            lines.push(`- ${objectionId} — ${answer}`);
     }
-    // Every other removal — budget or coverage, with no failed claim attached.
-    // This section is independent of `demotions`: the two channels are unrelated,
-    // and the motivating case has drops and NO demotions. Nesting it inside the
-    // demotion block returned empty GENERATE/ADDITIONAL lists with no candidate id
-    // and no reason, which is the state item 5 exists to make visible. Measured on
-    // eval run 32586610615, fixture repo15-P14: 10 drops, 0 demotions.
-    const demotedIds = new Set(plan.demotions.map((d) => d.candidateId));
-    const removedWithoutDemotion = dropped.filter((d) => !demotedIds.has(d.candidateId));
-    if (removedWithoutDemotion.length > 0) {
+    if (result.objections.length > 0) {
         lines.push("");
-        lines.push(`### Removed (${removedWithoutDemotion.length}) — candidates the selection stage dropped. They are NOT registered.`);
-        for (const drop of removedWithoutDemotion) {
-            lines.push(`- ${drop.candidateId}: ${drop.reason}`);
+        lines.push("Objections:");
+        for (const objection of result.objections) {
+            lines.push(`- ${objection.objectionId} — ${objection.message}`);
+            lines.push(`  evidence: ${objection.evidence}`);
+            lines.push(`  next: ${objection.suggestion}`);
         }
+        lines.push("");
+        lines.push("The plan is stored either way. Revise it and call this tool again — there is no registration limit — " +
+            "or answer an objection through `answers` using the id above. Anything left open is rendered in the report.");
     }
-    lines.push("");
-    lines.push(...renderGenerationDirective(plan));
-    lines.push(...renderBudgetCheck(plan, maxTotal));
     return lines.join("\n");
 }
 // ── Tool registration ───────────────────────────────────────────────────────
+/** One registration at a time per state file: the registration number is a
+ *  read-modify-write with an await between the halves, so two overlapping calls
+ *  returned one number for two plans. In-process serialisation is enough. */
+const registrationsInFlight = new Map();
+/** The one file two calls contend for, whatever they spelled. Keying on the raw
+ *  string let `/a/b/state.json` and `/a/b//state.json` take different locks on one
+ *  file. `realpathSync` throws before the file exists; the resolved path is the
+ *  right key then. */
+function lockKeyFor(stateFile) {
+    const resolved = path.resolve(stateFile);
+    try {
+        return fs.realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+function oneAtATime(stateFile, work) {
+    const key = lockKeyFor(stateFile);
+    const queued = (registrationsInFlight.get(key) ?? Promise.resolve()).then(work, work);
+    // Never rejects, so one failed registration cannot break the chain.
+    const settled = queued.catch(() => undefined);
+    registrationsInFlight.set(key, settled);
+    // Dropped when nothing is queued, so the map does not grow without bound.
+    void settled.then(() => {
+        if (registrationsInFlight.get(key) === settled)
+            registrationsInFlight.delete(key);
+    });
+    return queued;
+}
 export function registerRegisterTestPlanTool(server) {
     server.registerTool(TOOL_NAME, {
         annotations: {
-            destructiveHint: false,
+            // It REPLACES the stored plan and the registration count.
+            destructiveHint: true,
             readOnlyHint: false,
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: "REQUIRED before generation tools in testbot runs — the deterministic selection checkpoint that decides which candidate tests get generated. " +
-            "Register your COMPLETE candidate list (every test you would generate OR recommend) BEFORE calling any generation tool. " +
-            "Merges your candidates with any server pre-ranked candidates from skyramp_analyze_changes, verifies declared `discriminator` " +
-            "claims against the PR diff, re-ranks the union, and returns the mandated GENERATE list plus ADDITIONAL recommendations and " +
-            "demotion reasons for claims that failed verification. In an active testbot run, generation tools (skyramp_batch_scenario_test_generation, " +
-            "skyramp_contract_test_generation, skyramp_integration_test_generation) reject any scenario not in the returned GENERATE list — " +
-            "call this tool first, then generate exactly what it returns. Standalone/IDE MCP usage (no active testbot run) is unaffected.",
+        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. " +
+            "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.",
         inputSchema: registerTestPlanSchema,
     }, async (params) => {
-        let errorResult;
-        try {
-            logger.info("Registering run-wide test plan", {
-                candidateCount: params.candidates?.length ?? 0,
-            });
-            const stateManager = StateManager.fromStatePath(params.stateFile);
-            // The plan is run-wide, so register always reads the ROOT (primary)
-            // section — there is no section selector (routing by one is what let a
-            // related-repo registration run with that section's context —
-            // SKYR-4204 reopen). Run-wide facts (diff union, budget flags,
-            // scenario lookup) come from fullState below.
-            const stateData = await stateManager.readData();
-            if (!stateData) {
-                errorResult = toolError(`State file is empty or invalid: ${params.stateFile}. Call skyramp_analyze_changes first to generate a valid state file.`);
-                return errorResult;
-            }
-            // SKYR-4203: one register call carries candidates for EVERY repo of the
-            // run, but `stateData` is a single repo's section — and the candidate
-            // schema has no per-candidate repository, so a related repo's anchors
-            // were unverifiable by construction. Verify anchors (and rank diff-hunk
-            // proximity) against the union of ALL sections' diffs: an anchor
-            // grounded in a related repo's change is as real as one in the
-            // primary's. Sections with no diff (a related repo checked out on its
-            // default branch) are collected so an unmatched anchor reads as
-            // uncheckable rather than ungrounded.
-            const fullState = await stateManager.readFullState();
-            const diffSections = [
-                { repo: fullState?.metadata?.repository ?? "the primary repository", diff: fullState?.diffText },
-                ...Object.entries(fullState?.relatedRepos ?? {}).map(([repo, section]) => ({
-                    repo,
-                    diff: section.data?.diffText,
-                })),
-            ];
-            const diffText = diffSections.map((s) => s.diff).filter(Boolean).join("\n");
-            const reposWithoutDiff = diffSections.filter((s) => !s.diff).map((s) => s.repo);
-            // Scenario lookup for server-candidate recovery spans ALL sections —
-            // the primary's drafted scenarios must resolve even when `repository`
-            // targets a related repo (SKYR-4204 reopen: the same single-section
-            // shape as the diff union above).
-            const allScenarios = [
-                ...(fullState?.repositoryAnalysis?.scenarios ?? []),
-                ...Object.values(fullState?.relatedRepos ?? {}).flatMap((section) => section.data?.repositoryAnalysis?.scenarios ?? []),
-            ];
-            const changedRoutes = collectChangedRouteLines(diffText);
-            const agentCandidates = buildAgentCandidates(params.candidates ?? [], changedRoutes);
-            // The approved plan is run-wide and persists at the ROOT (see the
-            // persist step below), so prior-plan recovery reads the root first;
-            // the section fallback covers state written by older builds.
-            const serverCandidates = recoverServerCandidates(fullState?.approvedPlan ?? stateData.approvedPlan, allScenarios);
-            // Merge by scenario-name identity, NOT the full content-hashed candidateId:
-            // the server (analyze_changes) and the agent frequently draft their own
-            // independent steps[] for "the same" scenario (identical scenarioName),
-            // which hash to different candidateIds — deduping on the full id let
-            // both survive as apparent duplicates (SKYR-4026). A pre-seeded server
-            // candidate wins over an agent submission for the same scenario name —
-            // source: "server" is preserved per the unified-plan design.
-            //
-            // Uses scenarioMergeKey (untruncated), not scenarioNameSlug — the
-            // latter's 48-char cap is fine for a short candidateId prefix combined
-            // with a content hash, but bare as a Map key it would silently collapse
-            // two distinct long scenario names sharing a common prefix. A missing
-            // scenarioName (schema requires one for agent candidates; only a
-            // malformed server-recovered scenario could lack one) falls back to
-            // the already-unique candidateId rather than a shared literal.
-            const mergeKey = (c) => scenarioMergeKey(c.scenario.scenarioName) || c.candidateId;
-            const merged = new Map();
-            for (const candidate of agentCandidates)
-                merged.set(mergeKey(candidate), candidate);
-            for (const candidate of serverCandidates)
-                merged.set(mergeKey(candidate), candidate);
-            // The agent declares a claim per scenario NAME, so key the claims the
-            // same way the merge does and verify against whichever copy survived.
-            const claimsByKey = new Map();
-            // Keyed through mergeKey, not scenarioMergeKey alone: a name that
-            // slugifies to nothing (e.g. an all-non-ASCII name) would be stored
-            // under "" while the lookup falls back to the candidateId, so the claim
-            // would be neither verified nor demoted.
-            (params.candidates ?? []).forEach((input, i) => {
-                if (input.discriminator)
-                    claimsByKey.set(mergeKey(agentCandidates[i]), input.discriminator);
-            });
-            const { candidates: allCandidates, demotions } = applyDiscriminatorClaims([...merged.values()], claimsByKey, diffText, reposWithoutDiff);
-            // An empty union would persist an authoritative plan with an empty
-            // GENERATE list, which the generation gate then enforces — bricking
-            // the run until re-registration. Reject instead so the agent can
-            // self-correct in one step.
-            if (allCandidates.length === 0) {
-                errorResult = toolError("No candidates submitted and no server pre-ranked candidates exist for this run. " +
-                    "Submit your complete candidate list (every test you would generate or recommend) in `candidates` — an empty plan would block all generation.");
-                return errorResult;
-            }
-            // Review (mcp#774): enforce ONE run-wide plan at the tool boundary. A
-            // re-registration whose pool shares no scenario with the active plan
-            // is the per-repo-partial signature (the demoshop rig's second,
-            // backend-only call) — accepting it would silently REPLACE the run's
-            // plan with a subset and drop every earlier agent candidate. Genuine
-            // full-list updates overlap the active plan and replace it as before.
-            // The overlap test spans GENERATE ∪ ADDITIONAL: with maxGenerate=0 the
-            // active plan's GENERATE is empty while ADDITIONAL carries every
-            // candidate, and a disjoint partial could otherwise still replace it
-            // silently (Copilot review on #774).
-            const priorItems = [
-                ...(fullState?.approvedPlan?.generate ?? []),
-                ...(fullState?.approvedPlan?.additional ?? []),
-            ];
-            if (priorItems.length > 0) {
-                const poolKeys = new Set(allCandidates.map(mergeKey));
-                const overlaps = priorItems.some((item) => poolKeys.has(scenarioMergeKey(item.scenarioName) || item.candidateId));
-                if (!overlaps) {
-                    errorResult = toolError(`A run-wide plan is already active (${fullState.approvedPlan.planId}: ` +
-                        `${priorItems.map((i) => i.scenarioName).join(", ")}) and this submission shares none of its ` +
-                        "scenarios. skyramp_register_test_plan REPLACES the whole run's plan — resubmit ONE pooled candidate " +
-                        "list for the entire run (your previous candidates plus these changes), not a per-repo subset.");
-                    return errorResult;
-                }
-            }
-            const budgetContext = resolveBudgetContext(stateData, fullState);
-            // SKYR-4204 reopen: a reserved UI slot is only fillable from the
-            // candidate pool. A pool with no UI candidate on a run with frontend
-            // changes would silently plan zero UI tests (runs 32419025266,
-            // 32431042133, 32431106864) — reject so the agent self-corrects in one
-            // step, exactly like the empty-candidates rejection above.
-            const uiFloor = generateFloors(budgetContext).ui;
-            if (uiFloor > 0 && !allCandidates.some((c) => inferScenarioType(c.scenario) === TestType.UI)) {
-                errorResult = toolError(`This run has frontend changes, so the plan MUST include UI tests — at least ${uiFloor} of the ` +
-                    "GENERATE slots are held for them, and more are open to UI candidates on rank. No submitted or " +
-                    "recovered candidate has testType 'ui'. Resubmit your full candidate list including UI candidates " +
-                    "for the changed frontend (see uiContext.changedFrontendFiles).");
-                return errorResult;
-            }
-            const result = selectPlan(allCandidates, { ...budgetContext, demotions, diffText });
-            const approvedPlan = {
-                planId: crypto.randomUUID(),
-                createdAt: new Date().toISOString(),
-                generate: result.generate.map(buildApprovedPlanItem),
-                additional: result.additional.map(buildApprovedPlanItem),
-                demotions: result.demotions,
-                dropped: result.dropped,
-            };
-            // The approved plan is the ONE run-wide authority (the prompt mandates
-            // a single pooled registration on multi-repo runs), so it persists at
-            // the state-file ROOT regardless of `repository`. Per-section plans
-            // blinded every root-reading consumer — planGuard let generation run
-            // unguarded, submitReportTool's reconciliation was inert, and the eval
-            // extractor saw "no plan" (SKYR-4204 reopen). writeData preserves the
-            // relatedRepos sections and the root metadata.
+        // 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);
+        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.");
+        }
+        return oneAtATime(stateFile, async () => {
             try {
-                const { metadata: _meta, relatedRepos: _sections, ...rootData } = fullState ?? {};
-                await stateManager.writeData({ ...rootData, approvedPlan }, { step: TOOL_NAME });
+                const stateManager = StateManager.fromStatePath(stateFile);
+                // Run-wide: one registration covers every repository, so the facts come
+                // from the whole state file and the plan persists at its root.
+                const fullState = await stateManager.readFullState();
+                if (!fullState) {
+                    return toolError(`State file is empty or invalid: ${stateFile}. Call skyramp_analyze_changes first to generate a valid state file.`);
+                }
+                const registrationNumber = (fullState.registrationCount ?? 0) + 1;
+                const registration = buildRegistration(params, registrationNumber);
+                // The previous registration's answers are already on the stored plan, which
+                // the write below replaces.
+                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 });
+                }
+                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) }] };
             }
             catch (error) {
-                errorResult = toolError(`Failed to persist approved test plan to state file: ${error.message}. Retry this call.`);
-                return errorResult;
+                return toolError(`${TOOL_NAME} failed: ${error?.message ?? String(error)}`);
             }
-            return {
-                content: [{ type: "text", text: renderPlanText(approvedPlan, result.dropped, budgetContext.maxTotal) }],
-            };
-        }
-        catch (error) {
-            errorResult = toolError(`skyramp_register_test_plan failed: ${error?.message ?? String(error)}`);
-            return errorResult;
-        }
+        });
     });
 }