@skyramp/mcp 0.4.0 → 0.4.1-rc.2

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

@@ -4,7 +4,7 @@ import * as fs from "fs";
 import * as path from "path";
 import yaml from "js-yaml";
 import { logger } from "../../utils/logger.js";
-import { parseWorkspaceAuthType, getDefaultAuthHeader, WorkspaceAuthType, readWorkspaceConfigRaw } from "../../utils/workspaceAuth.js";
+import { parseWorkspaceAuthType, getDefaultAuthHeader, WorkspaceAuthType, readWorkspaceConfigRaw, resolveWorkspaceApiService, findWorkspaceAuthDisagreement } from "../../utils/workspaceAuth.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { makeProgressReporter } from "../../utils/progress.js";
 import { StateManager, registerSession, storeSessionData, rememberTestsRepoDir, getActiveRunStatePath, setActiveRunStatePath, } from "../../utils/AnalysisStateManager.js";
@@ -101,6 +101,20 @@ export const analyzeChangesInputSchema = {
         .default(false)
         .describe("When true, diffs the base ref against the working tree (captures uncommitted and unstaged changes). Use for local-dev workflows. Defaults to false (CI mode — committed changes only)."),
 };
+/** The shape an auth finding takes. Declared here beside the other output shapes;
+ *  the assignment below fails to compile if it drifts from `AuthFinding`. */
+const authFindingShape = z.object({
+    kind: z.literal("workspace-disagreement"),
+    message: z.string(),
+    serviceName: z.string(),
+    field: z.enum(["authType", "authHeader", "authScheme"]),
+    primary: z.string(),
+    analysed: z.string(),
+    primaryWorkspaceFile: z.string(),
+    analysedWorkspaceFile: z.string(),
+});
+const _authFindingShapeMatchesType = {};
+void _authFindingShapeMatchesType;
 /** Both halves of `uiContext` carry the same record, so the shape is declared once.
  *  It mirrors `RemovedUiElement`; the assignment below fails to compile if either drifts. */
 const uiIdentifierShape = z.object({ attribute: z.string(), value: z.string(), file: z.string() });
@@ -135,6 +149,7 @@ export const analyzeChangesOutputSchema = {
         authHeader: z.string().optional(),
         openApiSpecPath: z.string().optional(),
         openApiSpecLoaded: z.boolean(),
+        authFindings: z.array(authFindingShape).optional(),
     })
         .optional(),
     uiContext: z
