@skyramp/mcp 0.4.0-rc.2 → 0.4.1-rc.1

package/build/prompts/enhance-assertions/sharedAssertionRules.js

@@ -28,12 +28,13 @@ expect(response.statusCode).toBe(201);`,
         ],
     },
     {
-        title: "Error path (HTTP 4xx/5xx responses)",
-        description: "For every HTTP 4xx/5xx response that includes a response body, assert every error body field with its exact value — including `error.code`, `error.message`, `detail`, `errors[0].message`, and `errors[0].extensions.code`.",
+        title: "Error path (HTTP 4xx/5xx, or a 2xx carrying only an error body)",
+        description: "For every error response that includes a body, assert every error body field with its exact value — including `error.code`, `error.message`, `detail`, `errors[0].message`, and `errors[0].extensions.code`. An error response is any 4xx/5xx with a body, and any 2xx whose body is an error object (`error`, `message`, `errors[]`) with no resource payload.",
         subPoints: [
             "Also apply the array-validation rule to any errors array.",
             "Asserting only the status code is never sufficient when a body is present.",
             "For no-body responses such as a successful DELETE (204): assert the status code only.",
+            "For a 2xx error body, assert the exact status code, the error field's exact value, and that the resource fields carry no value (`toBeNull()` / `is None` — the SDK helper reads a missing path and an explicit null the same way, so this asserts \"no payload\", not \"key absent\"; use `checkSchema` when the two must be told apart). Never assert the success shape (a non-empty collection, `error` absent) against a response the recorded trace or `expected_response_body` shows returning an error or no-match body — classify the response by what this request returns, not by the outcome the test was meant to check for. The one exception is a test the plan declared `expected.outcome: fail` (typically a `bug_caught` or `requirement_conflict` candidate; the category is only the fallback when nothing was declared): it asserts the intended behaviour established by the diff, the PR statement, or the code's evident intent — keep that assertion and let the test fail.",
         ],
         examples: [
             {
@@ -43,6 +44,20 @@ expect(getValue(response, "errors.0.message")).toBe("Item not found");
 expect(getValue(response, "errors.0.extensions.code")).toBe("RECORD_NOT_FOUND");
 expect(getValue(response, "errors.1")).toBeNull();`,
             },
