@skyramp/mcp 0.3.5 → 0.3.6-rc.2.ac20

package/build/tools/submitReportTool.js

@@ -3,24 +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 { TEST_CATEGORIES, externalCategory, } from "../types/TestRecommendation.js";
 import { TestType, HttpMethod } from "../types/TestTypes.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, } from "../utils/AnalysisStateManager.js";
 import { toolError, testFileMatches } from "../utils/utils.js";
 import { matchesApprovedPlan } from "../utils/planMatchKeys.js";
 import { isTestbotEnabled } from "../utils/featureFlags.js";
-import { findUnbackedClaims, listChangedFiles, listChangedFilesAcross } from "../utils/reportVerification.js";
+import { findInvalidSourceCitations, findUnchangedFileClaims, listChangedFiles, listChangedFilesAcross, } from "../utils/reportVerification.js";
 import { getReportLanguage, isEnforcedReportLanguage, findLanguageViolations, findLanguageNearMisses, reportLanguageDisplayName, } from "../utils/reportLanguage.js";
-import { rederiveReuseOutcome } from "./code-refactor/reuse-state.js";
+import { rederiveReuseOutcome, reuseChainSkipped, } from "./code-refactor/reuse-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.
-const PLAN_GATED_TEST_TYPES = new Set([TestType.CONTRACT, TestType.INTEGRATION]);
+const PLAN_GATED_TEST_TYPES = new Set([
+    TestType.CONTRACT,
+    TestType.INTEGRATION,
+]);
 /**
  * Filename of the report, written beside the state file. SKYR-4147: the report path is
  * derived here rather than accepted as a parameter. The caller builds the state file and
@@ -46,7 +49,9 @@ function planNameCandidates(testId, testType) {
     if (!id)
         return [];
     const prefix = `${testType}-`;
-    return id.toLowerCase().startsWith(prefix) ? [id, id.slice(prefix.length)] : [id];
+    return id.toLowerCase().startsWith(prefix)
+        ? [id, id.slice(prefix.length)]
+        : [id];
 }
 /**
  * Split an `endpoint` field into one {method, path} per endpoint it names.
@@ -55,14 +60,20 @@ function planNameCandidates(testId, testType) {
  * unmatchable path, so such an entry could match nothing (SKYR-4123).
  */
 function parseEndpointField(endpoint) {
-    const parts = (endpoint ?? "").split(",").map((p) => p.trim()).filter(Boolean);
+    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() };
+        return {
+            method: part.slice(0, spaceIdx),
+            path: part.slice(spaceIdx + 1).trim(),
+        };
     });
 }
 // Drift actions that actually modify a test file. VERIFY and IGNORE are
@@ -73,6 +84,96 @@ const MAINTENANCE_CHANGE_ACTIONS = new Set([
     DriftAction.Regenerate,
     DriftAction.Delete,
 ]);
+const EXTERNAL_TO_EXECUTION_STATUS = {
+    pass: TestExecutionStatus.Pass,
+    fail: TestExecutionStatus.Fail,
+    error: TestExecutionStatus.Error,
+};
+/** Does this run's file outcome describe `knownPath`?
+ *
+ *  `absoluteFile` is the framework's own path resolved against the root it reported,
+ *  so it names one file and is compared exactly. An outcome without one is refused:
+ *  a relative spelling is a suffix, and a suffix cannot separate
+ *  `packages/a/tests/x.spec.ts` from `packages/b/tests/x.spec.ts`. Guessing there and
+ *  guarding the guess is what this deliberately does not do — a missing status is a
+ *  row that reads Unknown, which is what it reads today; a wrong one is a false claim
+ *  about someone's tests.
+ *
+ *  The cost is real and accepted: a suite running inside a container reports the
+ *  container's root, which cannot equal the host path discovery recorded, so those
+ *  repos get no status until the run records a root the report can line up. */
+function outcomeMatches(outcome, knownPath) {
+    return (typeof outcome.absoluteFile === "string" &&
+        path.resolve(outcome.absoluteFile) === path.resolve(knownPath));
+}
+/** One line describing what the suite saw, for a row whose status came from the run
+ *  rather than from an execution the agent drafted a summary for. Without it the
+ *  rendered cell is a bare `Error` or `Pass` with nothing behind it. */
+function describeOutcome(o) {
+    // Defended like the record reads around it: a malformed outcome must not throw
+    // out of the handler and take the whole report submission with it.
+    const c = o.counts ?? { pass: 0, fail: 0, error: 0, skipped: 0 };
+    const parts = [
+        c.pass ? `${c.pass} passed` : "",
+        c.fail ? `${c.fail} failed` : "",
+        c.error ? `${c.error} errored` : "",
+        c.skipped ? `${c.skipped} skipped` : "",
+    ].filter(Boolean);
+    const head = `${parts.join(", ") || "no tests reported"} in the repo's own suite`;
+    // Adapter messages carry stack traces, so collapse whitespace before truncating:
+    // an embedded newline would break the maintenance row this lands in.
+    const first = (o.errors ?? [])[0]?.replace(/\s+/g, " ").trim();
+    return first ? `${head} — ${first.slice(0, 200)}` : head;
+}
+function externalStatusesFor(records, knownPath) {
+    // LATEST per suite, then WORST across suites. Both halves matter: a suite re-run
+    // after another edit supersedes its own earlier verdict, so an obsolete failure
+    // must not outlive the fix that repaired it; but two different suites can each
+    // own the same file, and a pass in one must not mask a failure in the other.
+    const RANK = { pass: 0, fail: 1, error: 2 };
+    const statusIn = (mode) => {
+        const latestPerSuite = new Map();
+        for (const record of records ?? []) {
+            if (record.mode !== mode || record.skipped || !record.environmentHealthy)
+                continue;
+            // A suite that stopped on --max-failures left tests unrun and does not say
+            // which, so no file it touched can stand as covered. The adapter reports this;
+            // it is not a guess. (The tool forces --max-failures=0 for confirm, so this is
+            // reachable on a verify re-run under the repo's own cap.)
+            if (record.diagnostics?.maxFailuresBail)
+                continue;
+            const hit = (record.files ?? []).find((o) => outcomeMatches(o, knownPath));
+            if (!hit)
+                continue;
+            const key = record.suite ?? "";
+            const prior = latestPerSuite.get(key);
+            // `ranAt` is an ISO timestamp, so a lexical compare is chronological. The
+            // newest run wins BEFORE it is judged: a later partial re-run supersedes an
+            // earlier complete one, and must leave the row unknown rather than let the
+            // stale complete outcome stand in for it.
+            if (!prior || record.ranAt >= prior.at)
+                latestPerSuite.set(key, { at: record.ranAt, outcome: hit });
+        }
+        let worst;
+        for (const { outcome } of latestPerSuite.values()) {
+            // `skipped` means every test in the file was skipped — it was not exercised,
+            // and TestExecutionStatus.Skipped means a deliberate decision not to run it.
+            if (!outcome.complete || outcome.status === "skipped")
+                continue;
+            if (!worst || RANK[outcome.status] > RANK[worst.status])
+                worst = outcome;
+        }
+        return worst;
+    };
+    const before = statusIn("confirm");
+    const after = statusIn("verify");
+    return {
+        before: before && EXTERNAL_TO_EXECUTION_STATUS[before.status],
+        after: after && EXTERNAL_TO_EXECUTION_STATUS[after.status],
+        beforeDetail: before && describeOutcome(before),
+        afterDetail: after && describeOutcome(after),
+    };
+}
 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
