@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/tools/submitReportTool.js

@@ -3,26 +3,27 @@ import { logger } from "../utils/logger.js";
 import * as fs from "fs/promises";
 import * as path from "path";
 import { AnalyticsService } from "../services/AnalyticsService.js";
-import { TEST_CATEGORIES, externalCategory, } from "../types/TestRecommendation.js";
-import { TestType, HttpMethod } from "../types/TestTypes.js";
+import { SCENARIO_CATEGORIES, categoryExpectsRed, } from "../types/TestRecommendation.js";
+import { TestType } from "../types/TestTypes.js";
+import { STEP_METHOD_DESCRIPTION, stepMethodSchema } from "../types/StepMethod.js";
 import { DriftAction } from "../types/TestAnalysis.js";
 import { TestExecutionStatus } from "../types/TestExecution.js";
 import { IssueFoundCategory } from "../types/TestbotReport.js";
-import { StateManager, runArtifactDir, getTestsRepoDir, } from "../utils/AnalysisStateManager.js";
+import { StateManager, runArtifactDir, getTestsRepoDir, resolveRunStatePath, } from "../utils/AnalysisStateManager.js";
 import { toolError, testFileMatches } from "../utils/utils.js";
-import { matchesApprovedPlan } from "../utils/planMatchKeys.js";
-import { isTestbotEnabled } from "../utils/featureFlags.js";
+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 { checkExpectedOutcomeAfterExecution, } from "../recommendation/verifiers/expectedOutcome.js";
 import { findInvalidSourceCitations, findUnchangedFileClaims, listChangedFiles, listChangedFilesAcross, listChangedFilesAbs, } from "../utils/reportVerification.js";
 import { isPlanOnlyMode } from "../utils/planOnlyMode.js";
 import { getReportLanguage, isEnforcedReportLanguage, findLanguageViolations, findLanguageNearMisses, reportLanguageDisplayName, } from "../utils/reportLanguage.js";
 import { canonicalTestPath, findAssertionRecordByFileName, rederiveAssertionOutcome, } from "./code-refactor/assertion-state.js";
 import { rederiveReuseOutcome, reuseChainSkipped, samePath, } from "./code-refactor/reuse-state.js";
 import { retrofitGate, } from "./code-refactor/retrofit-state.js";