+            {
+                language: "javascript",
+                code: `// Recorded response is a 200 carrying an error object and no payload
+expect(searchPostResponse.statusCode, 'status code').toBe(200);
+expect(getResponseValue(searchPostResponse, "error"), 'error').toBe("No items matched the criteria.");
+expect(getResponseValue(searchPostResponse, "results"), 'results carries no value').toBeNull();`,
+            },
+            {
+                language: "python",
+                code: `# Recorded response: 400 {"error": "level must be one of Intern, Junior, Senior"}
+assert record_post_response.status_code == 400
+assert skyramp.get_response_value(record_post_response, "error") == "level must be one of Intern, Junior, Senior"
+assert skyramp.get_response_value(record_post_response, "insertedId") is None`,
+            },
         ],
     },
     {
@@ -77,7 +92,7 @@ expect(getValue(response, "errors.1")).toBeNull();`,
             "When the response is a non-empty array: assert the exact length, key fields on each item, and that the index after the last item is absent.",
             "Shape-only checks such as `Array.isArray` or `typeof` are not sufficient when the response contains actual values.",
             "If the response is sorted or ordered: assert the ordering direction across the first two items.",
-            "When the response is an empty or minimal body (an empty object, empty array, null, or only a few keys): assert the empty or minimal shape and the absence of error fields — do not stop at the status code.",
+            "When the response is an empty or minimal body (an empty object, empty array, null, or only a few keys): assert the empty or minimal shape and the absence of error fields — do not stop at the status code. A minimal body that is itself an error object falls under the Error path rule instead: assert its error field exactly.",
             "When the request includes pagination or filter parameters, assert the response reflects them.",
         ],
         examples: [
@@ -207,7 +222,8 @@ Before editing the given file, you must output a \`<thinking>\` block. The aim o
 2. Classify each response first by its response status type and then assign the applicable assertion rules to the response.
    1. Success with body (2xx with a response body): all assertion rules below may apply — echo-back of request fields, computed response fields, array / items validation, and chained values across steps.
    2. Success with no body (200/202/204 with an empty body — e.g. logout/cancel/submit action endpoints): assert the status code only. Also apply chained-values rules if a follow-up step uses this response's ID.
-   3. Error response (4xx/5xx with a body): assert every error body field with its exact value plus array / items validation on the \`errors[]\` array (exact length + per-item fields + next index null). Status code alone is never sufficient when a body is present — for example, also assert \`errors.0.extensions.code == 'INVALID_PAYLOAD'\` and that \`errors.1\` is null.
+   3. Error response (4xx/5xx with a body, or any status whose body is an error object such as \`{"error": "..."}\` with no resource payload): assert every error body field with its exact value plus array / items validation on the \`errors[]\` array (exact length + per-item fields + next index null). Status code alone is never sufficient when a body is present — for example, also assert \`errors.0.extensions.code == 'INVALID_PAYLOAD'\` and that \`errors.1\` is null.
+   Classify by the response the recorded trace or \`expected_response_body\` shows this request returning. The one exception is a test the plan declared \`expected.outcome: fail\` (typically a \`bug_caught\` or \`requirement_conflict\` candidate; read the declaration first and fall back to the category only when none was made): there the expected response is the intended behaviour established by the diff, the PR statement, or the code's evident intent, and the test is expected to fail until the code is fixed.
 3. For each in-scope response, output one JSON object using the template below. The output is an array — one object per in-scope response.
    - \`step\`: the HTTP method, path, and response variable name for this request (e.g. \`POST /products → products_POST_response\`).
    - \`response_status\`: one of \`success\`, \`no_body\`, or \`error\` based on the classification in step 2.

package/build/prompts/test-recommendation/test-recommendation-prompt.js

@@ -4,7 +4,6 @@ import { logger } from "../../utils/logger.js";
 import { buildArchitectPreamble, buildContextFetchingGuidance, buildReasoningProtocol, buildToolWorkflows, buildVerificationChecklist, } from "./recommendationSections.js";
 import { buildExecutionPlan, EXEC_STEP_ENRICH } from "./diffExecutionPlan.js";
 import { readPromptAsset } from "../promptAssets.js";
-import { renderPlanDeclarationGuidance } from "../testbot/planDeclarations.js";
 import { TASK_GENERATE, taskRef, } from "./recommendationShared.js";
 // Re-export for backward compatibility (tests and external callers import this from this module)
 function formatTestLocations(locs) {
@@ -22,11 +21,11 @@ function formatTestLocations(locs) {
 // on subsequent testbot runs on the same PR.
 const SKYRAMP_TEST_FILE_PATTERN = /(?:_test|_smoke|_contract|_fuzz|_integration|_load|_e2e|_ui)\.[^/]+$|scenario_[^/]+\.json$/;
 /** How this prompt tells the agent to plan: the whole procedure, every time.
- *  Rendered from `plugin/prompts/plan-tests.md` and `declaring-a-plan.md` rather
- *  than retyped, so there is one text and nothing to drift from. `isDiffScope` is
- *  unused here — the procedure reads the same for a diff and for a repository. */
+ *  Rendered from `plugin/prompts/plan-tests.md` rather than retyped, so there is
+ *  one text and nothing to drift from. `isDiffScope` is unused here — the
+ *  procedure reads the same for a diff and for a repository. */
 function planningInstruction(_isDiffScope) {
-    return `${readPromptAsset("plan-tests.md").trim()}\n\n${renderPlanDeclarationGuidance()}`;
+    return readPromptAsset("plan-tests.md").trim();
 }
 export function buildRecommendationPrompt(analysis, analysisScope = AnalysisScope.FullRepo, prContext, workspaceAuthHeader, workspaceAuthType, workspaceAuthScheme, sessionId) {
     const isDiffScope = isDiff(analysisScope);

package/build/prompts/testbot/testbot-prompts.js

@@ -4,10 +4,10 @@ import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { buildPathParamGuidance, } from "../test-recommendation/recommendationSections.js";
 import { setReportLanguage } from "../../utils/reportLanguage.js";
 import { setPlanOnlyMode } from "../../utils/planOnlyMode.js";
+import { recordPullRequestText } from "../../recommendation/pullRequestText.js";
 import { TASK_ANALYZE_MAINTAIN, TASK_GENERATE, TASK_SUBMIT, TESTBOT_TASK1_MAINTAIN_LABELS, TESTBOT_TASK1_MULTIREPO_LABELS, TESTBOT_TASK1_STEP_LABELS, orderedLabels, stepSubRef, taskRef, } from "../test-recommendation/recommendationShared.js";
 import { getTraceRecordingPromptText } from "../../playwright/traceRecordingPrompt.js";
 import { isContractConsumerModeEnabled, isPomReuseEnabled, isUtilsReuseEnabled, isSkillsLoaded, } from "../../utils/featureFlags.js";
-import { renderPlanDeclarationGuidance } from "./planDeclarations.js";
 import { fixErrorsInstruction } from "../../skills/fixTestImportErrorsSkill.js";
 import { resolveServiceDetailsRef } from "../../utils/utils.js";
 import { section, sectionBody } from "../promptAssets.js";
@@ -59,12 +59,12 @@ const PLAN_TESTS_MD = readPromptAsset("plan-tests.md").trim();
 // rendered neither it nor a copy, so the agent planned without the claims step and
 // without the backward surface map. Rendered here, never retyped.
 //
-// It sits OUTSIDE Task 1: the procedure is an eleven-item numbered list, Task 1's
+// It sits OUTSIDE Task 1: the procedure is a twelve-item numbered list, Task 1's
 // own steps are numbered too, and nested inside Task 1 the two share one ordinal
 // space (`referenceIntegrity.test.ts` reads every `N.` there as a Task 1 step).
 //
-// Two steps run elsewhere in this lane — step 6's maintenance update is Task 1's
-// tool step, step 9's registration happens in Task 2 after it. The note states that
+// Two steps run elsewhere in this lane — step 7's maintenance update is Task 1's
+// tool step, step 10's registration happens in Task 2 after it. The note states that
 // order; the markdown stays the source.
 //
 // The count sentence sits HERE, beside the register instruction, because the agent
@@ -173,6 +173,8 @@ export function parseRelatedRepositories(raw) {
 }
 export function getTestbotPrompt(opts) {
     const { prTitle, prDescription, repositoryPath, baseBranch, prNumber, userPrompt, services, uiCredentials, testsRepoDir, relatedRepositories, primaryRepo, planOnly = false, language, } = opts;
+    // Kept in the process for the plan tool, which is registered on this server.
+    recordPullRequestText(prTitle, prDescription);
     // The legacy count arguments are DECLARED NOWHERE, so zod strips them and their
     // names never reach the agent — not in a schema it lists, not in rendered text.
     // A number in front of the agent reads as a ceiling whatever the words around it
@@ -357,7 +359,7 @@ ${uiGroundingBlock}
 This is a plan-only evaluation run: the application under test is NOT running, and this run evaluates test SELECTION only. Nothing is generated or executed in this task.
 
 - Draft your complete plannedTest list — every test you would generate OR recommend for this PR, grounded in the analysis output and the diff. Favor tests that would FAIL if the changed logic were buggy, not just tests that exercise the new surface.
-- Register that list through \`skyramp_register_test_plan\` as "How to declare your plan" above describes. What you register is the plan — nothing re-ranks or trims it.
+- Register that list through \`skyramp_register_test_plan\` as the planning procedure above describes. What you register is the plan — nothing re-ranks or trims it.
 - Include UI and E2E planned tests on the same footing as the API types. The app is not running, so you cannot capture a blueprint — plan them ungrounded rather than drop them. For every UI plannedTest, set \`elements.items\` to null and set \`elements.pageUrl\` to the route path the test would visit, read out of the source: \`/orders/1\`, not a full URL, because no host is serving the app. Set \`screenEvidence.file\` to the changed frontend file that renders that route — the app not running does not excuse this one, because you read the file out of the diff. Describe the page or feature the test would exercise; do not name an element you have not seen. This lane is the one case where you fall back without attempting a capture first, so do NOT log the fallback in \`issuesFound\` — capture was never applicable here, and nothing failed.
 - Take no other actions in this task: no test generation tools, no browser traces or blueprint captures, no test files written, no test executions. Proceed directly to ${taskRef(TASK_SUBMIT)}.`;
     }