@@ -89,23 +190,33 @@ const repositoryField = z
  *  (downstream consumers treat absence as "the primary repo"). */
 function normalizeRepository(item) {
     const trimmed = item.repository?.trim();
-    return trimmed ? { ...item, repository: trimmed } : { ...item, repository: undefined };
+    return trimmed
+        ? { ...item, repository: trimmed }
+        : { ...item, repository: undefined };
 }
 // videoPath is deliberately absent from this input contract: it is attached server-side
 // from the run's execution records (see attachVideoPath), and zod strips any the model
 // supplies anyway. SKYR-4156 is what happens when the agent owns that field instead.
 const testResultSchema = z.object({
-    testType: z.nativeEnum(TestType).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'"),
+    testType: z
+        .nativeEnum(TestType)
+        .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'"),
     status: z.enum(["Pass", "Fail", "Skipped"]).describe("Test execution result"),
-    details: z.string().describe("One sentence — no embedded newlines, no markdown. e.g. '10.8s, products_contract_test.py' or 'failed: <one-line error summary>, products_contract_test.py'"),
+    details: z
+        .string()
+        .describe("One sentence — no embedded newlines, no markdown. e.g. '10.8s, products_contract_test.py' or 'failed: <one-line error summary>, products_contract_test.py'"),
     // Required for every row: each one reports a specific test file the agent ran, so it
     // can always name it. It is what identifies the row server-side — `endpoint` cannot,
     // since several tests routinely exercise one endpoint — and for ui/e2e it is what
     // attaches the recorded video (SKYR-4156). Not included in the report itself.
     testFilePath: z
         .string()
-        .refine((p) => path.isAbsolute(p), { message: "testFilePath must be an absolute path" })
+        .refine((p) => path.isAbsolute(p), {
+        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."),
     repository: repositoryField,
 });
@@ -117,21 +228,47 @@ const testResultSchema = z.object({
 // parsing. `reasoning` is free-form prose constrained by the Blueprint
 // Citation Invariant — every element cited must appear in `targetElements`.
 // See testbot prompt step 4 for the full populate-and-render rules.
+/**
+ * Accept an omitted key as an explicit `null`.
+ *
+ * SKYR-4208. The blueprint capture no longer carries a key whose value is null,
+ * so an element the agent lifts verbatim simply has no `testId`, `stableId` or
+ * `contextText`. Consumers of the report still expect all three keys, so the
+ * missing one is filled in here rather than asked for in the prompt.
+ */
+function nullWhenAbsent(inner) {
+    return inner.nullish().transform((v) => v ?? null);
+}
 export const targetElementSchema = z.object({
-    role: z.string().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."),
-    testId: z.string().nullable().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: z.string().nullable().describe("Unique HTML id attribute value (fallback locator when no testId), or null. Lifted from the blueprint element's `stableId`."),
-    contextText: z.array(z.string()).nullable().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."),
-    mutability: z.enum(["mutable", "immutable", "unknown"]).optional().describe("Whether the element's content/state is expected to change between captures. 'mutable' elements are behavioral-test targets; 'immutable' are smoke-test targets. Copied from the blueprint element's `mutability`."),
-    widgetType: z.enum(["native", "custom", "unknown"]).optional().describe("'native' = HTML built-ins (button, input). 'custom' or 'unknown' = non-standard composites; fall back to snapshot-driven trial clicks for interaction. Copied from the blueprint element's `widgetType`."),
+    role: z
+        .string()
+        .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."),
+    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."),
+    mutability: z
+        .enum(["mutable", "immutable", "unknown"])
+        .optional()
+        .describe("Whether the element's content/state is expected to change between captures. 'mutable' elements are behavioral-test targets; 'immutable' are smoke-test targets. Copied from the blueprint element's `mutability`."),
+    widgetType: z
+        .enum(["native", "custom", "unknown"])
+        .optional()
+        .describe("'native' = HTML built-ins (button, input). 'custom' or 'unknown' = non-standard composites; fall back to snapshot-driven trial clicks for interaction. Copied from the blueprint element's `widgetType`."),
 });
 // Page metadata for a UI recommendation. Lifted from the BlueprintCapture
 // the agent used to populate `targetElements`. Codegen reads `url` to drive
 // page.goto(); the verifier uses `pageHash` to detect stale captures.
 export const pageContextSchema = z.object({
-    url: z.string().describe("URL of the page where the test runs. Lifted from BlueprintCapture.url."),
-    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."),
+    url: z
+        .string()
+        .describe("URL of the page where the test runs. Lifted from BlueprintCapture.url."),
+    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."),
 });
 /**
  * SKYR-4193: LLMs habitually emit every key a schema declares, using a
@@ -165,21 +302,53 @@ function stripNullGroundingFields(val) {
 // interface that adds an `implemented: boolean` field. Both describe the same
 // concept (a test recommendation) — the only difference is whether it was
 // generated in this run or left for later. Tracked per Archit's review comment.
-export const newTestSchema = z.preprocess(stripNullGroundingFields, z.object({
-    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."),
-    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"),
-    endpoint: z.string().describe("HTTP verb and path, e.g. 'GET /api/v1/products'"),
+export const newTestSchema = z.preprocess(stripNullGroundingFields, z
+    .object({
+    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."),
+    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"),
+    endpoint: z
+        .string()
+        .describe("HTTP verb and path, e.g. 'GET /api/v1/products'"),
     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."),
-    scenarioFile: z.string().optional().describe("Path to the scenario JSON file if one was generated (e.g. 'tests/scenario_collections-links.json')"),
-    traceFile: z.string().optional().describe("Path to the backend trace file if used or created"),
-    frontendTrace: z.string().optional().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"),
+    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."),
+    scenarioFile: z
+        .string()
+        .optional()
+        .describe("Path to the scenario JSON file if one was generated (e.g. 'tests/scenario_collections-links.json')"),
+    traceFile: z
+        .string()
+        .optional()
+        .describe("Path to the backend trace file if used or created"),
+    frontendTrace: z
+        .string()
+        .optional()
+        .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"),
     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."),
-    pageContext: pageContextSchema.optional().describe("UI tests only: page metadata for the test. Lifted from the BlueprintCapture used during grounding."),
-}).superRefine((rec, ctx) => {
+    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."),
+    pageContext: pageContextSchema
+        .optional()
+        .describe("UI tests only: page metadata for the test. Lifted from the BlueprintCapture used during grounding."),
+})
+    .superRefine((rec, ctx) => {
     // targetElements / pageContext are UI-only.
     if (rec.testType !== TestType.UI) {
         for (const field of ["targetElements", "pageContext"]) {
@@ -210,7 +379,8 @@ export const newTestSchema = z.preprocess(stripNullGroundingFields, z.object({
             });
         }
         // pageContext is required when targetElements is an array (grounded), forbidden when null.
-        if (Array.isArray(rec.targetElements) && rec.pageContext === undefined) {
+        if (Array.isArray(rec.targetElements) &&
+            rec.pageContext === undefined) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 path: ["pageContext"],
@@ -233,7 +403,8 @@ export const newTestSchema = z.preprocess(stripNullGroundingFields, z.object({
                     message: "reasoning must contain '[no-blueprint-data]' when targetElements is null.",
                 });
             }
-            if (rec.description && !rec.description.includes("[no-blueprint-data]")) {
+            if (rec.description &&
+                !rec.description.includes("[no-blueprint-data]")) {
                 ctx.addIssue({
                     code: z.ZodIssueCode.custom,
                     path: ["description"],
@@ -243,8 +414,18 @@ export const newTestSchema = z.preprocess(stripNullGroundingFields, z.object({
         }
     }
 }));
-const issueFoundSchema = z.object({
-    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 citation string the submit-time check verifies and the report then ships.
+ *  Normalized HERE, once, so the value the verifier resolved is byte-identical to
+ *  the value written: the check trimmed its input, so a padded " src/x.py " used to
+ *  validate against the real path and ship the unusable padded one. A
+ *  blank/whitespace-only value means "no citation", the same rule `repository` uses. */
+const citationString = z.preprocess((v) => (typeof v === "string" ? v.trim() || undefined : v), z.string().optional());
+const issueFoundSchema = z
+    .object({
+    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. " +
+        "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"])
         .optional()
@@ -256,36 +437,130 @@ const issueFoundSchema = z.object({
         .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). " +
         "type = a type-check failure (tsc, mypy). " +
-        "config = environment or tooling misconfiguration (wrong workspace auth type, missing env var, setup command failure). " +
+        "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,
+    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'. " +
+        "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. " +
+        "This tool rejects the report if the text does not appear in the cited file."),
+    sourceLine: z
+        .number()
+        .int()
+        .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. " +
+        "The tool does not check that the line still holds the cited code, because line numbers drift."),
+})
+    .superRefine((issue, ctx) => {
+    // A `bug` entry asserts that product code is wrong, so it has to name the code:
+    // 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
+    // source location (an unreachable app, a missing env var), so the requirement is
+    // scoped to `bug` alone.
+    //
+    // The exit when the code cannot be named is NOT to invent a citation: a failure
+    // the agent cannot localize is already reported by its `testResults` row, and
+    // a tool or environment failure belongs under `config`.
+    if (issue.category !== IssueFoundCategory.Bug)
+        return;
+    if (issue.sourceFile !== undefined)
+        return;
+    ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["sourceFile"],
+        message: `sourceFile is required when category is 'bug' — a bug entry must name the code it is about. ` +
+            `Open the file, then set sourceFile (path relative to the repository root). Also set sourceSymbol (the function or identifier inside it) when the file has one, and sourceLine (the line of the offending statement) when you have it — both are optional. ` +
+            `If you cannot point at the code: a test failure is already reported by its testResults entry, and a tool or environment failure belongs under category 'config' — do not guess a citation.`,
+    });
 });
 const scenarioStepSchema = z.object({
-    method: z.nativeEnum(HttpMethod).optional().describe("HTTP method. Required for API steps, omit for UI/E2E actions."),
-    path: z.string().optional().describe("Endpoint or page path (e.g. '/api/v1/products' or '/products'). Required for API steps, omit for UI actions."),
-    description: z.string().describe("What this step does, e.g. 'Create a product' or 'Click checkout button and verify confirmation'"),
-    expectedStatusCode: z.number().optional().describe("Expected HTTP status code, e.g. 200, 201, 404"),
-    requestBody: z.record(z.any()).optional().describe("Example request body with realistic field values"),
-    responseBody: z.record(z.any()).optional().describe("Key response fields to verify, e.g. { id: 'number', name: 'string', in_stock: 'boolean?' }"),
+    method: z
+        .nativeEnum(HttpMethod)
+        .optional()
+        .describe("HTTP method. Required for API steps, omit for UI/E2E actions."),
+    path: z
+        .string()
+        .optional()
+        .describe("Endpoint or page path (e.g. '/api/v1/products' or '/products'). Required for API steps, omit for UI actions."),
+    description: z
+        .string()
+        .describe("What this step does, e.g. 'Create a product' or 'Click checkout button and verify confirmation'"),
+    expectedStatusCode: z
+        .number()
+        .optional()
+        .describe("Expected HTTP status code, e.g. 200, 201, 404"),
+    requestBody: z
+        .record(z.any())
+        .optional()
+        .describe("Example request body with realistic field values"),
+    responseBody: z
+        .union([z.record(z.any()), z.array(z.any())])
+        .optional()
+        .describe("Key response fields to verify, e.g. { id: 'number', name: 'string', in_stock: 'boolean?' }. An array for a collection/list endpoint that returns a JSON array."),
 });