@@ -285,9 +300,12 @@ export function registerAnalyzeChangesTool(server) {
             let wsAuthMethod = "none";
             let wsAuthType;
             let wsAuthScheme;
+            // What the agent has to decide about this repository's auth. Empty on a
+            // workspace whose config and code agree, which is every clean run.
+            const authFindings = [];
             const rawConfig = await readWorkspaceConfigRaw(params.repositoryPath);
             if (rawConfig) {
-                const svc = rawConfig.services?.[0];
+                const svc = resolveWorkspaceApiService(rawConfig);
                 if (svc?.api?.baseUrl)
                     wsBaseUrl = svc.api.baseUrl;
                 if (svc?.api?.authHeader !== undefined)
@@ -626,6 +644,40 @@ export function registerAnalyzeChangesTool(server) {
             if (params.repository)
                 setActiveRunStatePath(stateFile);
             registerSession(sessionId, stateFile);
+            // A related repo reads its OWN .skyramp/workspace.yml, so it can disagree
+            // with the primary's unified entry for the same service and nothing would
+            // say so.
+            //
+            // Runs AFTER the state write, because both checkout paths come off the run's
+            // state file and this call's own path is not in it until then. Write order is
+            // not fixed: given a declared `primaryRepository`, a related repo may write
+            // first and the root is then created empty (AnalysisStateManager.writeRepoData).
+            // So whichever call arrives second holds both sides and is the one that
+            // reports — the primary against the related repos already recorded, a related
+            // repo against the primary.
+            if (rawConfig && params.repository) {
+                try {
+                    const checkouts = await stateManager.listRepoCheckouts();
+                    const analysingPrimary = checkouts.some((checkout) => checkout.primary && checkout.root === params.repositoryPath);
+                    const others = checkouts.filter((checkout) => checkout.primary !== analysingPrimary &&
+                        checkout.root !== params.repositoryPath);
+                    for (const other of others) {
+                        const otherConfig = await readWorkspaceConfigRaw(other.root);
+                        const disagreement = analysingPrimary
+                            ? findWorkspaceAuthDisagreement(rawConfig, otherConfig, params.repositoryPath, other.root, other.repository)
+                            : findWorkspaceAuthDisagreement(otherConfig, rawConfig, other.root, params.repositoryPath, params.repository);
+                        if (disagreement) {
+                            authFindings.push(disagreement);
+                            break;
+                        }
+                    }
+                }
+                catch (error) {
+                    logger.debug("Could not compare this repository's workspace against the run's others", {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
             try {
                 await server.server.sendResourceListChanged();
             }
@@ -672,6 +724,7 @@ export function registerAnalyzeChangesTool(server) {
                     ...(wsAuthHeader ? { authHeader: wsAuthHeader } : {}),
                     ...(wsSchemaPath ? { openApiSpecPath: wsSchemaPath } : {}),
                     openApiSpecLoaded: specFetchSucceeded,
+                    ...(authFindings.length ? { authFindings } : {}),
                 },
                 // Removed half only. No prompt describes `retiredElements`, and beside the guard
                 // list it reads as more guards to record; the plan checks read the state file.

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

@@ -3,13 +3,14 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StateManager, UnifiedAnalysisState } from "../../utils/AnalysisStateManager.js";
 import { TestType } from "../../types/TestTypes.js";
 import { PlanResult } from "../../recommendation/registerPlan.js";
-import { ObjectionAnswer, PlanChange, PlanInput, VerifyContext } from "../../recommendation/types.js";
+import { ObjectionAnswer, PlanChange, PlanDefect, PlanInput, PlanMaintenance, VerifyContext } from "../../recommendation/types.js";
 /** The whole run's state file: the primary repository at the root, every related
  *  repository under `relatedRepos`. */
 type RunState = Awaited<ReturnType<StateManager<UnifiedAnalysisState>["readFullState"]>>;
 export declare const declarationFieldsSchema: z.ZodObject<{
     changedFile: z.ZodOptional<z.ZodString>;
     changes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    defects: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     asserts: z.ZodString;
     stepUnderTest: z.ZodOptional<z.ZodNumber>;
     expected: z.ZodObject<{
@@ -121,11 +122,12 @@ export declare const declarationFieldsSchema: z.ZodObject<{
         differsBy: string;
     }[] | undefined;
     changedFile?: string | undefined;
-    changes?: string[] | undefined;
+    defects?: string[] | undefined;
     routes?: {
         file: string;
         step: number;
     }[] | undefined;
+    changes?: string[] | undefined;
     elements?: {
         items?: {
             role: string;
@@ -158,11 +160,12 @@ export declare const declarationFieldsSchema: z.ZodObject<{
         differsBy: string;
     }[] | undefined;
     changedFile?: string | undefined;
-    changes?: string[] | undefined;
+    defects?: string[] | undefined;
     routes?: {
         file: string;
         step: number;
     }[] | undefined;
+    changes?: string[] | undefined;
     elements?: {
         items?: {
             role: string;
@@ -250,6 +253,7 @@ declare const registerPlannedTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     declarations: z.ZodOptional<z.ZodEffects<z.ZodObject<{
         changedFile: z.ZodOptional<z.ZodString>;
         changes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        defects: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         asserts: z.ZodString;
         stepUnderTest: z.ZodOptional<z.ZodNumber>;
         expected: z.ZodObject<{
@@ -361,11 +365,12 @@ declare const registerPlannedTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             differsBy: string;
         }[] | undefined;
         changedFile?: string | undefined;
-        changes?: string[] | undefined;
+        defects?: string[] | undefined;
         routes?: {
             file: string;
             step: number;
         }[] | undefined;
+        changes?: string[] | undefined;
         elements?: {
             items?: {
                 role: string;
@@ -398,11 +403,12 @@ declare const registerPlannedTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             differsBy: string;
         }[] | undefined;
         changedFile?: string | undefined;
-        changes?: string[] | undefined;
+        defects?: string[] | undefined;
         routes?: {
             file: string;
             step: number;
         }[] | undefined;
+        changes?: string[] | undefined;
         elements?: {
             items?: {
                 role: string;
@@ -435,11 +441,12 @@ declare const registerPlannedTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             differsBy: string;
         }[] | undefined;
         changedFile?: string | undefined;
-        changes?: string[] | undefined;
+        defects?: string[] | undefined;
         routes?: {
             file: string;
             step: number;
         }[] | undefined;
+        changes?: string[] | undefined;
         elements?: {
             items?: {
                 role: string;
@@ -472,11 +479,12 @@ declare const registerPlannedTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             differsBy: string;
         }[] | undefined;
         changedFile?: string | undefined;
-        changes?: string[] | undefined;
+        defects?: string[] | undefined;
         routes?: {
             file: string;
             step: number;
         }[] | undefined;
+        changes?: string[] | undefined;
         elements?: {
             items?: {
                 role: string;
@@ -502,8 +510,8 @@ declare const registerPlannedTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     description: string;
     testType: TestType.CONTRACT | TestType.INTEGRATION | TestType.E2E | TestType.UI;
-    scenarioName: string;
     category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    scenarioName: string;
     steps: {
         path: string;
         method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS" | "type" | "TRACE" | "CONNECT" | "assert" | "click" | "drag" | "drag-hold" | "hover" | "inspect" | "navigate" | "press" | "release" | "tap" | "wait" | "OPERATION";
@@ -527,11 +535,12 @@ declare const registerPlannedTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             differsBy: string;
         }[] | undefined;
         changedFile?: string | undefined;
-        changes?: string[] | undefined;
+        defects?: string[] | undefined;
         routes?: {
             file: string;
             step: number;
         }[] | undefined;
+        changes?: string[] | undefined;
         elements?: {
             items?: {
                 role: string;
@@ -557,8 +566,8 @@ declare const registerPlannedTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
 }, {
     description: string;
     testType: TestType.CONTRACT | TestType.INTEGRATION | TestType.E2E | TestType.UI;
-    scenarioName: string;
     category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    scenarioName: string;
     steps: {
         path: string;
         order: number;
@@ -582,11 +591,12 @@ declare const registerPlannedTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             differsBy: string;
         }[] | undefined;
         changedFile?: string | undefined;
-        changes?: string[] | undefined;
+        defects?: string[] | undefined;
         routes?: {
             file: string;
             step: number;
         }[] | undefined;
+        changes?: string[] | undefined;
         elements?: {
             items?: {
                 role: string;
@@ -612,8 +622,8 @@ declare const registerPlannedTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
 }>, {
     description: string;
     testType: TestType.CONTRACT | TestType.INTEGRATION | TestType.E2E | TestType.UI;
-    scenarioName: string;
     category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    scenarioName: string;
     steps: {
         path: string;
         method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS" | "type" | "TRACE" | "CONNECT" | "assert" | "click" | "drag" | "drag-hold" | "hover" | "inspect" | "navigate" | "press" | "release" | "tap" | "wait" | "OPERATION";
@@ -637,11 +647,12 @@ declare const registerPlannedTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             differsBy: string;
         }[] | undefined;
         changedFile?: string | undefined;
-        changes?: string[] | undefined;
+        defects?: string[] | undefined;
         routes?: {
             file: string;
             step: number;
         }[] | undefined;
+        changes?: string[] | undefined;
         elements?: {
             items?: {
                 role: string;
@@ -667,8 +678,8 @@ declare const registerPlannedTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
 }, {
     description: string;
     testType: TestType.CONTRACT | TestType.INTEGRATION | TestType.E2E | TestType.UI;
-    scenarioName: string;
     category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    scenarioName: string;
     steps: {
         path: string;
         order: number;
@@ -692,11 +703,12 @@ declare const registerPlannedTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             differsBy: string;
         }[] | undefined;
         changedFile?: string | undefined;
-        changes?: string[] | undefined;
+        defects?: string[] | undefined;
         routes?: {
             file: string;
             step: number;
         }[] | undefined;
+        changes?: string[] | undefined;
         elements?: {
             items?: {
                 role: string;
@@ -722,8 +734,8 @@ declare const registerPlannedTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
 }>, {
     description: string;
     testType: TestType.CONTRACT | TestType.INTEGRATION | TestType.E2E | TestType.UI;
-    scenarioName: string;
     category: "new_endpoint" | "bug_caught" | "requirement_conflict" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    scenarioName: string;
     steps: {
         path: string;
         method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS" | "type" | "TRACE" | "CONNECT" | "assert" | "click" | "drag" | "drag-hold" | "hover" | "inspect" | "navigate" | "press" | "release" | "tap" | "wait" | "OPERATION";
@@ -747,11 +759,12 @@ declare const registerPlannedTestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             differsBy: string;
         }[] | undefined;
         changedFile?: string | undefined;
-        changes?: string[] | undefined;
+        defects?: string[] | undefined;
         routes?: {
             file: string;
             step: number;
         }[] | undefined;
+        changes?: string[] | undefined;
         elements?: {
             items?: {
                 role: string;
@@ -779,7 +792,9 @@ type RegisterPlannedTestInput = z.infer<typeof registerPlannedTestSchema>;
 export interface RegisterTestPlanParams {
     stateFile?: string;
     changes?: PlanChange[];
+    defects?: PlanDefect[];
     plannedTests?: RegisterPlannedTestInput[];
+    maintains?: PlanMaintenance[];
     answers?: ObjectionAnswer[];
 }
 /** Map the schema-validated input onto a `PlanInput`. `subjectEndpoints` is

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

@@ -3,6 +3,7 @@ import * as fs from "fs";
 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 { toolError } from "../../utils/utils.js";
 import { TestType } from "../../types/TestTypes.js";
@@ -13,6 +14,7 @@ import { STEP_METHOD_DESCRIPTION, normalizeStepMethod, stepMethodSchema } from "
 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";
@@ -62,7 +64,11 @@ export const declarationFieldsSchema = z.object({
     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."),
+        .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."),
@@ -75,7 +81,7 @@ export const declarationFieldsSchema = z.object({
         .object({
         outcome: z
             .enum(["fail", "pass"])
-            .describe("Whether this test should fail or pass against the app as it stands."),
+            .describe("Whether this test should fail or pass against the app as it stands. Every case a `fail` test sends carries `expectedValue` or `derived`, never both."),
         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."),
@@ -171,17 +177,6 @@ function namesAScreen(url) {
  *  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
@@ -294,9 +289,16 @@ const registerTestPlanSchema = {
             .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."),
+        quote: z
+            .string()
+            .optional()
+            .describe("The requirement in the words the pull request uses, when `source` is `pr-title` or `pr-description`. CHECKED on a change a `requirement_conflict` test cites: the quote must appear in the title or description."),
         source: z
             .string()
-            .describe("Where you read it: `pr-description`, `spec:<path>` for a requirements file the description names, or `diff`."),
+            .refine((value) => /^(pr-title|pr-description|diff|spec:\S.*)$/i.test(value.trim()), {
+            message: "source must be `pr-title`, `pr-description`, `diff`, or `spec:<path>`",
+        })
+            .describe("Where you read it: `pr-title`, `pr-description`, `spec:<path>` for a requirements file the description names, or `diff`."),
         surfaces: z
             .array(z.enum(["api", "page"]))
             .min(1)
@@ -313,10 +315,31 @@ const registerTestPlanSchema = {
             expect: z
                 .enum(["accept", "reject"])
                 .describe("Whether the route must accept this value or reject it."),
+            expectedValue: z
+                .union([z.string(), z.number(), z.boolean(), z.null()])
+                .optional()
+                .describe("What the response must carry when this case is sent — the value itself, not a description of it. Declare it here so the test asserts what the change is supposed to do; a value decided while the test is being written can only be the value the running app returned, which is the one value a defect cannot contradict. Leave it out when no source states the value, and the test will assert the shape instead. `expectedValue` and `derived` are alternatives: a case declares one of them, never both. A test that expects to fail declares one of them on every case it sends."),
+            derived: z
+                .string()
+                .optional()
+                .describe("The rule the value follows from, in the source's words, when the source states a rule and not the value: `10 percent of the subtotal`. A test computes the value from what it sent. Use this instead of `expectedValue` whenever the pull request states the rule but never writes the number."),
+            expectedFrom: z
+                .string()
+                .refine((value) => /^(pr-title|pr-description|code|spec:\S.*|convention:\S.*)$/i.test(value.trim()), {
+                message: "expectedFrom must be `pr-title`, `pr-description`, `code`, `spec:<path>`, or `convention:<file:line>`",
+            })
+                .optional()
+                .describe("Where you read `expectedValue` or `derived`: `pr-title`, `pr-description`, `spec:<path>` for a requirements file the description names, `convention:<file:line>` for a rule the application already follows in code this pull request did not change, or `code` for the code under test. `code` draws an objection — it is the one source that agrees with a defect — so name it only when nothing else states the value. A value read from the pull request has to be WRITTEN there — in the quoted sentence or elsewhere in the title or description. If the pull request states the rule and never writes the number, leave `expectedValue` out and put the rule in `derived`. A case that declares `expectedValue` or `derived` and names no source here draws an objection."),
         })
             .strict()
             .refine((entry) => (entry.value !== undefined) !== (entry.absent === true), {
             message: "a case states either `value` or `absent`, never both and never neither",
+        })
+            // 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, {
+            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" })
             .optional()
@@ -343,6 +366,43 @@ const registerTestPlanSchema = {
     })
         .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."),
+    // `.default([])`, like `changes`: an empty list draws `defects:none`, which is
+    // exactly the objection a plan that reports no review should draw.
+    defects: z
+        .array(z
+        .object({
+        id: z
+            .string()
+            .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."),
+        description: z.string().describe("What is wrong, in one line."),
+        severity: z
+            .enum(["critical", "high", "medium", "low"])
+            .describe("critical = feature broken or data corrupted; high = wrong behaviour; medium = minor functional gap; low = cosmetic."),
+    })
+        .strict())
+        .superRefine((defects, ctx) => {
+        const first = new Map();
+        defects.forEach((defect, index) => {
+            const key = String(defect?.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: `defect id "${defect.id}" is already used by defect ${seen + 1}. Every defect needs its own id — planned tests cite it by that id.`,
+            });
+        });
+    })
+        .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."),
     // 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
@@ -374,6 +434,20 @@ const registerTestPlanSchema = {
         });
     })
         .describe("Your complete plan, unordered. Nothing ranks, dedups, reorders or trims it, and the server adds no planned test of its own."),
+    maintains: z
+        .array(z
+        .object({
+        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."),
+    })
+        .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."),
     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."),
@@ -381,7 +455,7 @@ const registerTestPlanSchema = {
         blocker: z
             .string()
             .optional()
-            .describe("What stopped this run from writing the test: a service that is not running, a paired branch that no longer exists, the one credential the run holds. An objection about a change with no test closes only with this. A reason the change is not worth testing is not a blocker."),
+            .describe("What stopped this run from writing the test: a service that is not running, a paired branch that no longer exists, the one credential the run holds. An objection about a change or a defect with no test closes only with this. A reason the change is not worth testing is not a blocker."),
     }).strict())
         .default([])
         .describe("One answer per objection from your previous registration that you do not intend to fix. There is no registration limit."),
@@ -394,7 +468,9 @@ const registerTestPlanSchema = {
 export function buildRegistration(params, registrationNumber) {
     return {
         changes: params.changes ?? [],
+        defects: params.defects ?? [],
         answers: params.answers ?? [],
+        ...(params.maintains?.length ? { maintains: params.maintains } : {}),
         // The tool counts the run's registrations; whatever the caller sent is ignored.
         registrationNumber,
         plannedTests: (params.plannedTests ?? []).map((input) => {
@@ -530,6 +606,16 @@ async function changedFilesForVerification(section) {
         return undefined;
     }
 }
+/** The pull request the prompt was rendered with. Blank on both fields only when
+ *  no entry point recorded one, which is not a state the testbot produces: it
+ *  fetches its prompt from this server. */
+function recordedPullRequest() {
+    const recorded = pullRequestText();
+    if (recorded)
+        return recorded;
+    logger.warning("No pull request text was recorded before the plan was registered; the checks that read it will see an empty pull request.");
+    return { title: "", description: "" };
+}
 /** Every fact the verifiers check against, gathered once per registration. */
 export async function buildVerifyContext(state) {
     const sections = repoSections(state);
@@ -543,6 +629,9 @@ export async function buildVerifyContext(state) {
         // 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 process for the same reason: this server rendered the prompt, so it
+        // already holds the title and description the run was given.
+        pullRequest: recordedPullRequest(),
         // 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.
@@ -561,7 +650,7 @@ export async function buildVerifyContext(state) {
 export function renderPlanResult(result) {
     const lines = [];
     lines.push(`Registration ${result.plan.registrationNumber} stored as this run's plan.`);
-    lines.push(`Plan: ${result.plan.plannedTests.length} planned test(s).`);
+    lines.push(`Plan: ${result.plan.plannedTests.length} planned test(s), ${(result.plan.defects ?? []).length} defect(s).`);
     // A convenience: `differsFrom` also accepts a `scenarioName`.
     for (const plannedTest of result.plan.plannedTests) {
         lines.push(`- ${plannedTest.plannedTestId} — ${plannedTest.scenario?.scenarioName ?? "(unnamed)"}`);