@@ -573,7 +575,7 @@ ${FINISH_CHECKS_BLOCK}
     // to name the changed file it is about, and cite the file it sits
     // in, and cite `routes` from the checkout, and all of those happen while
     // it analyzes in Task 1.
-    const planningBlock = `\n${planProcedureBlock}\n\n${renderPlanDeclarationGuidance()}\n`;
+    const planningBlock = `\n${planProcedureBlock}\n`;
     return `<TITLE>${prTitle}</TITLE>
 <DESCRIPTION>${prDescription}</DESCRIPTION>
 ${primaryRepoBlock}<REPOSITORY PATH>${repositoryPath}</REPOSITORY PATH>
@@ -603,9 +605,9 @@ In these cases:
 - \`issuesFound\` must be \`[]\` — do NOT add a "No testable behavioral surface" entry; the business case already explains the abstention
 - \`businessCaseAnalysis\` must be a one-sentence summary of what the PR actually does (do NOT leave it blank)
 
-**This zero-test path does NOT apply when the requirement check in ${taskRef(TASK_ANALYZE_MAINTAIN)} found a \`requirement_conflict\`.** A requirement the PR states and the diff did not implement is testable surface, whatever the diff otherwise contains. Report the conflict in \`issuesFound\` at severity \`high\` or above, and carry the failing \`requirement_conflict\` test in \`newTestsCreated\`. Where the requirement is observable nowhere you can reach, say that in \`businessCaseAnalysis\`. Abstaining there hands the author back their own code as though it were the requirement.
+**This zero-test path does NOT apply when the requirement check found a \`requirement_conflict\`.** A requirement the PR states and the diff did not implement is testable surface, whatever the diff otherwise contains. Report the conflict in \`issuesFound\` at severity \`high\` or above, and carry the failing \`requirement_conflict\` test in \`newTestsCreated\`. Where the requirement is observable nowhere you can reach, say that in \`businessCaseAnalysis\`. Abstaining there hands the author back their own code as though it were the requirement.
 
-${task3CountRule ? `${task3CountRule}\n\n` : ""}${reportLanguageBlock}Call \`skyramp_submit_report\`. Field names, types, and formats are defined in the tool's parameter schema — follow them exactly.
+${task3CountRule ? `${task3CountRule}\n\n` : ""}${reportLanguageBlock}Call \`skyramp_submit_report\`. Field names, types, and formats are defined in the tool's parameter schema — follow them exactly. A report check objects to an \`issuesFound\` entry with \`category: bug\` that no delivered test proves. The \`plannedTestId\` and \`defectId\` descriptions in the schema say what closes it. Answer an objection in one line.
 
 ${hasRelatedRepos
         ? `

package/build/recommendation/answers.d.ts