-// SKYR-3879 Path B: which testTypes the register-plan checkpoint gates. Mirrors
-// the generation tools actually wired to planGuard (batch-scenario/integration,
-// contract) — UI and E2E are on a separate blueprint-grounded pipeline and are
-// NOT gated at generation time (see planGuard.ts wiring), so they are excluded
-// here too rather than surprising the agent with a report-time-only gate.
+// Mirrors the tools wired to planGuard: UI and E2E are not gated at generation
+// time, so gating them here would be a report-time-only surprise.
 const PLAN_GATED_TEST_TYPES = new Set([
     TestType.CONTRACT,
     TestType.INTEGRATION,
@@ -41,44 +42,6 @@ const PLAN_GATED_TEST_TYPES = new Set([
  * `RUN_STATE_FILE_NAME` / testbot's `STATE_FILE_NAME`.
  */
 export const REPORT_FILE_NAME = "testbot-result.txt";
-/**
- * The names to match a report entry against the approved plan's `name:` keys.
- * `testId` is documented as `<testType>-<scenario-slug>`, so the plan's bare
- * scenarioName only matches once that prefix is dropped — but agents also submit
- * the bare name (both forms appear in SKYR-4123's runs), so try each.
- */
-function planNameCandidates(testId, testType) {
-    const id = (testId ?? "").trim();
-    if (!id)
-        return [];
-    const prefix = `${testType}-`;
-    return id.toLowerCase().startsWith(prefix)
-        ? [id, id.slice(prefix.length)]
-        : [id];
-}
-/**
- * Split an `endpoint` field into one {method, path} per endpoint it names.
- * A multi-step test writes them comma-separated ("POST /orders, DELETE
- * /orders/{id}"); read as a single endpoint the whole string becomes one
- * unmatchable path, so such an entry could match nothing (SKYR-4123).
- */
-function parseEndpointField(endpoint) {
-    const parts = (endpoint ?? "")
-        .split(",")
-        .map((p) => p.trim())
-        .filter(Boolean);
-    if (parts.length === 0)
-        return [{}];
-    return parts.map((part) => {
-        const spaceIdx = part.indexOf(" ");
-        if (spaceIdx <= 0)
-            return { path: part };
-        return {
-            method: part.slice(0, spaceIdx),
-            path: part.slice(spaceIdx + 1).trim(),
-        };
-    });
-}
 // Drift actions that actually modify a test file. VERIFY and IGNORE are
 // no-ops (the test was assessed but left unchanged), so they must not count
 // toward "tests maintained" telemetry.
@@ -87,17 +50,20 @@ const MAINTENANCE_CHANGE_ACTIONS = new Set([
     DriftAction.Regenerate,
     DriftAction.Delete,
 ]);
+/** Objection ids for an untested declared change, `coverage:change:<id>`. The
+ *  change table reads the agent's answer back off them. */
+const CHANGE_OBJECTION_PREFIX = "coverage:change:";
 const TOOL_NAME = "skyramp_submit_report";
 const DEFAULT_COMMIT_MESSAGE = "Added recommendations by Skyramp Testbot.";
 // Per-repo attribution. In a multi-repo run, every report item carries the
-// owner/repo it pertains to (the primary's owner/repo for primary findings, or a
-// related repo's owner/repo for findings from that repo's diff). Whitespace-only
+// owner/repo it pertains to (the primary's owner/repo for primary objections, or a
+// related repo's owner/repo for objections from that repo's diff). Whitespace-only
 // values are normalized to undefined so a blank string is never treated as a
 // distinct repo. Single-repo runs may omit it.
 const repositoryField = z
     .string()
     .optional()
-    .describe("The 'owner/repo' this item pertains to (e.g. 'letsramp/api-insight'). In a multi-repo run, ALWAYS set it — the primary's owner/repo for primary-repo findings, or a related repo's owner/repo for findings derived from that repository's diff. May be omitted only in single-repo runs.");
+    .describe("The 'owner/repo' this item pertains to (e.g. 'letsramp/api-insight'). In a multi-repo run, ALWAYS set it — the primary's owner/repo for primary-repo objections, or a related repo's owner/repo for objections derived from that repository's diff. May be omitted only in single-repo runs.");
 /** Normalize a `repository` attribution: trim, and map a blank/whitespace-only
  *  value to undefined so it is never serialized as a distinct empty repo
  *  (downstream consumers treat absence as "the primary repo"). */
@@ -116,7 +82,7 @@ const testResultSchema = z.object({
         .describe("Type of test. Do not include priority or other metadata in this field."),
     endpoint: z
         .string()
-        .describe("HTTP verb and path, e.g. 'GET /api/v1/products'"),
+        .describe("For contract and integration tests, the HTTP verb and path, e.g. 'GET /api/v1/products'. For ui and e2e tests, the page path the test opens, e.g. '/notifications'."),
     status: z.enum(["Pass", "Fail", "Skipped"]).describe("Test execution result"),
     details: z
         .string()
@@ -131,15 +97,23 @@ const testResultSchema = z.object({
         message: "testFilePath must be an absolute path",
     })
         .describe("Absolute path of the test file this result is for — the same path you passed to skyramp_execute_test's testFile param. Consumers basename it for display."),
+    reachedBehavior: z
+        .boolean()
+        .optional()
+        .describe("For a failing test only. `true` when the request that carries the behaviour under test was sent and answered by the code under test, and the assertion that failed is about that behaviour. " +
+        "`false` when the failure came earlier: a 404, 401, 403 or 5xx on a route the change adds; an expired token or a sign-in page; a control or setup step that failed; a generator or SDK error. " +
+        "If your own `details` text says the request was not sent or an earlier step tripped, this is `false`. Omit only if you cannot tell."),
     repository: repositoryField,
 });
 // Structured grounding for UI recommendations. Lifted verbatim from a
 // `browser_blueprint` element captured during this run. Source of truth for
 // codegen (prefers testId > stableId > role+name for locator selection),
-// the verifier (cross-checks each field against captured blueprints), and
+// the verifier (matches on `testId`, `stableId`, accessible name, or role plus
+// a repeating row's `contextText` — it reads no other field here), and
 // any future tooling that wants reliable grounding data without prose
 // parsing. `reasoning` is free-form prose constrained by the Blueprint
-// Citation Invariant — every element cited must appear in `targetElements`.
+// Citation Invariant — every element cited SHOULD appear in `targetElements`.
+// Prose only: nothing checks it, and it is on the list of unchecked rules.
 // See testbot prompt step 4 for the full populate-and-render rules.
 /**
  * Accept an omitted key as an explicit `null`.
@@ -158,7 +132,7 @@ export const targetElementSchema = z.object({
         .describe("ARIA role (e.g. 'button', 'heading', 'textbox', 'link'). Lifted verbatim from the captured blueprint element's `role` field."),
     accessibleName: z
         .string()
-        .describe("Computed accessible name (e.g. 'Save changes', 'Order Details'). Lifted verbatim from the captured blueprint element's `accessibleName` field. Must match the bolded name in `reasoning` character-for-character."),
+        .describe("Computed accessible name (e.g. 'Save changes', 'Order Details'). Lifted verbatim from the captured blueprint element's `accessibleName` field. In a REPORT entry, match the bolded name in `reasoning` character-for-character. A plan planned test has no `reasoning` field, so that half does not apply there."),
     testId: nullWhenAbsent(z.string()).describe("data-testid attribute value (preferred locator handle), or null when the element has no data-testid. Lifted from the blueprint element's `testId`."),
     stableId: nullWhenAbsent(z.string()).describe("Unique HTML id attribute value (fallback locator when no testId), or null. Lifted from the blueprint element's `stableId`."),
     contextText: nullWhenAbsent(z.array(z.string())).describe("Disambiguating row text for elements inside repeating sections (table rows, list items): the row's surrounding non-interactive text. Lifted from the blueprint repeatingElement's items[].contextText. null for non-repeating elements."),
@@ -181,21 +155,13 @@ export const pageContextSchema = z.object({
     pageHash: z
         .string()
         .optional()
-        .describe("Opaque hash of the captured page state (BlueprintCapture.pageHash). Lets the verifier confirm the recommendation was grounded in a still-current capture."),
+        .describe("Opaque hash of the captured page state (BlueprintCapture.pageHash). Recorded for a reader; NOT checked — the element check pools every capture of the page rather than narrowing by hash, so a stale one costs nothing. The tool that verifies elements says the same."),
 });
 /**
- * SKYR-4193: LLMs habitually emit every key a schema declares, using a
- * literal null for "not applicable". A null is stripped (normalized to
- * omitted) before validation wherever null carries no meaning, instead of
- * costing the agent a rejection/rewrite round-trip (run 32182635458 lost
- * ~2m40s to exactly this):
- * - `pageContext: null` is always stripped — the field is optional but never
- *   nullable, so null is never a valid value, UI or not.
- * - `targetElements: null` is stripped only on non-UI entries — on UI tests
- *   null is load-bearing ("blueprint capture failed", requires the
- *   '[no-blueprint-data]' markers) and must reach the refinements intact.
- * Non-null values on non-UI entries still reach the refinements and are
- * still rejected.
+ * A null that carries no meaning is stripped to omitted before validation.
+ * `pageContext: null` always: the field is optional, never nullable.
+ * `targetElements: null` on non-UI entries only — on a UI entry the null MEANS
+ * capture failed, so it must reach the refinements intact.
  */
 function stripNullGroundingFields(val) {
     if (!val || typeof val !== "object" || Array.isArray(val))
@@ -220,21 +186,27 @@ export const newTestSchema = z.preprocess(stripNullGroundingFields, z
     testId: z
         .string()
         .describe("Human-readable kebab-case identifier, e.g. 'contract-get-products' or 'integration-users-orders-workflow'. Format: '<testType>-<method>-<resource>' for single-endpoint tests or '<testType>-<scenario-slug>' for multi-step tests. Must be unique within the report."),
+    plannedTestId: z
+        .string()
+        .optional()
+        .describe("The `plannedTestId` of the plan entry this test was approved under. Copy it from the plan you submitted to skyramp_register_test_plan — never invent one. " +
+        "Required on EVERY entry, UI included. That is deliberately wider than the approved-plan generation gate, which stays contract and integration only: " +
+        "this id is the exact key the report is joined back to the plan on, and an entry without one falls back to guessing from the test name and endpoint."),
     testType: z
         .nativeEnum(TestType)
         .describe("Type of test created. Do not include priority or other metadata in this field."),
     category: z
-        .preprocess((val) => externalCategory(val), z.enum(TEST_CATEGORIES))
-        .describe("Test category — critical categories (security_boundary, business_rule, data_integrity, breaking_change) get generation priority over workflow"),
+        .enum(SCENARIO_CATEGORIES)
+        .describe("Test category. Write the same category the plan declared."),
     endpoint: z
         .string()
-        .describe("HTTP verb and path, e.g. 'GET /api/v1/products'"),
+        .describe("For contract and integration tests, the HTTP verb and path, e.g. 'GET /api/v1/products'. For ui and e2e tests, the page path the test opens, e.g. '/notifications'."),
     fileName: z.string().describe("Name of the generated test file"),
     description: z
         .string()
         .trim()
         .min(1)
-        .describe("What the test does — the steps and assertions, not the bugs it finds. e.g. 'Creates a collection, adds a link, then verifies the link exists'. Do NOT describe expected failures or bugs here — those belong in issuesFound."),
+        .describe("What the test does — the steps and assertions, not the bugs it finds. e.g. 'Creates a collection, adds a link, then verifies the link exists'. Do NOT describe expected failures or bugs here — those belong in issuesFound. Name any UI element the way a person would, e.g. the disabled 'Mark all as read' button — never a builder term such as blueprint or DOM analyzer, and never identifier syntax such as role=button or accessibleName=X."),
     scenarioFile: z
         .string()
         .optional()
@@ -249,19 +221,30 @@ export const newTestSchema = z.preprocess(stripNullGroundingFields, z
         .describe("Path to the Playwright/UI trace file if used or created"),
     reasoning: z
         .string()
-        .describe("Why this test was created: what production risk it mitigates, what code pattern it targets, or what coverage gap it fills"),
+        .describe("Why this test was created: what production risk it mitigates, what code pattern it targets, or what coverage gap it fills. Name any UI element the way a person would, e.g. the disabled 'Mark all as read' button — never a builder term such as blueprint or DOM analyzer, and never identifier syntax such as role=button or accessibleName=X."),
     repository: repositoryField,
     targetElements: z
         .array(targetElementSchema)
         .min(1)
         .nullable()
         .optional()
-        .describe("UI tests only: structured grounding for one or more elements the test targets. Most tests target a single element (array length 1); render-state and multi-step UI tests target several (array length 2+). Each entry must be lifted verbatim from a captured blueprint element. Set to null when blueprint capture failed (also requires '[no-blueprint-data]' marker in BOTH description and reasoning). See Blueprint Citation Invariant in testbot prompt."),
+        .describe("UI tests only: structured grounding for one or more elements the test targets. Most tests target a single element (array length 1); render-state and multi-step UI tests target several (array length 2+). Each entry must be lifted verbatim from a captured blueprint element. Set to null when blueprint capture failed — the null IS the signal, so put no marker in description or reasoning. See Blueprint Citation Invariant in testbot prompt."),
     pageContext: pageContextSchema
         .optional()
         .describe("UI tests only: page metadata for the test. Lifted from the BlueprintCapture used during grounding."),
 })
     .superRefine((rec, ctx) => {
+    // The join to the stored plan is this id and nothing else. Required for
+    // EVERY testType: the generation gate covers only contract and integration,
+    // and UI is where a delivery drifts furthest from the plan. Declared
+    // optional above and required here so the message says what to do.
+    if ((rec.plannedTestId ?? "").trim().length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["plannedTestId"],
+            message: "plannedTestId is required on every newTestsCreated entry. Use the plannedTestId of the plan entry this test was approved under, from skyramp_register_test_plan.",
+        });
+    }
     // targetElements / pageContext are UI-only.
     if (rec.testType !== TestType.UI) {
         for (const field of ["targetElements", "pageContext"]) {
@@ -288,10 +271,12 @@ export const newTestSchema = z.preprocess(stripNullGroundingFields, z
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 path: ["targetElements"],
-                message: "targetElements is required for testType: 'ui'. Use null when blueprint capture failed (and add '[no-blueprint-data]' to both description and reasoning).",
+                message: "targetElements is required for testType: 'ui'. Use null when blueprint capture failed; the null is the signal and needs no marker in description or reasoning.",
             });
         }
-        // pageContext is required when targetElements is an array (grounded), forbidden when null.
+        // Required beside an array, and ALLOWED beside null: the plan schema asks a
+        // UI planned test with no HTTP step for `pageContext.url`, so refusing it here
+        // would make a plan-legal shape illegal in the report.
         if (Array.isArray(rec.targetElements) &&
             rec.pageContext === undefined) {
             ctx.addIssue({
@@ -300,31 +285,6 @@ export const newTestSchema = z.preprocess(stripNullGroundingFields, z
                 message: "pageContext is required for testType: 'ui' when targetElements is an array.",
             });
         }
-        if (rec.targetElements === null && rec.pageContext !== undefined) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: ["pageContext"],
-                message: "pageContext must be omitted when targetElements is null (no blueprint data).",
-            });
-        }
-        // When targetElements is null, both description and reasoning must carry the '[no-blueprint-data]' marker.
-        if (rec.targetElements === null) {
-            if (!rec.reasoning.includes("[no-blueprint-data]")) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    path: ["reasoning"],
-                    message: "reasoning must contain '[no-blueprint-data]' when targetElements is null.",
-                });
-            }
-            if (rec.description &&
-                !rec.description.includes("[no-blueprint-data]")) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    path: ["description"],
-                    message: "description must contain '[no-blueprint-data]' when targetElements is null.",
-                });
-            }
-        }
     }
 }));
 /** A citation string the submit-time check verifies and the report then ships.
@@ -338,6 +298,7 @@ const issueFoundSchema = z
     description: z
         .string()
         .describe("One-line description. Do NOT prefix with the severity level — severity is a separate field. Include code logic bugs from the diff, test generation/execution failures, and environment misconfiguration. " +
+        "A bug that this change did not cause is still an issue: keep the test that found it, and say in this description that the bug predates the change. " +
         "When sourceFile or sourceSymbol is set, quote the offending line inside backticks in this description — the exact code, copied from the file, so review tools can find it."),
     severity: z
         .enum(["critical", "high", "medium", "low"])
@@ -345,18 +306,26 @@ const issueFoundSchema = z
         .describe("Issue severity. critical = feature broken/unusable (e.g. page doesn't load, data corruption). " +
         "high = incorrect behavior (e.g. wrong calculation, stale data returned). " +
         "medium = minor functional gap. low = cosmetic or informational. " +
-        "Floor: a requirement conflict — the PR title/description (or a requirements file it references) states a requirement the implemented behavior contradicts — is 'high' or 'critical', never 'medium' or below."),
+        "CHECKED: a run that wrote a test planned as `requirement_conflict` — the PR title or description, " +
+        "or a requirements file it names, states a requirement the implemented behavior contradicts — must " +
+        "report an issue here at 'critical' or 'high'. A stated requirement the code does not meet is not a " +
+        "medium. The check raises an objection, never a rejection."),
     category: z
         .nativeEnum(IssueFoundCategory)
         .describe("Issue classification. bug = a product/code defect, e.g. found by a test or in the diff. " +
-        "lint = a linter or formatter finding (eslint, flake8, prettier). " +
+        "lint = a linter or formatter objection (eslint, flake8, prettier). " +
         "type = a type-check failure (tsc, mypy). " +
         "config = environment or tooling misconfiguration (wrong workspace auth type, missing env var, setup command failure), " +
         "and also every Skyramp tool or environment failure — a generation or execution tool error, an unreachable app, a missing credential, a failed capture. " +
         "The report renders lint/type/config entries in a separate 'Configuration Errors' section so product bugs stay prominent under 'Issues Found'."),
     repository: repositoryField,
+    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."),
     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. " +
         "Cite only a file you actually opened this run: this tool rejects the report if the path does not exist in the repository."),
     sourceSymbol: citationString.describe("The function, method, or identifier inside sourceFile whose code is missing or wrong (e.g. 'delete_product'). " +
         "Optional — a config file or template has no symbol to name. Set it whenever the file has one. " +
@@ -367,7 +336,7 @@ const issueFoundSchema = z
         .positive()
         .optional()
         .describe("1-based line number in sourceFile. Optional and advisory. " +
-        "Give the line of the offending statement itself, not the line of the enclosing function's signature — review views place the finding on exactly this line. " +
+        "Give the line of the offending statement itself, not the line of the enclosing function's signature — review views place the objection on exactly this line. " +
         "The tool does not check that the line still holds the cited code, because line numbers drift."),
 })
     .superRefine((issue, ctx) => {
@@ -375,7 +344,7 @@ const issueFoundSchema = z
     // without a file the entry is prose a reviewer cannot act on, and nothing
     // downstream can place it in the diff. Only the file is required — a config file
     // or a template legitimately has no symbol to name, and line numbers are
-    // advisory. The other categories are tooling findings that often have no single
+    // advisory. The other categories are tooling objections that often have no single
     // source location (an unreachable app, a missing env var), so the requirement is
     // scoped to `bug` alone.
     //
@@ -395,10 +364,9 @@ const issueFoundSchema = z
     });
 });
 const scenarioStepSchema = z.object({
-    method: z
-        .nativeEnum(HttpMethod)
+    method: stepMethodSchema
         .optional()
-        .describe("HTTP method. Required for API steps, omit for UI/E2E actions."),
+        .describe(`${STEP_METHOD_DESCRIPTION} Omit it when the step does none of the three.`),
     path: z
         .string()
         .optional()
@@ -428,8 +396,8 @@ export const additionalRecommendationSchema = z.preprocess(stripNullGroundingFie
         .nativeEnum(TestType)
         .describe("Type of test. Do not include priority or other metadata in this field."),
     category: z
-        .preprocess((val) => externalCategory(val), z.enum(TEST_CATEGORIES))
-        .describe("Test category — critical categories get generation priority over workflow"),
+        .enum(SCENARIO_CATEGORIES)
+        .describe("Test category, e.g. business_rule, error_handling, security_boundary. Write the same category the plan declared."),
     primaryEndpoint: z
         .string()
         .optional()
@@ -441,10 +409,12 @@ export const additionalRecommendationSchema = z.preprocess(stripNullGroundingFie
     // TODO: replace text with max(3) and check for regression
     steps: z
         .array(scenarioStepSchema)
+        .optional()
+        .default([])
         .describe("Ordered sequence of API/UI steps in this test scenario (at most 3). Each API step must include method and path so the endpoints are explicit; a UI/E2E action step omits them. Include requestBody and responseBody only where they carry something a reader needs — the concrete values a claim rests on, or a list endpoint's array response; omit them otherwise."),
     description: z
         .string()
-        .describe("Walkthrough of what the test does — the steps and assertions. For multi-step scenarios, list the endpoints involved. The 'why it is valuable' belongs in reasoning."),
+        .describe("Walkthrough of what the test does — the steps and assertions. For multi-step scenarios, list the endpoints involved. The 'why it is valuable' belongs in reasoning. Name any UI element the way a person would, e.g. the disabled 'Mark all as read' button — never a builder term such as blueprint or DOM analyzer, and never identifier syntax such as role=button or accessibleName=X."),
     priority: z
         .preprocess((val) => (typeof val === "string" ? val.toLowerCase() : val), z.enum(["high", "medium", "low"]))
         .describe("Priority level: high, medium, or low. First check diff relevance — does the test target an endpoint changed in this PR? HIGH: diff-relevant security/auth/error tests, cross-resource isolation for diff endpoints, CRUD lifecycle for NEW endpoints in the diff. MEDIUM: diff-relevant business-rule happy paths, multi-resource workflows involving diff endpoints, security/error tests for NON-diff endpoints. LOW: tests targeting only unchanged endpoints, trivially discoverable happy paths duplicating generated tests."),
@@ -462,14 +432,14 @@ export const additionalRecommendationSchema = z.preprocess(stripNullGroundingFie
         .describe("Path to Playwright/UI trace file if available, e.g. 'tests/skyramp-playwright.zip'. UI tests need this; E2E tests need both frontend and backend traces."),
     reasoning: z
         .string()
-        .describe("Why this test is recommended: the specific production risk, business rule, or security boundary it would validate"),
+        .describe("Why this test is recommended: the specific production risk, business rule, or security boundary it would validate. Name any UI element the way a person would, e.g. the disabled 'Mark all as read' button — never a builder term such as blueprint or DOM analyzer, and never identifier syntax such as role=button or accessibleName=X."),
     repository: repositoryField,
     targetElements: z
         .array(targetElementSchema)
         .min(1)
         .nullable()
         .optional()
-        .describe("UI tests only: structured grounding for one or more elements the test targets. Most tests target a single element (array length 1); render-state and multi-step UI tests target several (array length 2+). Each entry must be lifted verbatim from a captured blueprint element. Set to null when blueprint capture failed (also requires '[no-blueprint-data]' marker in BOTH description and reasoning). See Blueprint Citation Invariant in testbot prompt."),
+        .describe("UI tests only: structured grounding for one or more elements the test would target. Most recommendations target a single element (array length 1); render-state and multi-step UI tests target several (array length 2+). Each entry must be lifted verbatim from a captured blueprint element. Set to null when no capture covers the screen — this test was never written, so null needs no marker. See Blueprint Citation Invariant in testbot prompt."),
     pageContext: pageContextSchema
         .optional()
         .describe("UI tests only: page metadata for the test. Lifted from the BlueprintCapture used during grounding."),
@@ -499,7 +469,7 @@ export const additionalRecommendationSchema = z.preprocess(stripNullGroundingFie
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 path: ["targetElements"],
-                message: "targetElements is required for testType: 'ui'. Use null when blueprint capture failed (and add '[no-blueprint-data]' to both description and reasoning).",
+                message: "targetElements is required for testType: 'ui'. Use null when no capture covers the screen.",
             });
         }
         if (Array.isArray(rec.targetElements) &&
@@ -510,29 +480,8 @@ export const additionalRecommendationSchema = z.preprocess(stripNullGroundingFie
                 message: "pageContext is required for testType: 'ui' when targetElements is an array.",
             });
         }
-        if (rec.targetElements === null && rec.pageContext !== undefined) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: ["pageContext"],
-                message: "pageContext must be omitted when targetElements is null (no blueprint data).",
-            });
-        }
-        if (rec.targetElements === null) {
-            if (!rec.reasoning.includes("[no-blueprint-data]")) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    path: ["reasoning"],
-                    message: "reasoning must contain '[no-blueprint-data]' when targetElements is null.",
-                });
-            }
-            if (!rec.description.includes("[no-blueprint-data]")) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    path: ["description"],
-                    message: "description must contain '[no-blueprint-data]' when targetElements is null.",
-                });
-            }
-        }
+        // No marker is asked for here: a recommendation was never written, so
+        // `targetElements: null` is its normal state rather than a lost capture.
     }
 }));
 // TODO(multi-repo maintenance): no `repository` field yet — see readData() TODO below.
@@ -540,7 +489,7 @@ const testMaintenanceSchema = z.object({
     testType: z.nativeEnum(TestType).describe("Type of test."),
     endpoint: z
         .string()
-        .describe("HTTP verb and path, e.g. 'GET /api/v1/products'"),
+        .describe("For contract and integration tests, the HTTP verb and path, e.g. 'GET /api/v1/products'. For ui and e2e tests, the page path the test opens, e.g. '/notifications'."),
     testFilePath: z
         .string()
         .refine((p) => path.isAbsolute(p), {
@@ -582,6 +531,12 @@ const testMaintenanceDetailSchema = testMaintenanceLLMSchema.pick({
     beforeDetails: true,
     afterDetails: true,
 });
+/** The key an answer is matched by: the objection's id AND its message. The id
+ *  alone is not unique — one verifier raises several different objections under
+ *  it — and the message is what the reader judges the answer against. */
+function answerKey(objection) {
+    return `${objection.objectionId}\n${objection.message}`;
+}
 /**
  * Derive per-run analytics counts from a submitted report. These power the
  * alpha-launch dashboards (tests generated/maintained, suite growth, bugs vs
@@ -734,6 +689,145 @@ function deduplicateById(items) {
     }
     return result;
 }
+/** Recommendation v2, post-execution half: the checks that need the tests to
+ *  exist and to have run. Nothing here is a gate — the tests are already written,
+ *  so an objection is a record in the report. */
+/** One execution outcome per delivered test, joined by FILE and never by array
+ *  position. Repository must match BEFORE the file comparison — `fileName` is a
+ *  basename. A file can own several rows: failed if ANY failed, first failure
+ *  carries the text; `Skipped` rows are evidence in neither direction. */
+function collectExecutionOutcomes(delivered, results) {
+    // Absent names nothing to disagree with, so it matches any — the same rule
+    // `checkEveryDeliveredTestRan` uses.
+    const sameRepository = (a, b) => {
+        const left = (a ?? "").trim();
+        const right = (b ?? "").trim();
+        return left === "" || right === "" || left === right;
+    };
+    const outcomes = [];
+    for (const test of delivered) {
+        const plannedTestId = test.plannedTestId?.trim();
+        if (!plannedTestId)
+            continue;
+        const rows = results.filter((row) => row.status !== "Skipped" &&
+            sameRepository(row.repository, test.repository) &&
+            testFileMatches(row.testFilePath, test.fileName));
+        if (rows.length === 0)
+            continue;
+        const failed = rows.find((row) => row.status === "Fail");
+        outcomes.push({
+            plannedTestId,
+            passed: !failed,
+            ...(failed ? { failureDetail: failed.details } : {}),
+            // Off the failing row, since that is the row the statement is about.
+            ...(failed && typeof failed.reachedBehavior === "boolean"
+                ? { reachedBehavior: failed.reachedBehavior }
+                : {}),
+        });
+    }
+    return outcomes;
+}
+/** One check, crash contained: the plan is read off disk, so a malformed field can
+ *  throw and a throw here would lose the whole report. The id prefix is a separate
+ *  argument because expectedOutcome's plan-time half mints its own. */
+function runPostExecutionCheck(name, objectionIdPrefix, check) {
+    try {
+        return check();
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        logger.warning(`Post-execution check ${name} threw: ${detail}`);
+        return [
+            {
+                objectionId: `${objectionIdPrefix}:crashed`,
+                verifier: name,
+                message: `The ${name} check could not run against this report.`,
+                evidence: `${name} threw: ${detail}`,
+                suggestion: "The report was written and the other checks still ran. A field of the stored plan is probably not the type the schema describes — re-submit the plan with skyramp_register_test_plan.",
+            },
+        ];
+    }
+}
+// ── Report-time checks on what the customer will read ───────────────────────
+/** One report entry per plan planned test. The expectedOutcome check keys results by
+ *  `plannedTestId` and the LAST wins, so a second entry with one id silently chose
+ *  which result answered for the planned test. The plan side keeps ids unique;
+ *  nothing checked the reverse. */
+function checkOneEntryPerCandidate(delivered) {
+    const byCandidate = new Map();
+    for (const test of delivered) {
+        const id = test.plannedTestId?.trim();
+        if (!id)
+            continue;
+        byCandidate.set(id, [...(byCandidate.get(id) ?? []), test.testId]);
+    }
+    return [...byCandidate]
+        .filter(([, testIds]) => testIds.length > 1)
+        .map(([plannedTestId, testIds]) => ({
+        objectionId: `oneEntryPerCandidate:${plannedTestId}`,
+        verifier: "oneEntryPerCandidate",
+        plannedTestId,
+        message: "Two report entries name one plan planned test. Only one of them can be the test that planned test asked for, and the checks that read the planned test's declaration cannot tell which.",
+        evidence: `planned test ${plannedTestId} claimed by: ${testIds.join(", ")}`,
+        suggestion: "Give each entry the plannedTestId of the planned test it really delivers, or plan the second test and use its own id.",
+    }));
+}
+/** Every delivered test has an execution result. The expectedOutcome check is silent for
+ *  a planned test with no outcome, so a filename the results do not carry was the
+ *  way past it. This is the check that says so. */
+function checkEveryDeliveredTestRan(delivered, results) {
+    // A side that names no repository names none to disagree with, so it matches
+    // any. A single-repo run fills the field on one list and not the other often
+    // enough that requiring both to agree reported tests that had plainly run.
+    const sameRepository = (a, b) => {
+        const left = (a ?? "").trim();
+        const right = (b ?? "").trim();
+        return left === "" || right === "" || left === right;
+    };
+    return delivered
+        .filter((test) => !results.some((row) => sameRepository(row.repository, test.repository) &&
+        testFileMatches(row.testFilePath, test.fileName)))
+        .map((test) => {
+        // Say which half failed. "No row names that file" reads as a missing run
+        // when the file is there and only the repository differs.
+        const byName = results.filter((row) => testFileMatches(row.testFilePath, test.fileName));
+        const evidence = byName.length
+            ? `reported as ${test.fileName} for ${test.repository?.trim() || "no repository"}, and the ${byName.length === 1 ? "row" : "rows"} naming that file ${byName.length === 1 ? "is" : "are"} for ${byName.map((row) => row.repository?.trim() || "no repository").join(", ")}`
+            : `reported as ${test.fileName}, no testResults row names that file`;
+        return {
+            objectionId: `deliveredTestRan:${test.testId}`,
+            verifier: "deliveredTestRan",
+            message: "This test is in the report and in no execution result. Nothing says whether it passes, so the checks that read its outcome stayed silent about it.",
+            evidence,
+            suggestion: "Run the test and add its result to `testResults` under the same file name, or take the entry out of the report.",
+        };
+    });
+}
+/** The four types a plan can express. `registerTestPlanTool`'s `PLAN_TEST_TYPES`
+ *  is the same list; the report accepts every `TestType`, so an entry outside
+ *  these four can never name a plan planned test and must not be asked to. */
+const PLANNABLE_TEST_TYPES = new Set([
+    TestType.CONTRACT,
+    TestType.INTEGRATION,
+    TestType.E2E,
+    TestType.UI,
+]);
+function runPostExecutionChecks(plan, delivered, results, issues) {
+    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
+        // agent has no way to fix.
+        .filter((test) => PLANNABLE_TEST_TYPES.has(test.testType))
+        .map((test) => test.plannedTestId?.trim())
+        .filter((id) => !!id)
+        .map((plannedTestId) => ({ plannedTestId }));
+    return [
+        ...runPostExecutionCheck("deliveredMatchesPlan", "deliveredMatchesPlan", () => checkDeliveredMatchesPlan(plan, shipped)),
+        ...runPostExecutionCheck("expectedOutcome", "expectedOutcome:executed", () => checkExpectedOutcomeAfterExecution(plan, collectExecutionOutcomes(delivered, results), issues)),
+        ...runPostExecutionCheck("reportedCategory", "reportedCategory", () => checkReportedCategoryMatchesPlan(plan, delivered)),
+        ...runPostExecutionCheck("requirementConflictReported", "requirementConflictReported", () => checkRequirementConflictReported(plan, delivered, issues)),
+    ];
+}
 export function registerSubmitReportTool(server) {
     server.registerTool(TOOL_NAME, {
         annotations: {
@@ -742,8 +836,9 @@ export function registerSubmitReportTool(server) {
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: "Submit the final testbot report. Call this tool once after completing all test analysis, generation, and execution. " +
-            "This is the ONLY way to submit the report — do NOT write the report to a file manually.",
+        description: "Submit the final testbot report. Call this tool once, after all test analysis, generation and execution. " +
+            "This is the ONLY way to submit the report — do NOT write the report to a file manually. " +
+            "If a check objects to what you reported, the objection names an id: fix what you can, and answer the rest through `answers` on a second call.",
         inputSchema: {
             businessCaseAnalysis: z
                 .string()
@@ -752,11 +847,13 @@ export function registerSubmitReportTool(server) {
             newTestsCreated: z
                 .array(newTestSchema)
                 .describe("List of new tests created. Use empty array [] if none."),
+            // Optional and unchecked: this run has no concept of a recommendation it
+            // does not write. Kept so an older caller still works.
             additionalRecommendations: z
                 .array(additionalRecommendationSchema)
                 .optional()
                 .default([])
-                .describe("Recommended tests that were not generated (lower priority). Only include recommendations that add distinct coverage beyond generated tests — do not pad with variants testing the same endpoint and flow."),
+                .describe("Leave this empty or omit it. Every test this run recommends is a test it generates: a test worth writing goes in the plan you submit to skyramp_register_test_plan, and nothing caps how many tests a plan may hold."),
             testMaintenanceDetails: z
                 .array(testMaintenanceDetailSchema)
                 .optional()
@@ -784,13 +881,27 @@ export function registerSubmitReportTool(server) {
                 .describe("Succinct commit message (if possible, under 72 chars) summarizing what Testbot did, " +
                 "e.g. 'add contract tests for /products endpoint' or 'update smoke tests for order API changes'. " +
                 "Used as both the git commit subject and the side PR title — the consumer applies truncation as needed."),
+            answers: z
+                .array(z
+                .object({
+                objectionId: z
+                    .string()
+                    .describe("The objection's id, exactly as this tool reported it after your last call. Answers are matched by the id AND the wording of the objection, never by position, so re-send the id as it was printed. An id this call raised no objection for closes nothing — a plan-time objection is answered through skyramp_register_test_plan instead."),
+                answer: z
+                    .string()
+                    .describe("Why the objection does not apply, or what you decided instead. A blank or whitespace-only answer closes nothing and the objection stays open."),
+            })
+                .strict())
+                .optional()
+                .default([])
+                .describe("One answer per check that objected to your previous call and that you do not intend to fix. An answered objection is published with your answer beside it and no longer counted open; an unanswered one is published on its own. Answers persist across calls, so an id answered once stays answered. There is no call limit."),
             stateFile: z
                 .string()
-                .describe("Path to the state file returned by skyramp_analyze_changes. Required — " +
-                "contains execution results for maintenance scoring (existingTests), " +
-                "discovered endpoints for coverage validation (newEndpoints), " +
-                "UI page context for frontend test grounding (uiContext), and the " +
-                "videos recorded for each executed browser test (executionVideos)."),
+                .optional()
+                .describe("Optional. A Testbot run finds its own state file, so leave this out. " +
+                "Give a path only to name a state file the run would not find by itself. " +
+                "The report is written beside it, and it holds the execution results, the " +
+                "page captures and the videos this report needs."),
         },
         _meta: {
             keywords: ["report", "summary", "testbot", "submit"],
@@ -802,6 +913,11 @@ export function registerSubmitReportTool(server) {
         // below when a report language is enforced, spread into the analytics
         // event in the finally. Empty (no properties) for non-enforced runs.
         const languageTelemetry = {};
+        // The run's own state file, unless the agent named one.
+        const stateFile = resolveRunStatePath(params.stateFile);
+        if (!stateFile) {
+            return toolError("This run has no state file. Call skyramp_analyze_changes first — it writes the state file this report goes beside.");
+        }
         // The report goes next to the state file, so in a Testbot run the state file has to
         // be in the run directory — that is where the action reads the report back from.
         // Two ways that breaks, both ending in a report nobody reads while this tool says
@@ -817,7 +933,7 @@ export function registerSubmitReportTool(server) {
                     "from $RUNNER_TEMP/skyramp. Set RUNNER_TEMP for the run. Retrying or changing " +
                     "the report will not help — this is an environment problem.");
             }
-            const stateDir = path.dirname(params.stateFile);
+            const stateDir = path.dirname(stateFile);
             if (path.resolve(stateDir) !== path.resolve(runDir)) {
                 return toolError(`Cannot write the report: stateFile is in ${stateDir}, but this run's directory ` +
                     `is ${runDir}. The report is written next to the state file and the Testbot ` +
@@ -925,7 +1041,7 @@ export function registerSubmitReportTool(server) {
         const dedupedRecommendations = deduplicateById([
             ...(params.additionalRecommendations ?? []),
         ]);
-        const stateManager = StateManager.fromStatePath(params.stateFile);
+        const stateManager = StateManager.fromStatePath(stateFile);
         let stateData;
         try {
             // Only reads the primary repo — see the related-repo check below for why related
@@ -937,7 +1053,7 @@ export function registerSubmitReportTool(server) {
             return errorResult;
         }
         if (!stateData) {
-            errorResult = toolError(`stateFile not found or empty: ${params.stateFile}`);
+            errorResult = toolError(`stateFile not found or empty: ${stateFile}`);
             return errorResult;
         }
         // undefined + existing tests present means skyramp_actions was never called this
@@ -951,49 +1067,47 @@ export function registerSubmitReportTool(server) {
                 "Call skyramp_actions (with recommendations: [] if no existing tests needed action) before skyramp_submit_report.");
             return errorResult;
         }
-        // SKYR-3879 Path B: every gated newTestsCreated entry (contract/integration —
-        // the testTypes actually wired to planGuard) must be admissible under the
-        // approved plan from skyramp_register_test_plan — the same predicate the
-        // generation-tool gate uses (GENERATE, or ADDITIONAL backfill when GENERATE
-        // is non-empty), so a generation the gate permitted is never rejected at
-        // report time. Absent approvedPlan (register tool never ran / never
-        // pre-seeded anything) → no check, back-compat.
+        // Every gated entry names a plan planned test by `plannedTestId`, and NOT
+        // conditionally on a plan existing: with none, every entry fails here, where
+        // skipping the check would read exactly like a satisfied plan.
         //
-        // SKYR-4123: the name must be part of the query for that parity to hold.
-        // Every generation tool passes scenarioName; this side did not, so the plan
-        // item's `name:` key was dead here and a test the gate had already let
-        // through was rejected while being listed as approved in the same message.
-        if (stateData.approvedPlan) {
-            const approvedPlan = stateData.approvedPlan;
+        // The planned test must be of the entry's OWN test type, trimmed and lower-cased
+        // because the plan's `testType` is free-form text; one stating no type is
+        // accepted. EXEMPT: a plan whose `plannedTests` is not an array cannot be read,
+        // and that is no evidence a test went unplanned. An ABSENT plan is not that.
+        const planUnreadable = !!stateData.plan && !Array.isArray(stateData.plan.plannedTests);
+        if (!planUnreadable) {
+            const planCandidates = stateData.plan?.plannedTests ?? [];
+            const plannedById = new Map();
+            for (const plannedTest of planCandidates) {
+                const id = plannedTest?.plannedTestId?.trim();
+                // First wins: `buildRegistration` suffixes a repeat, so a shared id can
+                // only come from a hand-edited plan.
+                if (id && !plannedById.has(id))
+                    plannedById.set(id, plannedTest);
+            }
             const unapproved = dedupedNewTests.filter((t) => {
                 if (!PLAN_GATED_TEST_TYPES.has(t.testType))
                     return false;
-                const endpoints = parseEndpointField(t.endpoint);
-                const names = planNameCandidates(t.testId, t.testType);
-                return !(names.length > 0 ? names : [undefined]).some((scenarioName) => endpoints.some(({ method, path }) => matchesApprovedPlan(approvedPlan, {
-                    scenarioName,
-                    testType: t.testType,
-                    method,
-                    path,
-                })));
+                const plannedTest = plannedById.get((t.plannedTestId ?? "").trim());
+                if (!plannedTest)
+                    return true;
+                const plannedType = String(plannedTest.scenario?.testType ?? "").trim().toLowerCase();
+                return plannedType !== "" && plannedType !== t.testType;
             });
             if (unapproved.length > 0) {
-                const approvedList = approvedPlan.generate.length > 0
-                    ? // Show each item's endpoint keys: without them a rejection that turns on
-                        // the endpoint reads as self-contradicting, because the entry's own name
-                        // is printed in this same list (SKYR-4123).
-                        approvedPlan.generate
-                            .map((item) => {
-                            const eps = item.matchKeys.filter((k) => k.startsWith("ep:"));
-                            return `[${item.testType}] ${item.scenarioName}${eps.length > 0 ? ` covering ${eps.join(", ")}` : ""}`;
-                        })
-                            .join("; ")
-                    : "(none)";
-                errorResult = toolError(`${unapproved.length} newTestsCreated entr${unapproved.length === 1 ? "y" : "ies"} not in the approved plan from ` +
-                    `skyramp_register_test_plan (plan ${approvedPlan.planId}) — neither its GENERATE list nor its ADDITIONAL backfill pool: ` +
-                    `${unapproved.map((t) => `${t.testId} (${t.testType} ${t.endpoint})`).join(", ")}. ` +
-                    `Approved GENERATE items: ${approvedList}. Call skyramp_register_test_plan to register this test before reporting it, ` +
-                    `or remove it from newTestsCreated.`);
+                const plannedList = plannedById.size > 0
+                    ? planCandidates
+                        .map((plannedTest) => `${plannedTest?.plannedTestId} (${plannedTest?.scenario?.testType ?? "?"} ${plannedTest?.scenario?.scenarioName ?? "?"})`)
+                        .join("; ")
+                    : "(none — no plan was submitted this run)";
+                errorResult = toolError(`${unapproved.length} newTestsCreated entr${unapproved.length === 1 ? "y" : "ies"} name no planned test of its own ` +
+                    `testType in the plan submitted to skyramp_register_test_plan: ` +
+                    `${unapproved
+                        .map((t) => `${t.testId} (${t.testType}, plannedTestId: ${(t.plannedTestId ?? "").trim() || "missing"})`)
+                        .join(", ")}. ` +
+                    `Planned planned tests: ${plannedList}. Submit a plan that contains these tests with skyramp_register_test_plan, ` +
+                    `then resubmit this report with each entry's plannedTestId copied from it — or remove the entries from newTestsCreated.`);
                 return errorResult;
             }
         }
@@ -1016,12 +1130,20 @@ export function registerSubmitReportTool(server) {
         // action/testType/endpoint/description come entirely from stateData.maintenanceVerdicts
         // (written by skyramp_actions right after drift analysis) — the LLM never supplies
         // testMaintenance directly, so there's nothing to re-transcribe here.
+        // `pomFile` rides along per row and is stripped from the wire format below,
+        // like testFilePath. It cannot be keyed by spec path: a spec emits one UPDATE
+        // verdict PER page object, so a spec-keyed map keeps only the last.
         const rawMaintenance = (stateData.maintenanceVerdicts ?? []).map((v) => ({
             testFilePath: v.testFilePath,
+            pomFile: v.pomFile,
             testType: v.testType,
             endpoint: v.endpoint,
             action: v.action,
-            description: v.rationale,
+            // A baseline refresh (SKYR-4298) leaves the spec untouched, so name the
+            // replaced PNGs here — the reviewer's cue to open the image diff in the PR.
+            description: v.rebaselineSnapshots?.length
+                ? `${v.rationale} (visual baseline refreshed: ${v.rebaselineSnapshots.join(", ")})`
+                : v.rationale,
             beforeDetails: "",
             afterDetails: "",
         }));
@@ -1135,7 +1257,7 @@ export function registerSubmitReportTool(server) {
                             `Testbot will not report file work that hasn't actually been made. Do NOT make a token edit to the claimed file just to satisfy this check.\n` +
                             `For a newTestsCreated claim: create the file, correct the claim's fileName to the file you actually created (see the changed files below), or remove the claim.\n` +
                             `For a testMaintenance claim: make the edit on the named file. That row is derived from the maintenance triage, not from this tool's input, so it cannot be corrected by changing what you pass here.\n` +
-                            `Unbacked claims:\n${unbacked.map((u) => `  - ${u}`).join("\n")}\n` +
+                            `Unbacked changes:\n${unbacked.map((u) => `  - ${u}`).join("\n")}\n` +
                             `Files with actual working-tree changes:\n${changedList || "  (none)"}`);
                         return errorResult;
                     }
@@ -1174,7 +1296,7 @@ export function registerSubmitReportTool(server) {
                 errorResult = toolError(citations.invalid.join("\n"));
                 return errorResult;
             }
-            // The checkout the citation resolved in owns the finding, so the report
+            // The checkout the citation resolved in owns the objection, so the report
             // states it. Left to the consumer, an unattributed related-repo path is
             // resolved against the primary checkout and links the wrong repo's file.
             citations.repository.forEach((repo, i) => {
@@ -1187,7 +1309,7 @@ export function registerSubmitReportTool(server) {
         // generation — downstream scoring scripts don't expect them and fail if
         // they encounter these string fields while traversing the object.
         // Also normalize each item's `repository` (blank → undefined).
-        // Checkout roots let the assertion-record matcher verify a candidate
+        // Checkout roots let the assertion-record matcher verify a planned test
         // record actually lives in the row's repo (basename collisions across
         // repos must not publish one spec's proof-of-work under another's name).
         const assertionCheckouts = await stateManager
@@ -1197,6 +1319,246 @@ export function registerSubmitReportTool(server) {
             const row = await attachReuseOutcome(normalizeRepository(rest), stateData.reuseOutcomes, stateData.reuseHandOffs, retrofitViews);
             return attachAssertionOutcome(row, stateData.assertionOutcomes ?? {}, assertionCheckouts);
         }));
+        // The report enum has no `bug_caught` value, so which failure was on purpose
+        // is derived from the plan rather than from agent prose. Read defensively:
+        // the plan comes off disk.
+        const failOnPurpose = new Set();
+        for (const plannedTest of Array.isArray(stateData.plan?.plannedTests)
+            ? stateData.plan.plannedTests
+            : []) {
+            const id = plannedTest?.plannedTestId?.trim();
+            if (!id)
+                continue;
+            // Off the category table, not a literal comparison: `changedFile`'s
+            // neighbour normalises case, space and separator, and the two must agree.
+            if (categoryExpectsRed(plannedTest?.scenario?.category) ||
+                plannedTest?.declarations?.expected?.outcome === "fail") {
+                failOnPurpose.add(id);
+            }
+        }
+        for (const test of sanitizedNewTests) {
+            if (failOnPurpose.has((test.plannedTestId ?? "").trim())) {
+                test.expectedToFail = true;
+            }
+        }
+        // Report-time checks on what the customer will read. They need no plan, so a
+        // run without one still gets them.
+        const reportChecks = [
+            ...runPostExecutionCheck("oneEntryPerCandidate", "oneEntryPerCandidate", () => checkOneEntryPerCandidate(dedupedNewTests)),
+            // Not in the plan-only lane: that lane requires `testResults` to be empty,
+            // so the check would flag every planned test.
+            ...(isPlanOnlyMode()
+                ? []
+                : runPostExecutionCheck("deliveredTestRan", "deliveredTestRan", () => checkEveryDeliveredTestRan(dedupedNewTests, params.testResults))),
+        ];
+        // Run against an EMPTY plan when none was submitted, never skipped: the gate
+        // above covers contract and integration only. An empty plan raises exactly
+        // the "delivered but unplanned" half, which is the true statement.
+        let objections;
+        let changeTable;
+        {
+            const postExecution = runPostExecutionChecks(stateData.plan ?? { plannedTests: [], registrationNumber: 0, answers: [], openObjections: [], answeredObjections: [] }, dedupedNewTests, params.testResults, params.issuesFound ?? []);
+            // 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)
+                ? stateData.plan.openObjections
+                : [];
+            // An answered objection is published WITH its answer, beside the open ones:
+            // any non-blank answer closes one, so publishing only the open would let a
+            // single character erase the record. The reader judges the answer, not the
+            // server.
+            const answered = Array.isArray(stateData.plan?.answeredObjections)
+                ? stateData.plan.answeredObjections
+                : [];
+            // Closed by a blocker the server could not check. Published with the blocker
+            // it names, so a reader can count how much of this run's accountability
+            // rests on a claim nothing verified.
+            const unverified = Array.isArray(stateData.plan?.unverifiedCloses)
+                ? stateData.plan.unverifiedCloses
+                : [];
+            // Post-execution objections are recomputed on every call, so one the agent
+            // fixed is gone and one it did not is raised again. Recomputation loses the
+            // ANSWER, which arrives on one call and is needed on every later one, so the
+            // answered set is persisted below and merged with this call's answers.
+            const acknowledged = params.answers ?? [];
+            // The message is part of the key, not just the id: one id covers several
+            // objections — `expectedOutcome:executed:<id>` is raised for a should-fail
+            // test that passed, a should-pass one that failed, and a failure that never
+            // reached its behaviour — so an id-only match would close the wrong one.
+            const carried = (Array.isArray(stateData.reportObjections?.answeredObjections)
+                ? stateData.reportObjections.answeredObjections
+                : []).filter((entry) => typeof entry?.objection?.objectionId === "string" &&
+                typeof entry?.answer === "string" &&
+                entry.answer.trim().length > 0);
+            const carriedByKey = new Map(carried.map((entry) => [answerKey(entry.objection), entry]));
+            // What the LAST call raised. Without it there is nothing to notice a
+            // fixed objection's absence against.
+            const previouslyRaised = (Array.isArray(stateData.reportObjections?.raisedObjections)
+                ? stateData.reportObjections.raisedObjections
+                : []).filter((entry) => typeof entry?.objection?.objectionId === "string");
+            // When an objection was first raised. Restamping it every call said an
+            // objection answered on call 2 was raised on call 2, so a reader could not
+            // tell how long it had stood (run 33984531266, sb19-home-dashboard). The
+            // number comes off disk, so a non-number is treated as no record.
+            const firstRaisedAt = new Map(previouslyRaised
+                .filter((entry) => Number.isFinite(entry.submission))
+                .map((entry) => [answerKey(entry.objection), entry.submission]));
+            const previouslyResolved = (Array.isArray(stateData.reportObjections?.resolvedObjections)
+                ? stateData.reportObjections.resolvedObjections
+                : []).filter((entry) => typeof entry?.objection?.objectionId === "string" &&
+                typeof entry?.resolvedBy === "string");
+            const submissionNumber = (stateData.reportObjections?.submissionCount ?? 0) + 1;
+            const raised = [...postExecution, ...reportChecks];
+            // Answerable = raised by THIS call or by an earlier one. The agent fixes an
+            // objection and answers it in the same call: fixing it stops the check
+            // raising it, so matching against this call alone called the answer unknown
+            // and objected to the agent for doing both (run 33946409570, sb19).
+            const answerable = [...raised, ...previouslyRaised.map((entry) => entry.objection)];
+            const reportStageObjections = [
+                ...raised,
+                ...unknownAnswerObjections(answerable, acknowledged, {
+                    scope: "this run raised",
+                    suggestion: "Answer only the ids this tool has listed on this run. A plan-time objection is answered through skyramp_register_test_plan's own answers, not here.",
+                }),
+            ];
+            const raisedNow = new Set(reportStageObjections.map(answerKey));
+            // A call with no execution result gives these checks nothing to judge, so
+            // their silence is not evidence: only a call carrying results can resolve an
+            // earlier objection.
+            const judgedThisCall = (params.testResults ?? []).length > 0;
+            // Resolved = raised earlier, absent from a call that could have raised it.
+            // One that comes back drops out: publishing it as both says two things.
+            const resolvedObjections = [
+                ...previouslyResolved,
+                ...(judgedThisCall
+                    ? previouslyRaised
+                        .filter((entry) => !raisedNow.has(answerKey(entry.objection)))
+                        .map((entry) => ({
+                        objection: entry.objection,
+                        resolvedBy: `submission ${submissionNumber}`,
+                    }))
+                    : []),
+            ].filter((entry, index, all) => !raisedNow.has(answerKey(entry.objection)) &&
+                all.findIndex((other) => answerKey(other.objection) === answerKey(entry.objection)) === index);
+            const answeredReportObjections = [];
+            const openReportObjections = [];
+            for (const objection of reportStageObjections) {
+                const answer = answerFor(objection, acknowledged) ?? carriedByKey.get(answerKey(objection))?.answer;
+                if (answer)
+                    answeredReportObjections.push({ objection, answer });
+                else
+                    openReportObjections.push(objection);
+            }
+            objections = [
+                ...stillOpen.map((objection) => ({
+                    ...objection,
+                    stage: "plan",
+                })),
+                ...answered
+                    .filter((entry) => entry?.objection)
+                    .map((entry) => ({
+                    ...entry.objection,
+                    stage: "plan",
+                    answer: typeof entry.answer === "string" ? entry.answer : "",
+                })),
+                ...unverified
+                    .filter((entry) => entry?.objection)
+                    .map((entry) => ({
+                    ...entry.objection,
+                    stage: "plan",
+                    answer: typeof entry.answer === "string" ? entry.answer : "",
+                    unverifiedBlocker: typeof entry.blocker === "string" ? entry.blocker : "",
+                })),
+                ...openReportObjections.map((objection) => ({
+                    ...objection,
+                    stage: "post-execution",
+                })),
+                ...answeredReportObjections.map(({ objection, answer }) => ({
+                    ...objection,
+                    stage: "post-execution",
+                    answer,
+                })),
+                ...resolvedObjections.map(({ objection, resolvedBy }) => ({
+                    ...objection,
+                    stage: "post-execution",
+                    resolvedBy,
+                })),
+            ];
+            // The change table: what the agent said the diff makes, and what it
+            // delivered against each promise. Read defensively — the plan comes off
+            // disk, so its declared array types hold only on the validated path.
+            const declaredChanges = Array.isArray(stateData.plan?.changes)
+                ? stateData.plan.changes
+                : [];
+            if (declaredChanges.length > 0) {
+                const changesByCandidate = new Map();
+                for (const plannedTest of Array.isArray(stateData.plan?.plannedTests)
+                    ? stateData.plan.plannedTests
+                    : []) {
+                    const id = plannedTest?.plannedTestId?.trim();
+                    const cited = plannedTest?.declarations?.changes;
+                    if (id && Array.isArray(cited)) {
+                        changesByCandidate.set(id, cited.map((entry) => String(entry ?? "").trim()));
+                    }
+                }
+                const answerByChange = new Map();
+                for (const objection of objections) {
+                    if (!objection.objectionId.startsWith(CHANGE_OBJECTION_PREFIX))
+                        continue;
+                    const answer = typeof objection.answer === "string" ? objection.answer.trim() : "";
+                    if (answer)
+                        answerByChange.set(objection.objectionId.slice(CHANGE_OBJECTION_PREFIX.length), answer);
+                }
+                changeTable = declaredChanges.map((change) => {
+                    const id = String(change?.id ?? "").trim();
+                    const testedBy = dedupedNewTests
+                        .map((test) => (test.plannedTestId ?? "").trim())
+                        .filter((plannedTestId) => plannedTestId && (changesByCandidate.get(plannedTestId) ?? []).includes(id));
+                    const answer = answerByChange.get(id);
+                    return {
+                        id,
+                        text: String(change?.text ?? ""),
+                        source: String(change?.source ?? ""),
+                        testedBy,
+                        ...(answer ? { answer } : {}),
+                    };
+                });
+            }
+            // An answer outlives both the call it was given on and the calls where
+            // its objection does not fire, so the persisted set is this call's answers
+            // plus every carried answer this call did not re-raise. The objections
+            // are recomputed, so a stored copy would have no reader.
+            const answeredNow = new Set(answeredReportObjections.map(({ objection }) => answerKey(objection)));
+            // The report is the deliverable, so a failed state write must not cost
+            // it; the answer is simply repeated on the next call.
+            try {
+                await stateManager.writeData({
+                    ...stateData,
+                    reportObjections: {
+                        answeredObjections: [
+                            ...answeredReportObjections,
+                            ...carried.filter((entry) => !answeredNow.has(answerKey(entry.objection))),
+                        ],
+                        // A call that judged nothing keeps the earlier entries it did not
+                        // re-raise: unresolved, merely unjudged.
+                        raisedObjections: [
+                            ...reportStageObjections.map((objection) => ({
+                                objection,
+                                submission: firstRaisedAt.get(answerKey(objection)) ?? submissionNumber,
+                            })),
+                            ...(judgedThisCall
+                                ? []
+                                : previouslyRaised.filter((entry) => !raisedNow.has(answerKey(entry.objection)))),
+                        ],
+                        resolvedObjections,
+                        submissionCount: submissionNumber,
+                    },
+                });
+            }
+            catch (error) {
+                logger.warning(`Could not persist report objections: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         const report = {
             businessCaseAnalysis: params.businessCaseAnalysis,
             newTestsCreated: sanitizedNewTests,
@@ -1206,7 +1568,10 @@ export function registerSubmitReportTool(server) {
             // TODO(multi-repo maintenance): map(normalizeRepository) once testMaintenanceSchema
             // has a repository field (see TODO above).
             testMaintenance: testMaintenance
-                ? await Promise.all(testMaintenance.map(async ({ testFilePath, ...row }) => {
+                ? await Promise.all(testMaintenance.map(async ({ testFilePath, pomFile, ...row }) => {
+                    // `pomFile` is the file skyramp_actions told the agent to edit;
+                    // `testFilePath` stays the spec, which is what ran. Name both when
+                    // they differ, or a page-object edit is reported against the spec.
                     // Maintenance rows still carry the absolute path here, so the
                     // assertion summary uses an EXACT canonical-path lookup — no
                     // basename ambiguity. This is what carries the maintenance
@@ -1220,6 +1585,10 @@ export function registerSubmitReportTool(server) {
                     return {
                         ...row,
                         fileName: path.basename(testFilePath),
+                        ...(pomFile &&
+                            path.basename(pomFile) !== path.basename(testFilePath)
+                            ? { editedFileName: path.basename(pomFile) }
+                            : {}),
                         ...(assertions ? { assertions } : {}),
                     };
                 }))
@@ -1234,13 +1603,15 @@ export function registerSubmitReportTool(server) {
             }),
             issuesFound,
             nextSteps: params.nextSteps ?? [],
+            ...(changeTable ? { changes: changeTable } : {}),
+            ...(objections ? { objections } : {}),
             commitMessage: (params.commitMessage ?? "").replace(/[\r\n]+/g, " ").trim() ||
                 DEFAULT_COMMIT_MESSAGE,
         };
         const reportJson = JSON.stringify(report, null, 2);
         // Beside the state file, which was read successfully above — so this directory is
         // known to exist and no mkdir is needed. See REPORT_FILE_NAME.
-        const reportPath = path.join(path.dirname(params.stateFile), REPORT_FILE_NAME);
+        const reportPath = path.join(path.dirname(stateFile), REPORT_FILE_NAME);
         logger.info("Submitting testbot report", {
             outputFile: reportPath,
             payloadBytes: reportJson.length,
@@ -1253,11 +1624,23 @@ export function registerSubmitReportTool(server) {
                 outputFile: reportPath,
                 elapsedMs: elapsed,
             });
+            // Addressed to the AGENT in the second person, each naming a next move: the
+            // report is already written when this returns and the tool can be called
+            // again, so the instruction is actionable. An answered objection is
+            // published but not listed back, which would read as a second demand.
+            const open = objections?.filter((objection) => objection.stage === "post-execution" && objection.answer === undefined) ?? [];
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Report submitted successfully to ${reportPath}`,
+                        text: `Report submitted successfully to ${reportPath}` +
+                            (open.length === 0
+                                ? ""
+                                : `\n\n${open.length} check${open.length === 1 ? "" : "s"} objected to what was reported. ` +
+                                    `Every one is published in the report as it stands; fix what you can and call this tool again.\n` +
+                                    open
+                                        .map((objection) => `- ${objection.objectionId} — ${objection.message}\n  evidence: ${objection.evidence}\n  next: ${objection.suggestion}`)
+                                        .join("\n")),
                     },
                 ],
             };