-export const additionalRecommendationSchema = z.preprocess(stripNullGroundingFields, z.object({
-    testId: z.string().describe("Human-readable kebab-case identifier, e.g. 'integration-products-orders-workflow' or 'e2e-checkout-flow'. Format: '<testType>-<scenario-slug>'. Must be unique within the report."),
-    testType: z.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"),
-    primaryEndpoint: z.string().optional().describe("The focal endpoint this test targets, e.g. 'PATCH /api/v1/orders/{order_id}'. Required for single-step contract tests. For multi-step integration or E2E scenarios, omit — the steps array is the authoritative source of all endpoints involved."),
-    scenarioName: z.string().optional().describe("Proposed scenario name for future generation, e.g. 'products-orders-workflow'. No file exists yet — this is a suggestion only. Omit if not applicable."),
+export const additionalRecommendationSchema = z.preprocess(stripNullGroundingFields, z
+    .object({
+    testId: z
+        .string()
+        .describe("Human-readable kebab-case identifier, e.g. 'integration-products-orders-workflow' or 'e2e-checkout-flow'. Format: '<testType>-<scenario-slug>'. Must be unique within the report."),
+    testType: z
+        .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"),
+    primaryEndpoint: z
+        .string()
+        .optional()
+        .describe("The focal endpoint this test targets, e.g. 'PATCH /api/v1/orders/{order_id}'. Required for single-step contract tests. For multi-step integration or E2E scenarios, omit — the steps array is the authoritative source of all endpoints involved."),
+    scenarioName: z
+        .string()
+        .optional()
+        .describe("Proposed scenario name for future generation, e.g. 'products-orders-workflow'. No file exists yet — this is a suggestion only. Omit if not applicable."),
     // TODO: replace text with max(3) and check for regression
-    steps: z.array(scenarioStepSchema).describe("Ordered sequence of API/UI steps in this test scenario (at most 3). Each step must include method and path so the endpoints are explicit. Omit requestBody and responseBody from steps."),
-    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."),
-    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."),
-    openApiSpec: z.string().optional().describe("Path to OpenAPI/Swagger spec file if available, e.g. 'openapi.yaml'"),
-    backendTrace: z.string().optional().describe("Path to backend trace file if available, e.g. 'tests/skyramp-traces.json'. Used by integration and E2E tests."),
-    frontendTrace: z.string().optional().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"),
+    steps: z
+        .array(scenarioStepSchema)
+        .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."),
+    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."),
+    openApiSpec: z
+        .string()
+        .optional()
+        .describe("Path to OpenAPI/Swagger spec file if available, e.g. 'openapi.yaml'"),
+    backendTrace: z
+        .string()
+        .optional()
+        .describe("Path to backend trace file if available, e.g. 'tests/skyramp-traces.json'. Used by integration and E2E tests."),
+    frontendTrace: z
+        .string()
+        .optional()
+        .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"),
     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."),
-    pageContext: pageContextSchema.optional().describe("UI tests only: page metadata for the test. Lifted from the BlueprintCapture used during grounding."),
-}).superRefine((rec, ctx) => {
+    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."),
+    pageContext: pageContextSchema
+        .optional()
+        .describe("UI tests only: page metadata for the test. Lifted from the BlueprintCapture used during grounding."),
+})
+    .superRefine((rec, ctx) => {
     if (rec.testType === TestType.CONTRACT && !rec.primaryEndpoint) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
@@ -313,7 +588,8 @@ export const additionalRecommendationSchema = z.preprocess(stripNullGroundingFie
                 message: "targetElements is required for testType: 'ui'. Use null when blueprint capture failed (and add '[no-blueprint-data]' to both description and reasoning).",
             });
         }
-        if (Array.isArray(rec.targetElements) && rec.pageContext === undefined) {
+        if (Array.isArray(rec.targetElements) &&
+            rec.pageContext === undefined) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 path: ["pageContext"],
@@ -348,23 +624,33 @@ export const additionalRecommendationSchema = z.preprocess(stripNullGroundingFie
 // TODO(multi-repo maintenance): no `repository` field yet — see readData() TODO below.
 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'"),
+    endpoint: z
+        .string()
+        .describe("HTTP verb and path, e.g. 'GET /api/v1/products'"),
     testFilePath: z
         .string()
-        .refine((p) => path.isAbsolute(p), { message: "testFilePath must be an absolute path" })
+        .refine((p) => path.isAbsolute(p), {
+        message: "testFilePath must be an absolute path",
+    })
         .describe("Absolute path of the test file that was maintained, e.g. '/repo/tests/products_smoke_test.py' — the same path you passed to skyramp_execute_test's testFile param. Consumers should basename this for display."),
-    action: z.nativeEnum(DriftAction).describe("The drift action assigned to this test during maintenance triage."),
+    action: z
+        .nativeEnum(DriftAction)
+        .describe("The drift action assigned to this test during maintenance triage."),
     description: z.string().describe("What was changed and why"),
-    beforeDetails: z.string().describe("One line only — no embedded newlines, no raw HTTP headers or JSON blobs. " +
+    beforeDetails: z
+        .string()
+        .describe("One line only — no embedded newlines, no raw HTTP headers or JSON blobs. " +
         "For passing runs: count and timing, e.g. '4 passed in 15.09s'. " +
         "For failing runs: failure name and one-line root cause, e.g. " +
         "'FAILED test_foo — assert 403 got 200, auth middleware not enforced'. " +
-        "Empty string for VERIFY/IGNORE entries where no before-execution was run."),
-    afterDetails: z.string().describe("One line only — no embedded newlines, no raw HTTP headers or JSON blobs. " +
+        "Pass an empty string when you ran nothing yourself — the server then fills this from the repo suite's own run — and for VERIFY/IGNORE entries where nothing ran at all. Omit the whole entry, never this field."),
+    afterDetails: z
+        .string()
+        .describe("One line only — no embedded newlines, no raw HTTP headers or JSON blobs. " +
         "For passing runs: count and timing, e.g. '5 passed in 10.96s'. " +
         "For failing runs: failure name and one-line root cause, e.g. " +
         "'FAILED test_foo — check_schema fails, order_id=1 has discount from prior PATCH test'. " +
-        "Empty string for VERIFY/IGNORE/DELETE entries where no after-execution was run."),
+        "Pass an empty string when you ran nothing yourself — the server then fills this from the repo suite's own run — and for VERIFY/IGNORE/DELETE entries where nothing ran at all. Omit the whole entry, never this field."),
     // Server-populated from stateFile execution records — never supplied by the LLM.
     beforeStatus: z.nativeEnum(TestExecutionStatus),
     afterStatus: z.nativeEnum(TestExecutionStatus),
@@ -405,7 +691,9 @@ function computeReportMetrics(params) {
     const recommendations = params.additionalRecommendations ?? [];
     const countBy = (items, pred) => items.filter(pred).length;
     const changedMaintenance = (params.testMaintenance ?? []).filter(isMaintenanceChange);
-    const maintenanceRecovered = countBy(changedMaintenance, (m) => (m.beforeStatus === TestExecutionStatus.Fail || m.beforeStatus === TestExecutionStatus.Error) && m.afterStatus === TestExecutionStatus.Pass);
+    const maintenanceRecovered = countBy(changedMaintenance, (m) => (m.beforeStatus === TestExecutionStatus.Fail ||
+        m.beforeStatus === TestExecutionStatus.Error) &&
+        m.afterStatus === TestExecutionStatus.Pass);
     return {
         testsGenerated: String(params.newTestsCreated.length),
         testsMaintained: String(changedMaintenance.length),
@@ -437,17 +725,35 @@ function computeReportMetrics(params) {
  * state: the execution fix-up can restore `<testFile>.raw.bak` over it afterwards
  * by plain `cp`, which this tool never sees. See rederiveReuseOutcome.
  *
- * Non-UI tests, tests the reuse tool never ran for, and specs whose outcome cannot
- * be re-derived all get nothing — which consumers already treat as "no reuse
- * summary". */
-async function attachReuseOutcome(test, outcomes) {
-    if (test.testType !== TestType.UI || !outcomes)
+ * Tests the reuse tool never ran for and specs whose outcome cannot be re-derived
+ * get nothing — which consumers already treat as "no reuse summary" — with one
+ * exception: a test whose generation handed off a reuse step that was never taken
+ * gets `chainSkipped: true` (SKYR-4220), the one claim that is exactly about the
+ * reuse tool NOT having run. Applies to every test type: UI tests carry the POM
+ * fields, API tests the shared-helper ones. */
+async function attachReuseOutcome(test, outcomes, handOffs) {
+    // POM records describe browser specs; a basename collision with an API test's
+    // fileName must not attach them there. A utils-path record is attachable anywhere.
+    const record = outcomes?.[path.basename(test.fileName)];
+    // A utils record carries the test type its verify ran under: a mismatch is a
+    // basename collision with another test, not this row's outcome.
+    const typeMatches = !record?.utils?.testType || record.utils.testType === test.testType;
+    const found = record && typeMatches && (test.testType === TestType.UI || record.utils)
+        ? record
+        : undefined;
+    const derived = found ? await rederiveReuseOutcome(found) : undefined;
+    // The RAW record: a colliding record of any kind means reuse ran for this basename,
+    // and the chain claim must not be made on the filtered view.
+    const chainSkipped = await reuseChainSkipped(test.fileName, test.testType, record, handOffs);
+    const reuse = derived || chainSkipped
+        ? { ...(derived ?? {}), ...(chainSkipped ? { chainSkipped } : {}) }
+        : undefined;
+    if (!reuse)
         return test;
-    const found = outcomes[path.basename(test.fileName)];
-    if (!found)
-        return test;
-    const reuse = await rederiveReuseOutcome(found);
-    return reuse ? { ...test, reuse } : test;
+    // A record that re-derives to nothing (e.g. a utils path that wrote no file) must
+    // not attach an empty object — consumers treat presence as "reuse ran".
+    const hasContent = Object.values(reuse).some((v) => v !== undefined);
+    return hasContent ? { ...test, reuse } : test;
 }
 /**
  * Attach the video recorded for this execution, matched by the row's testFilePath
@@ -461,7 +767,10 @@ async function attachReuseOutcome(test, outcomes) {
  * consumers already treat as "no recording for this test".
  */
 function attachVideoPath(row, videos) {
-    return { ...row, videoPath: videos?.[path.basename(row.testFilePath)]?.videoPath };
+    return {
+        ...row,
+        videoPath: videos?.[path.basename(row.testFilePath)]?.videoPath,
+    };
 }
 function deduplicateById(items) {
     const seen = new Set();
@@ -518,8 +827,8 @@ export function registerSubmitReportTool(server) {
                 .optional()
                 .default([])
                 .describe("Actionable follow-ups for the PR author. Each entry must be a single-line string (no embedded newlines). " +
-                "Include a next step for every critical/high severity issue in issuesFound. No next steps for low-severity issues. " +
-                "Also include a next step for every external test (Playwright, Cypress, RTL) assigned REGENERATE or DELETE in testMaintenance — the developer must act on these manually since they cannot be auto-applied (e.g. 'Regenerate frontend/tests/cart_pom.spec.ts — CartLine structure changed, all selectors need re-recording' or 'Delete frontend/tests/homepage.spec.ts — /cart route removed'). " +
+                "Do NOT add a next step that repeats an entry in issuesFound. The report renders every issue with its description and source location, and the consumer also posts an inline review comment on the cited line, so a repeated next step shows the same sentence to the author three times. Add a next step for an issue only when it names an action the issue text does not already state. " +
+                "Include a next step for every external test (Playwright, Cypress, RTL) assigned REGENERATE or DELETE in testMaintenance — the developer must act on these manually since they cannot be auto-applied (e.g. 'Regenerate frontend/tests/cart_pom.spec.ts — CartLine structure changed, all selectors need re-recording' or 'Delete frontend/tests/homepage.spec.ts — /cart route removed'). " +
                 "If multiple tests fail with 404 or connection refused: suggest checking targetSetupCommand/targetReadyCheckCommand. " +
                 "If 401/403 on auth endpoints: suggest authTokenCommand. " +
                 "When referencing code, use file name and relevant code pattern — no line numbers unless certain."),
@@ -590,31 +899,62 @@ export function registerSubmitReportTool(server) {
                 { path: "businessCaseAnalysis", text: params.businessCaseAnalysis },
             ];
             params.newTestsCreated.forEach((t, i) => {
-                textFields.push({ path: `newTestsCreated[${i}].description`, text: t.description });
-                textFields.push({ path: `newTestsCreated[${i}].reasoning`, text: t.reasoning });
+                textFields.push({
+                    path: `newTestsCreated[${i}].description`,
+                    text: t.description,
+                });
+                textFields.push({
+                    path: `newTestsCreated[${i}].reasoning`,
+                    text: t.reasoning,
+                });
             });
             (params.additionalRecommendations ?? []).forEach((r, i) => {
-                textFields.push({ path: `additionalRecommendations[${i}].description`, text: r.description });
-                textFields.push({ path: `additionalRecommendations[${i}].reasoning`, text: r.reasoning });
+                textFields.push({
+                    path: `additionalRecommendations[${i}].description`,
+                    text: r.description,
+                });
+                textFields.push({
+                    path: `additionalRecommendations[${i}].reasoning`,
+                    text: r.reasoning,
+                });
                 r.steps.forEach((s, j) => {
-                    textFields.push({ path: `additionalRecommendations[${i}].steps[${j}].description`, text: s.description });
+                    textFields.push({
+                        path: `additionalRecommendations[${i}].steps[${j}].description`,
+                        text: s.description,
+                    });
                 });
             });
             params.testResults.forEach((t, i) => {
-                textFields.push({ path: `testResults[${i}].details`, text: t.details });
+                textFields.push({
+                    path: `testResults[${i}].details`,
+                    text: t.details,
+                });
             });
             params.issuesFound.forEach((f, i) => {
-                textFields.push({ path: `issuesFound[${i}].description`, text: f.description });
+                textFields.push({
+                    path: `issuesFound[${i}].description`,
+                    text: f.description,
+                });
             });
             (params.nextSteps ?? []).forEach((s, i) => {
                 textFields.push({ path: `nextSteps[${i}]`, text: s });
             });
             (params.testMaintenanceDetails ?? []).forEach((d, i) => {
-                textFields.push({ path: `testMaintenanceDetails[${i}].beforeDetails`, text: d.beforeDetails });
-                textFields.push({ path: `testMaintenanceDetails[${i}].afterDetails`, text: d.afterDetails });
+                textFields.push({
+                    path: `testMaintenanceDetails[${i}].beforeDetails`,
+                    text: d.beforeDetails,
+                });
+                textFields.push({
+                    path: `testMaintenanceDetails[${i}].afterDetails`,
+                    text: d.afterDetails,
+                });
             });
-            if (params.commitMessage && params.commitMessage !== DEFAULT_COMMIT_MESSAGE) {
-                textFields.push({ path: "commitMessage", text: params.commitMessage });
+            if (params.commitMessage &&
+                params.commitMessage !== DEFAULT_COMMIT_MESSAGE) {
+                textFields.push({
+                    path: "commitMessage",
+                    text: params.commitMessage,
+                });
             }
             const languageViolations = findLanguageViolations(textFields, reportLanguage);
             if (languageViolations.length > 0) {
@@ -637,7 +977,9 @@ export function registerSubmitReportTool(server) {
             }
         }
         const dedupedNewTests = deduplicateById([...params.newTestsCreated]);
-        const dedupedRecommendations = deduplicateById([...(params.additionalRecommendations ?? [])]);
+        const dedupedRecommendations = deduplicateById([
+            ...(params.additionalRecommendations ?? []),
+        ]);
         const stateManager = StateManager.fromStatePath(params.stateFile);
         let stateData;
         try {
@@ -658,7 +1000,8 @@ export function registerSubmitReportTool(server) {
         // than silently reporting an empty testMaintenance section indistinguishable from a
         // real "nothing to do". With zero existing tests there was nothing to lose, so
         // undefined is safe there — no round-trip through skyramp_actions required.
-        if (stateData.maintenanceVerdicts === undefined && (stateData.existingTests?.length ?? 0) > 0) {
+        if (stateData.maintenanceVerdicts === undefined &&
+            (stateData.existingTests?.length ?? 0) > 0) {
             errorResult = toolError("stateFile has existingTests but no maintenanceVerdicts — skyramp_actions was not called for this run. " +
                 "Call skyramp_actions (with recommendations: [] if no existing tests needed action) before skyramp_submit_report.");
             return errorResult;
@@ -682,19 +1025,24 @@ export function registerSubmitReportTool(server) {
                     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 })));
+                return !(names.length > 0 ? names : [undefined]).some((scenarioName) => endpoints.some(({ method, path }) => matchesApprovedPlan(approvedPlan, {
+                    scenarioName,
+                    testType: t.testType,
+                    method,
+                    path,
+                })));
             });
             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("; ")
+                    ? // 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: ` +
@@ -745,21 +1093,62 @@ export function registerSubmitReportTool(server) {
                 const recorded = stateData.existingTests?.find((t) => testFileMatches(t.testFile, m.testFilePath));
                 const detail = params.testMaintenanceDetails?.find((d) => d.testFilePath === m.testFilePath);
                 const displayName = path.basename(m.testFilePath);
-                const defaultBeforeStatus = MAINTENANCE_CHANGE_ACTIONS.has(m.action) ? TestExecutionStatus.Unknown : TestExecutionStatus.Skipped;
-                const defaultAfterStatus = m.action === DriftAction.Delete ? TestExecutionStatus.Skipped
-                    : MAINTENANCE_CHANGE_ACTIONS.has(m.action) ? TestExecutionStatus.Unknown : TestExecutionStatus.Skipped;
-                const beforeStatus = recorded?.executionBefore?.status ?? defaultBeforeStatus;
-                const afterStatus = recorded?.executionAfter?.status ?? defaultAfterStatus;
+                const defaultBeforeStatus = MAINTENANCE_CHANGE_ACTIONS.has(m.action)
+                    ? TestExecutionStatus.Unknown
+                    : TestExecutionStatus.Skipped;
+                const defaultAfterStatus = m.action === DriftAction.Delete
+                    ? TestExecutionStatus.Skipped
+                    : MAINTENANCE_CHANGE_ACTIONS.has(m.action)
+                        ? TestExecutionStatus.Unknown
+                        : TestExecutionStatus.Skipped;
+                // A suite run answers only for a row whose default is Unknown. VERIFY and
+                // IGNORE are Skipped by decision, not for want of a result, and testbot
+                // drops both from the rendered table.
+                const external = externalStatusesFor(stateData.externalTestResults, m.testFilePath);
+                const beforeStatus = recorded?.executionBefore?.status ??
+                    (defaultBeforeStatus === TestExecutionStatus.Unknown
+                        ? external.before
+                        : undefined) ??
+                    defaultBeforeStatus;
+                const afterStatus = recorded?.executionAfter?.status ??
+                    (defaultAfterStatus === TestExecutionStatus.Unknown
+                        ? external.after
+                        : undefined) ??
+                    defaultAfterStatus;
                 // Trim before checking — a whitespace-only string is semantically blank and
                 // must not satisfy the "drafted a summary" requirement.
-                const beforeDetails = detail?.beforeDetails?.trim() ?? "";
-                const afterDetails = detail?.afterDetails?.trim() ?? "";
+                // The agent's drafted summary wins; otherwise a status that came from
+                // the suite run carries the run's own line, so the rendered cell is
+                // never a bare verdict with nothing behind it.
+                //
+                // Only when there is NO recorded execution. A file the agent ran itself
+                // owes a drafted summary, and filling it here would satisfy the check
+                // below on the agent's behalf whenever the two statuses happened to
+                // agree — silently dropping the requirement.
+                //
+                // And only where the STATUS came from the suite too. A VERIFY or DELETE
+                // row keeps its Skipped default, so a line saying "1 passed in the repo's
+                // own suite" beside it contradicts the very cell it annotates.
+                const beforeFromSuite = defaultBeforeStatus === TestExecutionStatus.Unknown &&
+                    !recorded?.executionBefore;
+                const afterFromSuite = defaultAfterStatus === TestExecutionStatus.Unknown &&
+                    !recorded?.executionAfter;
+                const beforeDetails = detail?.beforeDetails?.trim() ||
+                    (beforeFromSuite ? (external.beforeDetail ?? "") : "");
+                const afterDetails = detail?.afterDetails?.trim() ||
+                    (afterFromSuite ? (external.afterDetail ?? "") : "");
                 if (recorded?.executionBefore && !beforeDetails)
                     missingDetails.push(`${displayName} (beforeDetails)`);
                 if (recorded?.executionAfter && !afterDetails)
                     missingDetails.push(`${displayName} (afterDetails)`);
                 logger.info(`${displayName}: before=${beforeStatus} after=${afterStatus}`);
-                return { ...m, beforeDetails, afterDetails, beforeStatus, afterStatus };
+                return {
+                    ...m,
+                    beforeDetails,
+                    afterDetails,
+                    beforeStatus,
+                    afterStatus,
+                };
             });
         }
         if (missingDetails.length > 0) {
@@ -796,7 +1185,7 @@ export function registerSubmitReportTool(server) {
                             ...Object.values(fullState?.relatedRepos ?? {}).map((section) => section.repositoryPath),
                         ])),
                     ];
-                    const unbacked = findUnbackedClaims({
+                    const unbacked = findUnchangedFileClaims({
                         repoRoot,
                         changedFiles,
                         newTests: dedupedNewTests,
@@ -815,7 +1204,10 @@ export function registerSubmitReportTool(server) {
                         // SKYR-4129. Do NOT offer re-running skyramp_actions to restate the verdict:
                         // this branch only fires when the edit is genuinely absent, so rewriting the
                         // record to match that would be the tamper path, not the fix.
-                        const changedList = changedFiles.slice(0, 20).map((f) => `  - ${f}`).join("\n");
+                        const changedList = changedFiles
+                            .slice(0, 20)
+                            .map((f) => `  - ${f}`)
+                            .join("\n");
                         errorResult = toolError(`${unbacked.length} report claim(s) are not backed by any change in the working tree — ` +
                             `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` +
@@ -832,12 +1224,36 @@ export function registerSubmitReportTool(server) {
                 }
             }
         }
+        // Validated against the tool INPUT only, never the state file (a state-file
+        // guard here previously caused a rejection loop). Only entries carrying a
+        // citation are checked, so an ordinary run pays no extra cost.
+        // `repository` is normalized BEFORE the check so the attribution the check
+        // reconciles is the one the report ships, and so the stamp below survives
+        // into the written file — this array is what the report is built from.
+        const issuesFound = params.issuesFound.map(normalizeRepository);
+        if (issuesFound.some((issue) => issue.sourceFile?.trim())) {
+            const citations = await findInvalidSourceCitations({
+                checkouts: await stateManager.listRepoCheckouts(),
+                issues: issuesFound,
+            });
+            if (citations.invalid.length > 0) {
+                errorResult = toolError(citations.invalid.join("\n"));
+                return errorResult;
+            }
+            // The checkout the citation resolved in owns the finding, 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) => {
+                if (repo)
+                    issuesFound[i] = { ...issuesFound[i], repository: repo };
+            });
+        }
         // Strip generation-artifact fields from newTestsCreated before writing.
         // scenarioFile, traceFile, frontendTrace are internal paths used during
         // 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).
-        const sanitizedNewTests = await Promise.all(dedupedNewTests.map(({ scenarioFile: _sf, traceFile: _tf, frontendTrace: _ft, ...rest }) => attachReuseOutcome(normalizeRepository(rest), stateData.reuseOutcomes)));
+        const sanitizedNewTests = await Promise.all(dedupedNewTests.map(({ scenarioFile: _sf, traceFile: _tf, frontendTrace: _ft, ...rest }) => attachReuseOutcome(normalizeRepository(rest), stateData.reuseOutcomes, stateData.reuseHandOffs)));
         const report = {
             businessCaseAnalysis: params.businessCaseAnalysis,
             newTestsCreated: sanitizedNewTests,
@@ -858,9 +1274,10 @@ export function registerSubmitReportTool(server) {
                 const { testFilePath: _tfp, ...wire } = attachVideoPath(normalizeRepository(row), stateData.executionVideos);
                 return wire;
             }),
-            issuesFound: params.issuesFound.map(normalizeRepository),
+            issuesFound,
             nextSteps: params.nextSteps ?? [],
-            commitMessage: (params.commitMessage ?? "").replace(/[\r\n]+/g, " ").trim() || DEFAULT_COMMIT_MESSAGE,
+            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