@@ -19,13 +19,17 @@ export declare function unknownAnswerObjections(objections: Objection[], acknowl
  *  leave the bug. `verifierContracts.ts` carries the evidence. */
 export declare const NON_ANSWERABLE_PREFIX = "coverage:stateTest:";
 export declare function isNonAnswerable(objectionId: unknown): boolean;
-/** The objection a sentence alone does not close either. A change with no test
- *  needs the test, unless this run could not write one — so the answer closes it
- *  only when it also names what stopped the run. Measured on run 34176038240:
- *  across eight fixtures 45 objections were raised and 45 were closed, and the one
- *  class that a sentence cannot close was never raised at all. Prose closed every
- *  uncovered change, including changes nothing prevented a test from reaching. */
-export declare const BLOCKER_ONLY_PREFIX = "coverage:change:";
+/** The objections a sentence alone does not close either. A change with no test
+ *  needs the test, and a defect with no test needs the test — a defect the code
+ *  already had before this pull request included. Either one closes only when the
+ *  answer also names what stopped the test: a service that is not running, a
+ *  branch that no longer exists, the one credential the run holds. Measured on run
+ *  34176038240: across eight fixtures 45 objections were raised and 45 were
+ *  closed, and the one class that a sentence cannot close was never raised at all.
+ *  Prose closed every uncovered change, including changes nothing prevented a test
+ *  from reaching. Runs 34423214322 and 34423217796 then lost three defects the
+ *  baseline reported: each was listed and closed by a sentence. */
+export declare const BLOCKER_ONLY_PREFIXES: readonly ["coverage:change:", "defects:untested:"];
 export declare function needsBlocker(objectionId: unknown): boolean;
 /** The objection raised below carries this prefix and the id it objects to. */
 export declare const REFUSED_ANSWER_PREFIX = "answers:refused:";

package/build/recommendation/answers.js

@@ -49,15 +49,19 @@ export const NON_ANSWERABLE_PREFIX = "coverage:stateTest:";
 export function isNonAnswerable(objectionId) {
     return typeof objectionId === "string" && objectionId.startsWith(NON_ANSWERABLE_PREFIX);
 }
-/** The objection a sentence alone does not close either. A change with no test
- *  needs the test, unless this run could not write one — so the answer closes it
- *  only when it also names what stopped the run. Measured on run 34176038240:
- *  across eight fixtures 45 objections were raised and 45 were closed, and the one
- *  class that a sentence cannot close was never raised at all. Prose closed every
- *  uncovered change, including changes nothing prevented a test from reaching. */
-export const BLOCKER_ONLY_PREFIX = "coverage:change:";
+/** The objections a sentence alone does not close either. A change with no test
+ *  needs the test, and a defect with no test needs the test — a defect the code
+ *  already had before this pull request included. Either one closes only when the
+ *  answer also names what stopped the test: a service that is not running, a
+ *  branch that no longer exists, the one credential the run holds. Measured on run
+ *  34176038240: across eight fixtures 45 objections were raised and 45 were
+ *  closed, and the one class that a sentence cannot close was never raised at all.
+ *  Prose closed every uncovered change, including changes nothing prevented a test
+ *  from reaching. Runs 34423214322 and 34423217796 then lost three defects the
+ *  baseline reported: each was listed and closed by a sentence. */
+export const BLOCKER_ONLY_PREFIXES = ["coverage:change:", "defects:untested:"];
 export function needsBlocker(objectionId) {
-    return typeof objectionId === "string" && objectionId.startsWith(BLOCKER_ONLY_PREFIX);
+    return typeof objectionId === "string" && BLOCKER_ONLY_PREFIXES.some((prefix) => objectionId.startsWith(prefix));
 }
 /** The objection raised below carries this prefix and the id it objects to. */
 export const REFUSED_ANSWER_PREFIX = "answers:refused:";
@@ -84,11 +88,11 @@ export function refusedAnswerObjections(objections, acknowledged) {
             objectionId: `${REFUSED_ANSWER_PREFIX}${id}`,
             verifier: "answers",
             message: needsBlocker(id)
-                ? "The answer says why this change has no test, and it does not say what stopped this run from writing one, so the objection stays open."
+                ? "The answer says why there is no test, and it does not say what stopped this run from writing one, so the objection stays open."
                 : "This objection is closed only by a planned test, so the answer closed nothing and the objection stays open.",
             evidence: `answered "${id}"${needsBlocker(id) ? " with no `blocker`" : ", which no answer closes"}`,
             suggestion: needsBlocker(id)
-                ? "Plan a test for this change and register the plan again. If this run cannot write one, send the same answer with `blocker` naming what stopped it — a service that is not running, a paired branch that no longer exists, the one credential the run holds. A reason the change is not worth testing is not a blocker."
+                ? "Plan the test and register the plan again. If this run cannot write one, send the same answer with `blocker` naming what stopped it — a service that is not running, a paired branch that no longer exists, the one credential the run holds. A reason it is not worth testing is not a blocker."
                 : "Add a planned test that names the record's state as `startState` and runs this route's mutation on it, then register the plan again. Every other objection takes an answer; this one takes a test.",
         });
     }

package/build/recommendation/pullRequestText.d.ts

