@skyramp/mcp 0.4.0 → 0.4.1-rc.1

package/build/recommendation/verifiers/issueTraceability.js

@@ -0,0 +1,197 @@
+const NORMAL_LANE = { planOnly: false };
+/** An id as the plan spells it: trimmed, and exact otherwise. */
+function idKey(raw) {
+    return typeof raw === "string" ? raw.trim() : "";
+}
+/** The plan's defects that carry an id. Read defensively: the plan comes off disk,
+ *  and a plan stored before this field existed has none. */
+function declaredDefects(plan) {
+    const raw = plan?.defects;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((defect) => idKey(defect?.id).length > 0);
+}
+/** The defect ids one planned test cites. */
+function citedDefects(plannedTest) {
+    const declared = plannedTest?.declarations?.defects;
+    return Array.isArray(declared) ? declared.map(idKey).filter(Boolean) : [];
+}
+/** Whether the plan declares this test as one that expects to fail. Undeclared
+ *  reads as not failing, exactly as the plan-time `defects` verifier reads it: a
+ *  test that says nothing about its outcome proves nothing about a bug. */
+function expectsToFail(plannedTest) {
+    return plannedTest?.declarations?.expected?.outcome === "fail";
+}
+/** How many characters of an issue's description the objection quotes. */
+const QUOTE_LENGTH = 80;
+function quote(description) {
+    const text = String(description ?? "").trim().replace(/\s+/g, " ");
+    return text.length > QUOTE_LENGTH ? `${text.slice(0, QUOTE_LENGTH)}…` : text;
+}
+/** The plan-time `defects:untested:<id>` objection, as the plan-time verifier ids it. */
+const UNTESTED_PREFIX = "defects:untested:";
+/** Defect ids whose `defects:untested:<id>` objection the agent closed when it
+ *  registered the plan, by an answer or by a blocker. Both buckets: a blocker
+ *  close is stored apart from an answer and is a close all the same. Read
+ *  defensively: the plan comes off disk. */
+function answeredUntested(plan) {
+    const closed = [
+        ...(Array.isArray(plan?.answeredObjections) ? plan.answeredObjections : []),
+        ...(Array.isArray(plan?.unverifiedCloses) ? plan.unverifiedCloses : []),
+    ];
+    const ids = new Set();
+    for (const entry of closed) {
+        const objectionId = idKey(entry?.objection?.objectionId);
+        if (!objectionId.startsWith(UNTESTED_PREFIX))
+            continue;
+        if (idKey(entry?.answer).length === 0)
+            continue;
+        const id = idKey(objectionId.slice(UNTESTED_PREFIX.length));
+        if (id)
+            ids.add(id);
+    }
+    return ids;
+}
+/** Where the defect sits, as the objection quotes it. */
+function locate(defect) {
+    const file = String(defect?.file ?? "").trim() || "no file";
+    return typeof defect?.line === "number" ? `${file}:${defect.line}` : file;
+}
+/** Report-time. Every `category: bug` issue names the test that proves it, by
+ *  `plannedTestId` or through a `defectId`, or it draws an objection the agent
+ *  answers. Run 34283539284 reported six bugs with no test behind any of them and
+ *  nothing said so; the one test near the headline bug asserted a value that
+ *  passes against the broken output.
+ *
+ *  A test proves a bug when the run DELIVERED it and the plan declares it as one
+ *  that expects to fail. Both halves matter. A planned test the run never wrote is
+ *  a promise, not proof, and the plan-time objections already hold the agent to
+ *  those — except in the plan-only lane, which delivers nothing by design, so
+ *  there a planned test is as far as a trace can go. A test the plan declares
+ *  green is the run-34283539284 case itself: it passes against the broken output,
+ *  so it says nothing about the bug. The plan is the only place a delivered test's
+ *  expected outcome is written down, so a delivered test that joins to no planned
+ *  test carries no such declaration and does not count either.
+ *
+ *  A `defectId` counts the same way, and only for an id the plan's own `defects`
+ *  list declares: `declarations.defects` is free text until it is joined to that
+ *  list, so an unjoined id would let a report invent a defect and trace every bug
+ *  through it.
+ *
+ *  A declared `defectId` also counts when the agent answered `defects:untested:<id>`
+ *  at plan time (or closed it with a blocker). The plan-time verifier asked why no
+ *  test proves that defect and the agent said; asking again here is the same
+ *  question twice, and the answer is already published with the plan. */
+export function checkIssueTraceability(plan, delivered, issues, lane = NORMAL_LANE) {
+    const shipped = new Set(delivered.map((test) => idKey(test?.plannedTestId)).filter(Boolean));
+    const plannedTests = Array.isArray(plan?.plannedTests) ? plan.plannedTests : [];
+    // The join that gives a delivered test its expected outcome. First entry wins:
+    // a repeated id is the plan's own duplicate, and the checks that own it are the
+    // plan-time ones.
+    const plannedById = new Map();
+    for (const plannedTest of plannedTests) {
+        const id = idKey(plannedTest?.plannedTestId);
+        if (id && !plannedById.has(id))
+            plannedById.set(id, plannedTest);
+    }
+    // In the plan-only lane a planned test stands where a delivered one would.
+    const inHand = (plannedTestId) => shipped.has(plannedTestId) || (lane.planOnly && plannedById.has(plannedTestId));
+    const proves = (plannedTestId) => inHand(plannedTestId) && expectsToFail(plannedById.get(plannedTestId));
+    /** Why this id proves nothing, in the words the objection uses. */
+    const gap = (plannedTestId) => {
+        if (!inHand(plannedTestId)) {
+            return plannedById.has(plannedTestId)
+                ? `plannedTestId "${plannedTestId}" names a planned test the run did not deliver`
+                : `plannedTestId "${plannedTestId}" names no delivered or planned test`;
+        }
+        const word = lane.planOnly ? "planned" : "delivered";
+        return plannedById.has(plannedTestId)
+            ? `plannedTestId "${plannedTestId}" names a ${word} test the plan declares as expecting to pass, and a test that passes today proves nothing about a bug`
+            : `plannedTestId "${plannedTestId}" names a ${word} test that no planned test declares, so nothing says it expects to fail`;
+    };
+    const known = new Set(declaredDefects(plan).map((defect) => idKey(defect.id)));
+    // Declared defect id -> the tests that prove it: in hand, and red by declaration.
+    const provenBy = new Map();
+    // Declared defect id -> the tests that cite it and prove nothing. Evidence only.
+    const citedWeakly = new Map();
+    for (const plannedTest of plannedTests) {
+        const id = idKey(plannedTest?.plannedTestId);
+        if (!id || !inHand(id))
+            continue;
+        const bucket = proves(id) ? provenBy : citedWeakly;
+        for (const defectId of citedDefects(plannedTest)) {
+            if (!known.has(defectId))
+                continue;
+            bucket.set(defectId, [...(bucket.get(defectId) ?? []), id]);
+        }
+    }
+    const answered = answeredUntested(plan);
+    const objections = [];
+    issues.forEach((issue, index) => {
+        if (String(issue?.category ?? "").trim().toLowerCase() !== "bug")
+            return;
+        const plannedTestId = idKey(issue?.plannedTestId);
+        if (plannedTestId && proves(plannedTestId))
+            return;
+        const defectId = idKey(issue?.defectId);
+        const declaredDefect = defectId.length > 0 && known.has(defectId);
+        if (declaredDefect && ((provenBy.get(defectId) ?? []).length > 0 || answered.has(defectId)))
+            return;
+        const named = [];
+        if (plannedTestId)
+            named.push(gap(plannedTestId));
+        if (defectId) {
+            const word = lane.planOnly ? "planned" : "delivered";
+            if (!declaredDefect) {
+                named.push(`defectId "${defectId}" names no defect this plan declares`);
+            }
+            else if ((citedWeakly.get(defectId) ?? []).length > 0) {
+                named.push(`defectId "${defectId}" is cited by no ${word} test that expects to fail: ${(citedWeakly.get(defectId) ?? []).join(", ")} cite it and the plan declares each as expecting to pass`);
+            }
+            else {
+                named.push(`defectId "${defectId}" is cited by no ${word} test that expects to fail and no plan-time answer closed ${UNTESTED_PREFIX}${defectId}`);
+            }
+        }
+        const where = String(issue?.sourceFile ?? "").trim() || "no sourceFile";
+        objections.push({
+            // Keyed on the entry's position: an issue has no id of its own. The
+            // message NAMES the issue because the report-stage carry matches on the id
+            // AND the message: with a fixed message, an answer given for the bug at
+            // index 0 would follow index 0 to whatever bug the next call put there.
+            objectionId: `issueTraceability:${index}`,
+            verifier: "issueTraceability",
+            message: `No test proves this bug: "${quote(issue?.description)}" (${where}).`,
+            evidence: `issuesFound[${index}]: ${named.length > 0 ? named.join("; ") : "no plannedTestId and no defectId"}.`,
+            suggestion: "Set `plannedTestId` to the delivered test that proves this bug — one the plan declares with `expected.outcome: fail`, so it stays red until the bug is fixed — or set `defectId` to a declared plan defect such a test cites. If no test proves it, answer in one line why.",
+        });
+    });
+    return objections;
+}
+/** Report-time. Every defect the plan declared is an `issuesFound` entry that
+ *  names it by `defectId`. The review found it; the report must show it. */
+export function checkDefectsReported(plan, issues) {
+    // Only a `category: bug` entry reports a defect. The schema takes a `defectId`
+    // on a lint, type or config entry too, and the report renders those in its own
+    // Configuration Errors section — a defect parked there is one the reader never
+    // meets under Issues Found, and it would close this check all the same.
+    const reported = new Set(issues
+        .filter((issue) => String(issue?.category ?? "").trim().toLowerCase() === "bug")
+        .map((issue) => idKey(issue?.defectId))
+        .filter(Boolean));
+    const objections = [];
+    const seen = new Set();
+    for (const defect of declaredDefects(plan)) {
+        const id = idKey(defect.id);
+        if (seen.has(id) || reported.has(id))
+            continue;
+        seen.add(id);
+        objections.push({
+            objectionId: `defects:unreported:${id}`,
+            verifier: "defects",
+            message: "The plan declares this defect and no issue in the report names it.",
+            evidence: `defect ${id} (${locate(defect)}): "${String(defect.description ?? "").trim()}"; no issuesFound entry carries defectId "${id}".`,
+            suggestion: "Add an `issuesFound` entry for it with `category: bug`, `defectId` set to this id, and the `plannedTestId` of the test that proves it. If the review was wrong and there is no defect, answer in one line what you found.",
+        });
+    }
+    return objections;
+}