@@ -0,0 +1,18 @@
+/** Called by every entry point that renders the testbot prompt, with the values it
+ *  renders. */
+export declare function recordPullRequestText(title: unknown, description: unknown): void;
+/** UNDEFINED when this process never rendered the prompt — a caller that drives the
+ *  tools directly, or a test. A check that reads the pull request stays silent then;
+ *  it cannot tell an empty pull request from one it never saw. */
+export declare function pullRequestText(): {
+    title: string;
+    description: string;
+} | undefined;
+export declare function clearPullRequestText(): void;
+/** The pull request as one searchable string. Whitespace runs fold to one space, so
+ *  a quote wrapped across lines still matches the sentence it was taken from. */
+export declare const searchable: (pr: {
+    title: string;
+    description: string;
+}) => string;
+export declare const appearsIn: (haystack: string, needle: string) => boolean;

package/build/recommendation/pullRequestText.js

@@ -0,0 +1,31 @@
+/** The pull request's own title and description, as the run rendered its prompt with.
+ *
+ *  IN PROCESS, never the state file: the prompt and the plan tool are registered on
+ *  the same server, so the text is already here, and writing it would put the pull
+ *  request's prose on disk once per registration for a reader in the same process.
+ *
+ *  ONE SLOT, last write wins. A run renders the prompt once, and a second render is
+ *  a second run whose text replaces the first. */
+let recorded;
+const asText = (value) => (typeof value === "string" ? value : "");
+/** Called by every entry point that renders the testbot prompt, with the values it
+ *  renders. */
+export function recordPullRequestText(title, description) {
+    recorded = { title: asText(title), description: asText(description) };
+}
+/** UNDEFINED when this process never rendered the prompt — a caller that drives the
+ *  tools directly, or a test. A check that reads the pull request stays silent then;
+ *  it cannot tell an empty pull request from one it never saw. */
+export function pullRequestText() {
+    return recorded;
+}
+export function clearPullRequestText() {
+    recorded = undefined;
+}
+/** The pull request as one searchable string. Whitespace runs fold to one space, so
+ *  a quote wrapped across lines still matches the sentence it was taken from. */
+export const searchable = (pr) => `${pr.title}\n${pr.description}`.replace(/\s+/g, " ").trim().toLowerCase();
+export const appearsIn = (haystack, needle) => {
+    const folded = needle.replace(/\s+/g, " ").trim().toLowerCase();
+    return folded.length > 0 && haystack.includes(folded);
+};

package/build/recommendation/registerPlan.d.ts