package/build/recommendation/verifiers/requirementSourced.d.ts

@@ -0,0 +1,2 @@
+import { Verifier } from "../types.js";
+export declare const requirementSourced: Verifier;

package/build/recommendation/verifiers/requirementSourced.js

@@ -0,0 +1,168 @@
+import { normalizeCategory } from "../../types/TestRecommendation.js";
+import { REQUIREMENT_SOURCED_CONTRACT, fillPlaceholders } from "../verifierContracts.js";
+import { normalizeCitedPath } from "./citedPath.js";
+import { appearsIn, searchable } from "../pullRequestText.js";
+/** Verifier 10. A change names where the agent read it, and the server reads the
+ *  name back.
+ *
+ *  `source` is the record of where a change came from, and the server holds the
+ *  pull request's own words, so it reads the claim back against them: a `spec:` path
+ *  has to name a file the checkout holds AND a file the pull request names, and a
+ *  change read from the pull request has to quote words the pull request carries.
+ *
+ *  A conflict is a disagreement between a requirement and the code. A change read
+ *  off the diff IS the code, so there is no second side for it to disagree with.
+ *
+ *  The plan tool always supplies the pull request: the testbot fetches its prompt
+ *  from this same server, so the text is in the process. Both fields blank means
+ *  the run had no title and no description. */
+const { unsourced: UNSOURCED, unreadable: UNREADABLE, fromDiff: FROM_DIFF, noChange: NO_CHANGE, notNamed: NOT_NAMED, emptyPullRequest: EMPTY_PULL_REQUEST, notQuoted: NOT_QUOTED, unquoted: UNQUOTED, } = REQUIREMENT_SOURCED_CONTRACT.objections;
+const CONFLICT_CATEGORY = "requirement_conflict";
+function readSource(raw) {
+    const none = (kind) => ({ kind, file: "", citedAs: "" });
+    const source = typeof raw === "string" ? raw.trim() : "";
+    if (source.length === 0)
+        return none("unknown");
+    if (/^(pr-title|pr-description)$/i.test(source))
+        return none("pullRequest");
+    if (/^diff$/i.test(source))
+        return none("diff");
+    const named = /^spec:(.*)$/i.exec(source);
+    if (!named)
+        return none("unknown");
+    const citedAs = named[1]
+        .split(/[#§]/)[0]
+        .replace(/(?::\d+)+(?:-\d+)?$/, "")
+        .trim();
+    const file = normalizeCitedPath(citedAs);
+    // `spec:` with nothing after it names no file, so there is nothing to check and
+    // nothing to trust either.
+    return file ? { kind: "spec", file, citedAs } : none("unknown");
+}
+/** A source that stands for a requirement: the pull request, or a requirements file. */
+const statesARequirement = (source) => source.kind === "pullRequest" || source.kind === "spec";
+const text = (value) => (typeof value === "string" ? value.trim() : "");
+const list = (value) => (Array.isArray(value) ? value : []);
+export const requirementSourced = {
+    name: "requirementSourced",
+    run(registration, ctx) {
+        const changes = list(registration?.changes);
+        const plannedTests = list(registration?.plannedTests);
+        const objections = [];
+        const sourceById = new Map();
+        const quoteById = new Map();
+        const pullRequestText = searchable(ctx.pullRequest);
+        for (const change of changes) {
+            const changeId = text(change?.id) || "(unnamed)";
+            const written = text(change?.source);
+            const source = readSource(written);
+            if (text(change?.id)) {
+                sourceById.set(text(change.id), source);
+                quoteById.set(text(change.id), typeof change?.quote === "string" ? change.quote : undefined);
+            }
+            if (source.kind === "unknown") {
+                objections.push({
+                    objectionId: `requirementSourced:unsourced:${changeId}`,
+                    verifier: "requirementSourced",
+                    message: fillPlaceholders(UNSOURCED.message, { change: changeId }),
+                    evidence: `change ${changeId} states source \`${written || "(blank)"}\``,
+                    suggestion: UNSOURCED.suggestion,
+                });
+                continue;
+            }
+            if (source.kind === "pullRequest") {
+                if (pullRequestText.length > 0)
+                    continue;
+                objections.push({
+                    objectionId: `requirementSourced:emptyPullRequest:${changeId}`,
+                    verifier: "requirementSourced",
+                    message: fillPlaceholders(EMPTY_PULL_REQUEST.message, { change: changeId }),
+                    evidence: `change ${changeId} states source \`${written}\`; this run rendered its prompt with no title and no description`,
+                    suggestion: EMPTY_PULL_REQUEST.suggestion,
+                });
+                continue;
+            }
+            if (source.kind !== "spec")
+                continue;
+            if (typeof ctx?.citedFileExists === "function" && !ctx.citedFileExists(source.file)) {
+                objections.push({
+                    objectionId: `requirementSourced:unreadable:${changeId}`,
+                    verifier: "requirementSourced",
+                    message: fillPlaceholders(UNREADABLE.message, { change: changeId, source: written }),
+                    evidence: `change ${changeId} states source \`${written}\`; ${source.file} is not a file in the run's repositories`,
+                    suggestion: UNREADABLE.suggestion,
+                });
+                continue;
+            }
+            // A requirements file the pull request never names is a file the agent found by
+            // looking through the repository, which is not reading a requirement.
+            if (appearsIn(pullRequestText, source.file) || appearsIn(pullRequestText, source.citedAs))
+                continue;
+            objections.push({
+                objectionId: `requirementSourced:notNamed:${changeId}`,
+                verifier: "requirementSourced",
+                message: fillPlaceholders(NOT_NAMED.message, { change: changeId, source: written }),
+                evidence: `change ${changeId} states source \`${written}\`; neither the title nor the description names ${source.file}`,
+                suggestion: NOT_NAMED.suggestion,
+            });
+        }
+        for (const plannedTest of plannedTests) {
+            if (normalizeCategory(plannedTest?.scenario?.category) !== CONFLICT_CATEGORY)
+                continue;
+            const plannedTestId = text(plannedTest?.plannedTestId);
+            const named = plannedTestId ? { plannedTestId } : {};
+            // An id no change carries names nothing, so it says no more than citing
+            // nothing does. Both leave the requirement with no stated origin.
+            const cited = list(plannedTest?.declarations?.changes)
+                .map((changeId) => text(changeId))
+                .filter((changeId) => sourceById.has(changeId));
+            if (cited.length === 0) {
+                objections.push({
+                    objectionId: `requirementSourced:noChange:${plannedTestId || "plan"}`,
+                    verifier: "requirementSourced",
+                    ...named,
+                    message: NO_CHANGE.message,
+                    evidence: `planned test ${plannedTestId || "(unnamed)"} reports a requirement conflict and cites no change this plan declares`,
+                    suggestion: NO_CHANGE.suggestion,
+                });
+                continue;
+            }
+            if (cited.some((changeId) => statesARequirement(sourceById.get(changeId)))) {
+                // The quote is what makes the claim checkable. One objection per test, on the
+                // first cited change that does not carry one the pull request holds.
+                const offending = cited.find((changeId) => {
+                    if (sourceById.get(changeId)?.kind !== "pullRequest")
+                        return false;
+                    const quote = quoteById.get(changeId);
+                    return quote === undefined || !appearsIn(pullRequestText, quote);
+                });
+                if (offending === undefined)
+                    continue;
+                const quote = quoteById.get(offending);
+                const objection = quote === undefined ? UNQUOTED : NOT_QUOTED;
+                objections.push({
+                    objectionId: `requirementSourced:notQuoted:${plannedTestId || "plan"}`,
+                    verifier: "requirementSourced",
+                    ...named,
+                    message: fillPlaceholders(objection.message, { change: offending }),
+                    evidence: quote === undefined
+                        ? `planned test ${plannedTestId || "(unnamed)"} cites ${offending}, which states no \`quote\``
+                        : `planned test ${plannedTestId || "(unnamed)"} cites ${offending}, whose quote \`${quote}\` is in neither the title nor the description`,
+                    suggestion: objection.suggestion,
+                });
+                continue;
+            }
+            objections.push({
+                objectionId: `requirementSourced:fromDiff:${plannedTestId || "plan"}`,
+                verifier: "requirementSourced",
+                ...named,
+                message: FROM_DIFF.message,
+                evidence: `planned test ${plannedTestId || "(unnamed)"} cites ${cited
+                    .map((changeId) => `${changeId} (kind ${sourceById.get(changeId)?.kind})`)
+                    .join(", ")}`,
+                suggestion: FROM_DIFF.suggestion,
+            });
+        }
+        return objections;
+    },
+};

package/build/tools/submitReportTool.js

@@ -15,6 +15,7 @@ import { isTestbotEnabled, } from "../utils/featureFlags.js";
 import { answerFor, unknownAnswerObjections } from "../recommendation/answers.js";
 import { checkDeliveredMatchesPlan } from "../recommendation/verifiers/deliveredMatchesPlan.js";
 import { checkReportedCategoryMatchesPlan, checkRequirementConflictReported, } from "../recommendation/verifiers/reportedCategory.js";
+import { checkDefectsReported, checkIssueTraceability } from "../recommendation/verifiers/issueTraceability.js";
 import { checkExpectedOutcomeAfterExecution, } from "../recommendation/verifiers/expectedOutcome.js";
 import { findInvalidSourceCitations, findUnchangedFileClaims, listChangedFiles, listChangedFilesAcross, listChangedFilesAbs, } from "../utils/reportVerification.js";
 import { isPlanOnlyMode } from "../utils/planOnlyMode.js";
@@ -322,7 +323,15 @@ const issueFoundSchema = z
     plannedTestId: z
         .string()
         .optional()
-        .describe("The `plannedTestId` of the planned test this issue is about, when it is about one. Set it on the issue you record for a `requirement_conflict` test so the conflict is tied to the test that asserts it; otherwise leave it out."),
+        .describe("The `plannedTestId` of the DELIVERED test that proves this issue. Your plan declares that test with `expected.outcome: fail`, so it stays red until the issue is fixed; a `requirement_conflict` test that asserts the requirement is declared the same way. A planned test you did not write proves nothing, and a test the plan declares green proves nothing either. " +
+        "This field is CONDITIONAL, not required on every bug: set it when such a test exists; set `defectId` instead when a plan defect traces the issue; leave both out when no test proves the issue. " +
+        "CHECKED on a `bug` entry: one that neither names a delivered red test here nor traces through `defectId` draws an objection you answer in one line."),
+    defectId: z
+        .string()
+        .optional()
+        .describe("The `id` of the plan defect this issue reports, from the `defects` list you registered with skyramp_register_test_plan. Spell it as that list spells it: an id the plan does not declare traces nothing. " +
+        "Set it on the `category: bug` entry that reports the defect. A `defectId` on a `lint`, `type` or `config` entry does not report the defect — the report renders those in its own Configuration Errors section. " +
+        "CHECKED: every plan defect has a `bug` issue that names it, and a `bug` entry with no `plannedTestId` traces through this defect when a delivered test that expects to fail cites it, or when you answered `defects:untested:<id>` at plan time. Leave it out for an issue the plan did not declare."),
     sourceFile: citationString.describe("Path of the application file whose code is missing or wrong, relative to the repository root (e.g. 'src/crud/products.py'). " +
         "REQUIRED when category is 'bug'. " +
         "For code that is MISSING — an unmounted router, an unregistered route, an import never added — name the file where the line should be, not the file that defines what is unmounted. " +
@@ -812,7 +821,10 @@ const PLANNABLE_TEST_TYPES = new Set([
     TestType.E2E,
     TestType.UI,
 ]);
-function runPostExecutionChecks(plan, delivered, results, issues) {
+function runPostExecutionChecks(plan, delivered, results, issues, 
+/** The plan-only lane delivers nothing, so there a planned test is proof
+ *  enough for a bug. Passed in, not read here, so the checks stay pure. */
+planOnly) {
     const shipped = delivered
         // A smoke, fuzz or load entry is filtered out rather than reported as
         // unplanned: a plan cannot hold one, so the objection would name a mistake the
@@ -826,6 +838,10 @@ function runPostExecutionChecks(plan, delivered, results, issues) {
         ...runPostExecutionCheck("expectedOutcome", "expectedOutcome:executed", () => checkExpectedOutcomeAfterExecution(plan, collectExecutionOutcomes(delivered, results), issues)),
         ...runPostExecutionCheck("reportedCategory", "reportedCategory", () => checkReportedCategoryMatchesPlan(plan, delivered)),
         ...runPostExecutionCheck("requirementConflictReported", "requirementConflictReported", () => checkRequirementConflictReported(plan, delivered, issues)),
+        // Both halves of the review's accountability, and neither refuses the report:
+        // a bug with no test behind it, and a plan defect the report never mentions.
+        ...runPostExecutionCheck("issueTraceability", "issueTraceability", () => checkIssueTraceability(plan, shipped, issues, { planOnly })),
+        ...runPostExecutionCheck("defectsReported", "defects:unreported", () => checkDefectsReported(plan, issues)),
     ];
 }
 export function registerSubmitReportTool(server) {
@@ -1357,7 +1373,7 @@ export function registerSubmitReportTool(server) {
         let objections;
         let changeTable;
         {
-            const postExecution = runPostExecutionChecks(stateData.plan ?? { plannedTests: [], registrationNumber: 0, answers: [], openObjections: [], answeredObjections: [] }, dedupedNewTests, params.testResults, params.issuesFound ?? []);
+            const postExecution = runPostExecutionChecks(stateData.plan ?? { plannedTests: [], registrationNumber: 0, answers: [], openObjections: [], answeredObjections: [] }, dedupedNewTests, params.testResults, params.issuesFound ?? [], isPlanOnlyMode());
             // Read defensively, like the crash-contained checks above: the plan comes
             // off disk, so its declared array type holds only on the validated path.
             const stillOpen = Array.isArray(stateData.plan?.openObjections)

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, 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,6 +792,7 @@ type RegisterPlannedTestInput = z.infer<typeof registerPlannedTestSchema>;
 export interface RegisterTestPlanParams {
     stateFile?: string;
     changes?: PlanChange[];
+    defects?: PlanDefect[];
     plannedTests?: RegisterPlannedTestInput[];
     answers?: ObjectionAnswer[];
 }