@@ -1,10 +1,14 @@
-import { Objection, ObjectionAnswer, PlanChange, PlanInput, PlannedTest, VerifyContext } from "./types.js";
+import { Objection, ObjectionAnswer, PlanChange, PlanDefect, PlanInput, PlannedTest, VerifyContext } from "./types.js";
 /** The plan as stored for the run. Every registration produces one; the newest
  *  replaces the last. */
 export interface Plan {
     /** The changes the agent said the diff makes. Published in the report
      *  beside the tests delivered against each one. */
     changes: PlanChange[];
+    /** The defects the code review found. skyramp_submit_report reads them to hold
+     *  the report to the review: every one is an issue, and every issue names the
+     *  test that proves it. */
+    defects: PlanDefect[];
     plannedTests: PlannedTest[];
     /** Objections the agent answered, with the answers. */
     answeredObjections: Array<{

package/build/recommendation/registerPlan.js

@@ -53,12 +53,13 @@ export function registerPlan(registration, ctx, previous) {
     const acknowledged = Array.isArray(registration.answers) ? registration.answers : [];
     const plannedTests = Array.isArray(registration.plannedTests) ? registration.plannedTests : [];
     const changes = Array.isArray(registration.changes) ? registration.changes : [];
+    const defects = Array.isArray(registration.defects) ? registration.defects : [];
     const registrationNumber = storedRegistrationNumber(registration);
     // The verifiers see the same normalised fields the STORED plan gets, not the raw
     // registration: handing them the raw one let a malformed top-level field crash
     // every check at once, giving eight `:crashed` objections and no real ones.
     // Crash containment is for a malformed field INSIDE a planned test.
-    const verified = runPlanTimeVerifiers({ ...registration, plannedTests, changes, answers: acknowledged }, ctx);
+    const verified = runPlanTimeVerifiers({ ...registration, plannedTests, changes, defects, answers: acknowledged }, ctx);
     const objections = [
         ...verified,
         ...unknownAnswerObjections(verified, acknowledged, {
@@ -107,6 +108,7 @@ export function registerPlan(registration, ctx, previous) {
             : {}),
         plan: {
             changes,
+            defects,
             plannedTests,
             answeredObjections,
             unverifiedCloses,

package/build/recommendation/runVerifiers.js

@@ -6,7 +6,10 @@ import { expectedOutcomeAtPlanTime } from "./verifiers/expectedOutcome.js";
 import { uiElementGrounded } from "./verifiers/uiElementGrounded.js";
 import { screenRoute } from "./verifiers/screenRoute.js";
 import { coverage } from "./verifiers/coverage.js";
+import { expectedValueSourced } from "./verifiers/expectedValueSourced.js";
 import { removedElementGuarded } from "./verifiers/removedElementGuarded.js";
+import { requirementSourced } from "./verifiers/requirementSourced.js";
+import { defects } from "./verifiers/defects.js";
 /** Verifiers that need only the plan and the run's facts. The order is the order
  *  objections are reported in; it carries no priority. */
 export const PLAN_TIME_VERIFIERS = [
@@ -18,7 +21,10 @@ export const PLAN_TIME_VERIFIERS = [
     uiElementGrounded,
     screenRoute,
     coverage,
+    expectedValueSourced,
     removedElementGuarded,
+    requirementSourced,
+    defects,
 ];
 /** How a crashed verifier reads back. The id is the verifier's name plus a fixed
  *  word, so it stays stable across registrations and can be answered. */

package/build/recommendation/types.d.ts

@@ -23,6 +23,9 @@ export interface PlanChange {
     id: string;
     text: string;
     source: string;
+    /** The requirement in the pull request's own words, when `source` names the pull
+     *  request. Checked against the text the run rendered its prompt with. */
+    quote?: string;
     /** Where a user or caller meets this change. Every change states it: an optional
      *  field the agent skips gives the check nothing to read. */
     surfaces: Array<"api" | "page">;
@@ -34,8 +37,26 @@ export interface PlanChange {
         value?: string | number | boolean | null;
         absent?: true;
         expect: "accept" | "reject";
+        /** What the response must carry when this case is sent. Declared here so the
+         *  test asserts a value the plan decided, not the value the running app
+         *  happened to return — the one source that always agrees with a defect. */
+        expectedValue?: string | number | boolean | null;
+        /** Where the agent read `expectedValue`: `pr-description`, `spec:<path>`,
+         *  `convention:<file:line>`, or `code`. */
+        expectedFrom?: string;
     }>;
 }
+/** One defect the code review found, as the agent read it. Nothing on the server
+ *  parses the description or opens the file: the check reads the id, and a test
+ *  that cites it and expects to fail is what proves it. */
+export interface PlanDefect {
+    id: string;
+    file: string;
+    /** Advisory. Line numbers drift, so nothing checks it. */
+    line?: number;
+    description: string;
+    severity: "critical" | "high" | "medium" | "low";
+}
 /** What a planned test states so a verifier has a checkable change. Kept in step with
  *  `declarationFieldsSchema`, which the plan tool asserts against this type. */
 export interface PlannedTestDetails {
@@ -74,6 +95,9 @@ export interface PlannedTestDetails {
     };
     /** The ids of the declared changes this test proves. */
     changes?: string[];
+    /** The ids of the declared defects this test proves. A test proves a defect
+     *  only when it expects to fail; the defects check reads both. */
+    defects?: string[];
     /** The state the mutated record is in before the mutation. Presence only. */
     startState?: string;
     /** UI planned tests only. `items` entries are COPIES of elements a capture of
@@ -103,6 +127,10 @@ export interface ObjectionAnswer {
 export interface PlanInput {
     /** The changes the diff makes. Each planned test cites the ones it tests. */
     changes: PlanChange[];
+    /** The defects the code review found. Each planned test cites the ones it
+     *  proves. Empty is a statement — the review found none — and draws an
+     *  objection the agent answers. */
+    defects: PlanDefect[];
     plannedTests: PlannedTest[];
     answers: ObjectionAnswer[];
     /** The tool owns this and overwrites whatever the caller sends. */
@@ -141,6 +169,13 @@ export interface VerifyContext {
     /** Identifiers a rename replaced, empty when the diff renames nothing. Only the
      *  server pairs the two sides of a diff. */
     retiredUiElements: RemovedUiElement[];
+    /** The pull request's title and description, as the run rendered its prompt with.
+     *  The plan tool fills it from the process the prompt was rendered in. Both fields
+     *  blank MEANS the run had no title and no description. */
+    pullRequest: {
+        title: string;
+        description: string;
+    };
     /** Whether a cited path names a file in any of the run's repositories. Injected
      *  to keep the verifiers filesystem-free. */
     citedFileExists(relativePath: string): boolean;

package/build/recommendation/verifierContracts.d.ts

@@ -17,8 +17,6 @@ export interface ContractObjection {
 export interface VerifierContract {
     /** The verifier's own `Verifier.name`. */
     readonly id: string;
-    /** What the registered plan has to carry for the check to have anything to read. */
-    readonly declarationFields: readonly string[];
     /** One entry per message the verifier can emit, keyed by the case. A key naming a
      *  segment of the `objectionId` uses that segment's spelling. The keys are widened
      *  here so every contract satisfies the interface, while each contract is `as
@@ -31,7 +29,6 @@ export interface VerifierContract {
 }
 export declare const CHANGED_FILE_CONTRACT: {
     readonly id: "changedFile";
-    readonly declarationFields: readonly ["declarations.changedFile", "declarations.screenEvidence.file"];
     readonly objections: {
         readonly notStated: {
             readonly message: "This test does not state which changed file it targets.";
@@ -54,7 +51,6 @@ export declare const CHANGED_FILE_CONTRACT: {
 };
 export declare const SCREEN_ROUTE_CONTRACT: {
     readonly id: "screenRoute";
-    readonly declarationFields: readonly ["declarations.elements.pageUrl", "declarations.screenEvidence.file", "declarations.changedFile"];
     readonly objections: {
         readonly mismatch: {
             readonly message: "The page this UI test opens is not a page that renders the changed file it is about.";
@@ -69,7 +65,6 @@ export declare const SCREEN_ROUTE_CONTRACT: {
 };
 export declare const ENDPOINT_GROUNDED_CONTRACT: {
     readonly id: "endpointGrounded";
-    readonly declarationFields: readonly ["steps[]", "testType", "declarations.routes"];
     readonly objections: {
         readonly uncited: {
             readonly message: "A call this test makes cites no file that declares it.";
@@ -88,7 +83,6 @@ export declare const ENDPOINT_GROUNDED_CONTRACT: {
 };
 export declare const STATED_DIFFERENCE_CONTRACT: {
     readonly id: "statedDifference";
-    readonly declarationFields: readonly ["steps[]", "testType", "scenarioName", "declarations.differsFrom"];
     readonly objections: {
         readonly unexplainedPair: {
             readonly message: "Another planned test in this plan tests the same endpoint and neither says how they differ.";
@@ -107,7 +101,6 @@ export declare const STATED_DIFFERENCE_CONTRACT: {
 };
 export declare const EXISTING_COVERAGE_CONTRACT: {
     readonly id: "existingCoverage";
-    readonly declarationFields: readonly ["declarations.existingTests"];
     readonly objections: {
         readonly citedTestMissing: {
             readonly message: "This planned test names an existing test file that is not in the checkout.";
@@ -118,7 +111,6 @@ export declare const EXISTING_COVERAGE_CONTRACT: {
 };
 export declare const EXPECTED_OUTCOME_CONTRACT: {
     readonly id: "expectedOutcome";
-    readonly declarationFields: readonly ["category", "declarations.expected.outcome", "declarations.expected.why"];
     readonly objections: {
         readonly passInShouldFailCategory: {
             readonly message: "This planned test is categorised \"{category}\" but expects to pass on the app as it stands.";
@@ -133,7 +125,6 @@ export declare const EXPECTED_OUTCOME_CONTRACT: {
 };
 export declare const UI_ELEMENT_GROUNDED_CONTRACT: {
     readonly id: "uiElementGrounded";
-    readonly declarationFields: readonly ["testType", "steps[]", "declarations.elements.items", "declarations.elements.pageUrl", "declarations.asserts", "scenarioName", "description", "declarations.expected.why"];
     readonly objections: {
         readonly nogrounding: {
             readonly message: "This UI test names no `elements.items`, so nothing says the elements it targets are on the page.";
@@ -156,7 +147,6 @@ export declare const UI_ELEMENT_GROUNDED_CONTRACT: {
 };
 export declare const COVERAGE_CONTRACT: {
     readonly id: "coverage";
-    readonly declarationFields: readonly ["changes", "declarations.changes", "declarations.changedFile", "declarations.routes", "declarations.screenEvidence.file", "declarations.startState", "changes[].cases", "changes[].surfaces"];
     readonly objections: {
         readonly change: {
             readonly message: "This declared change has no test in the plan.";
@@ -195,7 +185,6 @@ export declare const COVERAGE_CONTRACT: {
 };
 export declare const REMOVED_ELEMENT_GUARDED_CONTRACT: {
     readonly id: "removedElementGuarded";
-    readonly declarationFields: readonly ["declarations.elements.items", "declarations.asserts"];
     readonly objections: {
         readonly missing: {
             readonly message: "The diff removes `{element}` and no planned test says it is gone.";
@@ -208,6 +197,100 @@ export declare const REMOVED_ELEMENT_GUARDED_CONTRACT: {
     };
     readonly suggestion: "Does every element this diff removes have a planned test that asserts it is gone, and does no test claim a renamed identifier is gone?";
 };
+export declare const EXPECTED_VALUE_SOURCED_CONTRACT: {
+    readonly id: "expectedValueSourced";
+    readonly objections: {
+        readonly sourcedFromCode: {
+            readonly message: "This case expects a value it read from the code as it stands, so a defect in that code becomes what the test demands.";
+            readonly suggestion: "Read the value from the pull request title or description, from a requirements file the description names, or from a convention the application already follows elsewhere, and name that source. If none of them states it, leave `expectedValue` out and assert the shape instead.";
+        };
+        readonly missingSource: {
+            readonly message: "This case states an expected value and does not say where the value came from.";
+            readonly suggestion: "Set `expectedFrom` to `pr-title`, `pr-description`, `spec:<path>`, `convention:<file:line>` or `code`.";
+        };
+        readonly unreadableSource: {
+            readonly message: "This case names a file as the source of its expected value, and that file is not in the checkout.";
+            readonly suggestion: "Give the path as the repository spells it, from the repository root. If the file is not there, the value has no source: read it from the pull request title or description instead, or leave `expectedValue` out and assert the shape.";
+        };
+        readonly changedConvention: {
+            readonly message: "This case reads its expected value from a line this pull request writes, so the same change decides both the behaviour and what counts as correct.";
+            readonly suggestion: "Cite a file the pull request leaves alone, or read the value from the description or a requirements file. If the cited file is changed but has nothing to do with this case, say so as the answer.";
+        };
+        readonly quoteMissing: {
+            readonly message: "This case reads its value from the pull request, and its change does not quote the sentence that states the rule.";
+            readonly suggestion: "Put the sentence from the title or description on the change as `quote`, as written there. Derive this case's value from that rule; the value itself need not appear in the pull request.";
+        };
+        readonly failWithoutValue: {
+            readonly message: "This test expects to fail, and no case on the changes it cites states the value it must assert.";
+            readonly suggestion: "Put the value the code does not return today on the case this test sends, as `expectedValue`, and name where you read it. If no source states the value, answer with what the test asserts instead and where that comes from.";
+        };
+    };
+    readonly suggestion: "Where does the correct value for this case come from?";
+};
+export declare const REQUIREMENT_SOURCED_CONTRACT: {
+    readonly id: "requirementSourced";
+    readonly objections: {
+        readonly unsourced: {
+            readonly message: "Change `{change}` does not name a source the plan accepts: `pr-title`, `pr-description`, `spec:<path>` or `diff`.";
+            readonly suggestion: "Set `source` on this change to `pr-title` or `pr-description`, to `spec:<path>` for the requirements file that states it, or to `diff`.";
+        };
+        readonly unreadable: {
+            readonly message: "Change `{change}` cites `{source}`, and the checkout holds no file at that path.";
+            readonly suggestion: "Cite the requirements file by the path the checkout holds, or name the source you actually read this change in.";
+        };
+        readonly fromDiff: {
+            readonly message: "This test reports a requirement conflict, and none of the changes it cites was read from the pull request or a requirements file.";
+            readonly suggestion: "Cite a change you read in the pull request or in a requirements file, or report this test as something other than a requirement conflict.";
+        };
+        readonly notNamed: {
+            readonly message: "Change `{change}` cites `{source}`, and the pull request names no such file.";
+            readonly suggestion: "Cite a file the title or description names. If neither names it, you read the change in the repository, so set `source` to `diff`.";
+        };
+        readonly emptyPullRequest: {
+            readonly message: "Change `{change}` says it was read from the pull request, and the pull request has no title or description.";
+            readonly suggestion: "Set `source` to `spec:<path>` for the requirements file that states this change, or to `diff` if only the code states it.";
+        };
+        readonly notQuoted: {
+            readonly message: "This test reports a requirement conflict, and change `{change}` quotes words the pull request does not carry.";
+            readonly suggestion: "Quote the requirement as the title or description spells it, word for word. If you cannot find those words there, the change came from somewhere else: say where in `source`.";
+        };
+        readonly unquoted: {
+            readonly message: "This test reports a requirement conflict, and change `{change}` does not quote the requirement.";
+            readonly suggestion: "Set `quote` on that change to the sentence in the title or description that states the requirement.";
+        };
+        readonly noChange: {
+            readonly message: "This test reports a requirement conflict and cites no change, so nothing says where the requirement came from.";
+            readonly suggestion: "Name in `changes` the change that states the requirement, or report this test as something other than a requirement conflict.";
+        };
+    };
+    readonly suggestion: "Does every change name where you read it, and does every requirement-conflict test cite a change that came from the pull request or a requirements file?";
+};
+export declare const DEFECTS_CONTRACT: {
+    readonly id: "defects";
+    readonly objections: {
+        readonly none: {
+            readonly message: "The plan declares no defects, so nothing says the code review happened before the plan.";
+            readonly suggestion: "Review the code that serves each change — the handler, the functions it calls to read or write data, the component and what it calls — and list each defect in `defects`. If the review found none, answer in one line what you read.";
+        };
+        readonly untested: {
+            readonly message: "This declared defect has no test in the plan.";
+            readonly suggestion: "Add a planned test that cites the defect in `defects` and sets `expected.outcome` to `fail`. A defect in a file this pull request touches gets the test whether or not this pull request introduced it. If something stopped this run from writing the test, answer it and set `blocker` to what stopped it.";
+        };
+        readonly expectedPass: {
+            readonly message: "Every test that cites this defect expects to pass, and a test that passes today proves nothing about a defect.";
+            readonly suggestion: "Assert what the fixed code returns, set `expected.outcome` to `fail` with `why`, or answer in one line why a passing test is the proof.";
+        };
+        readonly unknownId: {
+            readonly message: "A planned test cites a defect id that this plan does not declare.";
+            readonly suggestion: "Spell the defect's `id` exactly as your own `defects` list gives it — the match is exact apart from surrounding space. Declare the defect if it is missing.";
+        };
+        readonly conflictWithoutDefect: {
+            readonly message: "This test reports a requirement conflict and cites no defect.";
+            readonly suggestion: "List the conflict in `defects`: the file and line that contradict the requirement, and a description that quotes the requirement. Cite that id from this test.";
+        };
+    };
+    readonly suggestion: "Which planned test proves each defect the review found, and for one nothing proves, why does it need no test?";
+};
 /** Fills a contract sentence's `{placeholder}` spans from the run's or the
  *  planned test's own values. A placeholder with no value is left as written rather
  *  than blanked, so a missed key shows up as `{knob}` instead of reading as a gap