@skyramp/mcp 0.4.1 → 0.4.2-rc.2

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

@@ -1,17 +1,24 @@
 import { z } from "zod";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
-import { buildPathParamGuidance, } from "../test-recommendation/recommendationSections.js";
+import { buildPathParamGuidance } from "../test-recommendation/recommendationSections.js";
 import { setReportLanguage } from "../../utils/reportLanguage.js";
 import { setPlanOnlyMode } from "../../utils/planOnlyMode.js";
+import { parseMaxFixAttemptsArg, resolveMaxFixAttempts, setMaxFixAttempts, } from "../../utils/fixAttempts.js";
+import { setPrimaryRepository } from "../../utils/AnalysisStateManager.js";
 import { recordPullRequestText } from "../../recommendation/pullRequestText.js";
 import { AUTH_MIDDLEWARE_PATTERNS_STR } from "../../utils/workspaceAuth.js";
 import { TASK_ANALYZE_MAINTAIN, TASK_GENERATE, TASK_SUBMIT, TESTBOT_TASK1_MAINTAIN_LABELS, TESTBOT_TASK1_MULTIREPO_LABELS, TESTBOT_TASK1_STEP_LABELS, orderedLabels, stepSubRef, taskRef, } from "../test-recommendation/recommendationShared.js";
 import { getTraceRecordingPromptText } from "../../playwright/traceRecordingPrompt.js";
 import { isContractConsumerModeEnabled, isPomReuseEnabled, isUtilsReuseEnabled, isSkillsLoaded, } from "../../utils/featureFlags.js";
 import { fixErrorsInstruction } from "../../skills/fixTestImportErrorsSkill.js";
+import { runTestCall } from "../../skills/runTestSkill.js";
+import { alignAssertionsStep } from "../../skills/validateAssertionAlignmentSkill.js";
+import { ASSERTION_ENHANCEABLE_TEST_TYPES } from "../../types/TestTypes.js";
+import { enhanceAssertionsCall } from "../../skills/enhanceAssertionsSkill.js";
 import { resolveServiceDetailsRef } from "../../utils/utils.js";
 import { section, sectionBody } from "../promptAssets.js";
+import { CODE_REUSE_GENERATION_CLAUSE } from "../reuse-hand-off.js";
 import { readPromptAsset } from "../promptAssets.js";
 import { fillPlaceholders } from "../../recommendation/verifierContracts.js";
 import { buildServiceContext, readWorkspaceServices } from "../prompt-utils.js";
@@ -118,28 +125,31 @@ export const EXEC_FAIL = orderedLabels([
     "INFRA_RETRY",
     "REPORT_FAIL",
 ]);
+function capitalize(text) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}
 // The UI enhance entry of the post-generation list. On the modularize-first UI
 // flow the enhance call is the first sub-step of the generation result's chain — but
 // that chain exists only for a TS/JS UI generation with enhanceAssertions on,
 // which this prompt cannot see per call. So the step keeps the call and lets
 // the agent skip it only when it already made it for that file.
 const UI_ENHANCE_STEP = UI_UTILS_REUSE
-    ? `Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated UI test file, \`testType: "ui"\`, and \`enhanceType: "generation"\`, and apply every instruction returned to that file — UNLESS you already called it for this file as the first sub-step of step ${POSTGEN.UI_CODE_REUSE}'s chain, in which case skip it (never enhance the same file twice; never leave a generated UI test un-enhanced). The guidance below on which assertions to add applies to whichever call enhances the file.`
-    : `Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated UI test file, \`testType: "ui"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.`;
+    ? `${capitalize(enhanceAssertionsCall("ui", "generated UI test file"))} — UNLESS you already did it for this file as the first sub-step of step ${POSTGEN.UI_CODE_REUSE}'s chain, in which case skip it (never enhance the same file twice; never leave a generated UI test un-enhanced). The guidance below on which assertions to add applies to whichever call enhances the file.`
+    : `${capitalize(enhanceAssertionsCall("ui", "generated UI test file"))}.`;
 // Post-generation code-reuse step for UI tests. The POM catalog, the `verify: true`
 // loop and the `.raw.bak` restore only exist on the POM-aware path — when that path
 // is flagged off, `skyramp_reuse_code` returns the SkyrampUtils workflow instead, so
 // the agent must not be sent looking for artifacts nothing produces.
 const UI_CODE_REUSE_STEP = POM_REUSE_ENABLED
-    ? `${POSTGEN.UI_CODE_REUSE}. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result directs you to call \`skyramp_reuse_code\` — do this BEFORE \`skyramp_enhance_assertions\`. Two outcomes: (1) a response starting "No reusable POM layer detected" — this is a normal outcome, continue immediately (do NOT retry); (2) a refactoring workflow — follow it to completion INCLUDING its verification loop (\`skyramp_reuse_code\` with \`verify: true\`), finish only when it reports PASSED. If a reused test later fails execution and the failure points at a substituted POM call, restore the saved \`<testFile>.raw.bak\` over the test file and re-run — do NOT hand-edit the customer's POM methods (this re-run counts toward the 2-attempt execution cap — prefer this restore over the generic timeout fix-up when the failing locator came from a POM substitution). **Cleanup before reporting:** \`.raw.bak\` files are internal scratch — after ALL test executions are complete (pass or fail) and before calling \`skyramp_submit_report\`, delete every \`*.raw.bak\` you created so they are not committed to the customer-facing branch. The \`skyramp-pom-catalog.md\` is NOT scratch — leave it in place (later runs reuse it).`
+    ? `${POSTGEN.UI_CODE_REUSE}. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result directs you to call \`skyramp_reuse_code\` — do this BEFORE enhancing assertions. Two outcomes: (1) a response starting "No reusable POM layer detected" — this is a normal outcome, continue immediately (do NOT retry); (2) a refactoring workflow — follow it to completion INCLUDING its verification loop (\`skyramp_reuse_code\` with \`verify: true\`), finish only when it reports PASSED. If a reused test later fails execution and the failure points at a substituted POM call, restore the saved \`<testFile>.raw.bak\` over the test file and re-run — do NOT hand-edit the customer's POM methods (this re-run counts toward the per-file execution attempt cap; when the budget allows no re-run, restore the file for delivery and report the failure instead of executing again — prefer this restore over the generic timeout fix-up when the failing locator came from a POM substitution). **Cleanup before reporting:** \`.raw.bak\` files are internal scratch — after ALL test executions are complete (pass or fail) and before calling \`skyramp_submit_report\`, delete every \`*.raw.bak\` you created so they are not committed to the customer-facing branch. The \`skyramp-pom-catalog.md\` is NOT scratch — leave it in place (later runs reuse it).`
     : UI_UTILS_REUSE
-        ? `${POSTGEN.UI_CODE_REUSE}. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result carries three CRITICAL NEXT STEPS — \`skyramp_enhance_assertions\` (on the freshly generated file, while its selectors are still inline), then \`skyramp_modularization\`, then \`skyramp_reuse_code\` — with the exact arguments for each. Do all three, in that order and to completion, for EVERY generated UI test file — the enhance sub-step is that file's step ${POSTGEN.UI_ENHANCE} below (do not call \`skyramp_enhance_assertions\` a second time for the same file, and do not skip it for later files). Sibling tests offering nothing to reuse is a normal outcome, but the reuse steps still move this test's own helpers into the shared utils file and import them back, so the test file IS expected to change. Then continue (do NOT retry).`
-        : `${POSTGEN.UI_CODE_REUSE}. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result directs you to call \`skyramp_reuse_code\` — do this BEFORE \`skyramp_enhance_assertions\`. Follow the returned steps exactly. If it finds no existing helper functions to reuse, that is a normal outcome — leave the test file unchanged and continue immediately (do NOT retry).`;
+        ? `${POSTGEN.UI_CODE_REUSE}. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result carries three CRITICAL NEXT STEPS — \`skyramp_enhance_assertions\` (on the freshly generated file, while its selectors are still inline), then \`skyramp_modularization\`, then \`skyramp_reuse_code\` — with the exact arguments for each. Do all three, in that order and to completion, for EVERY generated UI test file — the enhance sub-step is that file's step ${POSTGEN.UI_ENHANCE} below (do not call \`skyramp_enhance_assertions\` a second time for the same file, and do not skip it for later files). Sibling tests offering nothing to reuse is a normal outcome, but the reuse steps still move this test's own helpers into the shared utils file — or, where the repository already has a browser helper module of its own, call its helpers and add to that module what it lacks — and import them back, so the test file IS expected to change. Then continue (do NOT retry).`
+        : `${POSTGEN.UI_CODE_REUSE}. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result directs you to call \`skyramp_reuse_code\` — do this BEFORE enhancing assertions. Follow the returned steps exactly. If it finds no existing helper functions to reuse, that is a normal outcome — leave the test file unchanged and continue immediately (do NOT retry).`;
 // Generation-call clause for the integration pipeline: only ask for codeReuse when
 // utils reuse is enabled — with the flag off, integration generation behaves exactly
 // as it did before the feature existed (no file-rewriting post-steps).
 const INTEGRATION_CODE_REUSE_GEN_CLAUSE = UTILS_REUSE_ENABLED
-    ? `, setting \`modularizeCode: false\` and \`codeReuse: true\` (TypeScript/JavaScript/Python — leave \`codeReuse\` unset for Java: cross-file helpers do not compile in the test executor)`
+    ? CODE_REUSE_GENERATION_CLAUSE
     : ``;
 // The post-generation modularize → reuse steps are NOT listed here: the
 // generation tool's own result emits them (see TestGenerationService) when called
@@ -176,8 +186,40 @@ export function parseRelatedRepositories(raw) {
         return undefined;
     }
 }
+// The UI-timeout diagnosis is the same whatever the budget: read the output,
+// rule on the route, rule on a positional locator before the failing step. Only
+// the "then retry" part depends on the cap, so the cap-of-one variant of the
+// fix-up section shares these and drops the retry.
+const UI_TIMEOUT_READ_OUTPUT = `If a generated UI test fails with a timeout waiting for an element after navigation (e.g. \`TimeoutError\` on \`getByTestId\` or \`locator\`), first read the test output \`skyramp_execute_test\` returned — its console lines and the URL the page ended on.`;
+const UI_TIMEOUT_ROUTE_BULLET = `- **The route is broken** when that output reports a failed load of the page the test navigated to, or when the page ended on a route that is neither the login page nor another spelling of the URL it navigated to. Report \`status: "Fail"\` and name in the details both the route the test asked for and the URL the page reached. Do not change the waits.
+`;
+// The two waits a late-element timeout gets. Rendered at every cap: at one the
+// agent edits the delivered file and reports; above one it re-runs.
+const UI_TIMEOUT_WAIT_STEPS = `1. After the login submit, add \`await page.waitForURL((u) => !u.pathname.startsWith('/login'));\`. After every other \`page.goto()\`, wait for the first element the next step uses with \`await expect(locator).toBeVisible();\`. Do not add \`waitForLoadState('networkidle')\`.
+2. Add \`await page.locator('[data-testid="some-element"]').waitFor({ state: 'visible', timeout: 10000 });\` for the specific element the test needs.
+Do NOT use \`page.waitForTimeout()\` with fixed delays.`;
+const UI_TIMEOUT_POSITIONAL_BULLET = `- **The step before the failing one used a positional locator** — \`.nth(n)\`, \`.first()\`, \`.last()\`, or a bare tag chain such as \`locator("div").nth(80).locator("span")\` — and the element that timed out is an option, panel or message that step should have opened. A positional click that lands on the wrong element does not fail; the error surfaces one line late. But do not convict the locator on that pattern alone — the following step can be at fault by itself (the PR renamed or removed the option it waits for, the panel renders late, the route is broken). Establish which before editing, with the app still running: open the page with \`browser_snapshot\`/\`browser_blueprint\` and see what the positional path resolves to now, and check whether the diff added or removed siblings ahead of the recorded control.
+  - If it now resolves to a different control than the one recorded: the locator is the cause. Re-scope it to the control's labelled container or its role and name — \`getByRole('group', { name: 'Protocols' }).getByRole('combobox')\`, or a container test id narrowed to the control — never bump the index or add \`.first()\`. If the page offers no stable anchor for it, report the test as \`status: "Fail"\` naming the positional locator as the cause.
+  - If it still resolves to the recorded control: the failing step is at fault. Handle it under the other branches here (a broken route, a late element) or as maintenance of what the PR changed (a renamed label, a removed option) — do not spend an attempt on the locator. Making the positional locator stable in the same edit is good hygiene, not the fix.
+`;
 export function getTestbotPrompt(opts) {
     const { prTitle, prDescription, repositoryPath, baseBranch, prNumber, userPrompt, services, uiCredentials, testsRepoDir, relatedRepositories, primaryRepo, planOnly = false, language, } = opts;
+    // The per-file execution attempt cap for the fix-and-rerun loop (SKYR-4460):
+    // the URI/prompt argument, else SKYRAMP_MAX_FIX_ATTEMPTS, else the default.
+    // Recorded for the run so skyramp_execute_test enforces the number this
+    // prompt states, not a second reading of the environment.
+    const maxFixAttempts = resolveMaxFixAttempts(opts.maxFixAttempts);
+    setMaxFixAttempts(maxFixAttempts);
+    const fixReruns = maxFixAttempts - 1;
+    const fixBudgetClause = fixReruns === 0
+        ? `the first run only — this run allows NO fix-and-rerun iteration`
+        : `the first run plus at most ${fixReruns} fix-and-rerun iteration${fixReruns === 1 ? "" : "s"}`;
+    // Rendering the prompt is where the run declares its primary checkout — the
+    // action passes its workingDirectory and its slug here. Write order must not
+    // decide it (SKYR-4333). Set, not set-if-unset: one server can render a second
+    // run for a different checkout, and keeping the first would route the second
+    // one as a related repository.
+    setPrimaryRepository({ repositoryPath, repo: primaryRepo });
     // Kept in the process for the plan tool, which is registered on this server.
     recordPullRequestText(prTitle, prDescription);
     // The legacy count arguments are DECLARED NOWHERE, so zod strips them and their
@@ -206,32 +248,40 @@ export function getTestbotPrompt(opts) {
     const analyzeBlock = fillPlaceholders(sectionBody(TESTBOT_TASK1_MD, "## Analyze the change"), {
         analyzeStep: TASK1.ANALYZE,
         repositoryPath,
+        primaryRepo,
         analyzeCountArgs,
         baseBranchArg: baseBranch ? `, \`baseBranch\`: "${baseBranch}"` : "",
         prNumberArg: prNumber ? `, \`prNumber\`: ${prNumber}` : "",
-        testsRepoDirArg: testsRepoDir ? `, \`testsRepoDir\`: "${testsRepoDir}"` : "",
-        uiCredentialsNote: uiCredentials ? ` ${sectionBody(TESTBOT_TASK1_MD, "## Log in before capturing")}` : "",
+        testsRepoDirArg: testsRepoDir
+            ? `, \`testsRepoDir\`: "${testsRepoDir}"`
+            : "",
+        uiCredentialsNote: uiCredentials
+            ? ` ${sectionBody(TESTBOT_TASK1_MD, "## Log in before capturing")}`
+            : "",
         submitTask: taskRef(TASK_SUBMIT),
         generateTask: taskRef(TASK_GENERATE),
-    }) + (hasRelatedRepos
-        ? `\n\n   ${fillPlaceholders(sectionBody(TESTBOT_TASK1_MD, "## Multi-repo context"), {
-            analyzeStep: TASK1.ANALYZE,
-            registerServicesStep: MULTIREPO.REGISTER_SERVICES,
-            analyzeRepoStep: MULTIREPO.ANALYZE_REPO,
-            onFailureStep: MULTIREPO.ON_FAILURE,
-            registerServicesRef: stepSubRef(TASK1.ANALYZE, MULTIREPO.REGISTER_SERVICES),
-            relatedRepoCount: relatedRepositories.length,
-            repoWord: relatedRepositories.length === 1 ? "repository" : "repositories",
-            callWord: relatedRepositories.length === 1 ? "call" : "calls",
-            repositoryPath,
-            primaryRepo: primaryRepo || "<the primary repo's owner/repo>",
-            generateTask: taskRef(TASK_GENERATE),
-            testRepoExclusionNote: testsRepoDir
-                ? " — NOT in the configured test repo, even though generated test files are delivered there"
-                : "",
-            testRepoExclusionShort: testsRepoDir ? " and NOT the test repo" : "",
-        })}`
-        : "\n");
+    }) +
+        (hasRelatedRepos
+            ? `\n\n   ${fillPlaceholders(sectionBody(TESTBOT_TASK1_MD, "## Multi-repo context"), {
+                analyzeStep: TASK1.ANALYZE,
+                registerServicesStep: MULTIREPO.REGISTER_SERVICES,
+                analyzeRepoStep: MULTIREPO.ANALYZE_REPO,
+                onFailureStep: MULTIREPO.ON_FAILURE,
+                registerServicesRef: stepSubRef(TASK1.ANALYZE, MULTIREPO.REGISTER_SERVICES),
+                relatedRepoCount: relatedRepositories.length,
+                repoWord: relatedRepositories.length === 1 ? "repository" : "repositories",
+                callWord: relatedRepositories.length === 1 ? "call" : "calls",
+                repositoryPath,
+                primaryRepo,
+                generateTask: taskRef(TASK_GENERATE),
+                testRepoExclusionNote: testsRepoDir
+                    ? " — NOT in the configured test repo, even though generated test files are delivered there"
+                    : "",
+                testRepoExclusionShort: testsRepoDir
+                    ? " and NOT the test repo"
+                    : "",
+            })}`
+            : "\n");
     // SKYR-4023: user-facing report language. English display names improve
     // instruction-following vs bare codes; Intl.DisplayNames (Node >=18) names any
     // code correctly, falling back to the raw code only if it can't be resolved.
@@ -258,16 +308,19 @@ export function getTestbotPrompt(opts) {
 
 `;
     }
-    // The Task 1 maintenance baseline sub-step branches in plan-only eval runs (SKYR-3879
-    // plan-only lane): the SUT is not running, so the pre-edit baseline
-    // execution is replaced by static-analysis-only verdicts. Defined before
-    // task1Section, which interpolates it.
+    // The Task 1 maintenance sub-steps that run tests branch in plan-only eval runs
+    // (SKYR-3879 plan-only lane): the SUT is not running, so those runs are replaced
+    // by static-analysis-only verdicts. Defined before task1Section, which
+    // interpolates them.
     let maintenanceBeforeExecStep;
+    let verifyExternalStep;
     if (planOnly) {
+        verifyExternalStep = `   ${MAINTAIN.VERIFY_EXTERNAL}. Plan-only run: do not run the external tests you edited.`;
         maintenanceBeforeExecStep = `   ${MAINTAIN.BASELINE}. Plan-only run: skip the pre-edit baseline execution — the application is not running. Record every maintenance verdict from static drift analysis alone; execution statuses simply remain unrecorded.`;
     }
     else {
-        maintenanceBeforeExecStep = `   ${MAINTAIN.BASELINE}. Call \`skyramp_execute_test\` with \`phase: "before"\` and \`stateFile\` for every UPDATE/REGENERATE/DELETE test. Exclude tests marked \`[external]\` — those are baselined in ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.CONFIRM_EXTERNAL)} via \`skyramp_run_existing_tests\`. Run them sequentially, not in parallel. This captures the pre-edit baseline — do not skip even if you expect the test to fail. Never pass \`rebaselineSnapshots\` here: a \`Screenshot comparison failed\` on this run is the evidence that a visual baseline is stale, and the refresh belongs to the final execution.`;
+        verifyExternalStep = `   ${MAINTAIN.VERIFY_EXTERNAL}. Run the external tests you edited again. Do this step right after ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.APPLY_ACTIONS)}. It applies to each \`[external]\` test file that you edited in ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.APPLY_ACTIONS)} and that ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.BASELINE)} ran. Run each such file with \`skyramp_execute_test\`, \`phase: "after"\` and \`stateFile\`, and use the same command as in ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.BASELINE)}. Record each result as the file's \`afterStatus\`. The final execution excludes \`[external]\` files, so this step is where they get their after-run. If no file applies, say so in your report. If a file still fails, report it — do not run it again.`;
+        maintenanceBeforeExecStep = `   ${MAINTAIN.BASELINE}. Call \`skyramp_execute_test\` with \`phase: "before"\` and \`stateFile\` for every Skyramp test you will change, and for every test the repository owns that you will mark UPDATE: ${runTestCall()}. Run them one at a time, not in parallel. Run the command even when you expect the runner or a package to be missing: the failure output is what names what is missing, and a check you make before the run reaches no repair. On this run repair the environment only — install what is missing and run the file again — and never edit the test file, because the result of the file as the repository wrote it IS the baseline. This captures the pre-edit baseline — do not skip it even when you expect the test to fail. \`skyramp_actions\` refuses an UPDATE of the repository's own test until that test has this run. Nothing else owes one: a VERIFY changes no file, and a REGENERATE or a DELETE of the repository's own test is a recommendation you report rather than apply. Never pass \`rebaselineSnapshots\` on this run: a \`Screenshot comparison failed\` here is the evidence that a visual baseline is stale, and the refresh belongs to the final execution.`;
     }
     // For follow-up requests: emit the @skyramp-testbot header + guardrails, both stop-early.
     // For first-run prompts: emit the full Task 1 analysis + maintenance section.
@@ -297,8 +350,6 @@ ${analyzeBlock}
 
 ${TASK1.MAINTAIN}. **Maintain existing tests:**
 
-   ${MAINTAIN.CONFIRM_EXTERNAL}. Confirm external-test breakage before assessment. If any service in \`${repositoryPath}/.skyramp/workspace.yml\` declares test-env config (\`runtimeDetails.test*\`), call \`skyramp_run_existing_tests\` (\`mode: "confirm"\`, \`stateFile\`) on the tests \`skyramp_analyze_changes\` marked \`[external]\` — the repo's OWN suite, not the Skyramp-generated tests — before \`skyramp_analyze_test_health\`, so the run-confirmed failures fold into its assessment. Do NOT read the \`[external]\` test files to *guess* the change's impact — RUN them with \`skyramp_run_existing_tests\` to get real pass/fail; reading them is not a substitute for running them. These \`[external]\` suites also do not run through \`skyramp_execute_test\`, so skipping this leaves their status \`Unknown\`. Selector, health-gate, and self-skip behavior are in the tool description. (Skyramp-generated tests are handled in ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.BASELINE)}, not here.)
-
    ${MAINTAIN.TEST_HEALTH}. Call \`skyramp_analyze_test_health\` with \`stateFile\` (from \`skyramp_analyze_changes\` output). Pass \`blueprintCaptured: true\` when \`browser_blueprint\` was called successfully earlier in this session — see the parameter description for when this applies. **Do NOT read application source files** (routes, models, controllers) — all change information you need is in the \`skyramp_analyze_changes\` output and the diff. Exception: the UI drift pre-scan (\`UI_SYMBOL_PRESCAN\`) may instruct you to read changed frontend files to extract exported symbols — follow those instructions when present.
 
    ${MAINTAIN.UPDATE_INSTRUCTIONS}. Write \`updateInstructions\` for each UPDATE or REGENERATE test before calling \`skyramp_actions\` — articulating the change first prevents file content from overriding diff-based reasoning.
@@ -307,7 +358,7 @@ ${maintenanceBeforeExecStep}
 
    ${MAINTAIN.APPLY_ACTIONS}. Call \`skyramp_actions\` with \`stateFile\` (from \`skyramp_analyze_changes\` output) and apply the edits it returns.
 
-   ${MAINTAIN.VERIFY_EXTERNAL}. Verify external-test fixes. **This step is not optional and it is the easiest one to forget — you have just edited files in ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.APPLY_ACTIONS)}, so come back here before you move on to anything else.** It applies whenever ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.CONFIRM_EXTERNAL)} reported a real pass/fail result for a file you then edited. It does NOT apply when ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.CONFIRM_EXTERNAL)} returned \`skipped: true\` or \`ran: 0\` for every suite — there is no baseline to compare against, so say so in your report instead of re-running. When it applies: re-run those \`[external]\` files with \`skyramp_run_existing_tests\` (\`mode: "verify"\`, \`stateFile\`) and record each file's result as its \`afterStatus\`. Editing an \`[external]\` file that ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.CONFIRM_EXTERNAL)} confirmed failing and NOT re-running it leaves your own fix unverified — you would be reporting a repair you never saw work. A still-failing verify is surfaced in the report — do not loop.
+${verifyExternalStep}
 
 ${codeReviewBlock}
 
@@ -467,7 +518,8 @@ ${CONTRACT_MODE_GUIDANCE}
   - **\`browser_assert\`**: the \`browser_navigate\` result states the rule this tool has to satisfy on every page you reach. Call multiple assertions in the same tool call batch when checking independent elements.
   - **Removal guard — when \`uiContext.removedElements\` is non-empty**: the server lists which elements this PR removed — each identified by a \`data-*\` attribute and value, with the file it came from (renames, moves and deleted files are excluded). Read that file and the route or page files that render it to decide which page each appeared on. Per PAGE: \`browser_navigate\` to it, wait for the app to render, then call \`browser_assert_hidden\` once per listed element using the target the list shows — \`testId: "<value>"\` when the attribute is \`data-testid\`, otherwise \`attribute: "<name>", value: "<value>"\` (e.g. \`attribute: "data-cy"\`); no \`ref\` — the element no longer exists, so no snapshot has one; the tool checks the live page and refuses to record on a blank or un-rendered page. Then at least one \`browser_assert\` on a RETAINED element of the same page verifying its text, value or state. If a UI trace for that page is already planned, record the guard assertions inside that trace; otherwise this is its own trace and spec, \`verify-removed-ui-<page-slug>\`. The generated test asserts \`toBeHidden()\` on \`getByTestId(...)\` or \`page.locator('[data-cy="..."]')\` accordingly. A removed element the server did not list still gets its test (the removal check requires it) — ground that one in the diff and prefix its \`reasoning\` with \`[removed-element diff-grounded]\`; prefix \`reasoning\` with \`[removed-element server-listed]\` when the element came from \`uiContext.removedElements\`. When the removed element lived inside a control the page has to open — an \`option\` of a \`select\`, an item of a closed menu — open that control before asserting: a closed control's contents are never visible, so a hidden assertion recorded against a shut one passes whether the element was removed or not. \`browser_assert_hidden\` stays the tool either way, because \`browser_assert\` needs a snapshot \`ref\` and a removed element has none; where the control cannot be opened, say so in \`reasoning\` so the assertion step turns that guard into a count. **Deleted routes or pages are deleted features, not removed elements**: test the removal through the link or entry point that survives. A trace may still open the retired URL — to assert the app's fallback there, or that the old page's elements are gone — after it has recorded a positive \`browser_assert\` on a surviving page; a trace whose only visited page is the dead URL has no positive companion and is not a guard spec.
   - **Renames are not removals — on every PR, whatever \`uiContext.removedElements\` holds**: when a test id, \`aria-label\` or other accessible name changed, assert the element by its new identifier and leave the retired identifier alone (no \`browser_assert_hidden\` on it). A rename PR removes nothing, so this rule applies when the removed list is empty.
-  - **\`browser_visual_snapshot\` — for visual/appearance checks**: when the instruction asks to take a screenshot, capture a baseline, or verify how a page/element/region *looks* (not its text or value), call \`browser_visual_snapshot\` — it records a \`toHaveScreenshot()\` assertion so the generated test pixel-compares against a baseline on every run. Do NOT use \`browser_take_screenshot\` for this: it captures a throwaway image that is dropped at export and never appears in the generated test (use it only to view the page yourself).
+  - **\`browser_visual_snapshot\` — for visual/appearance checks**: when the instruction asks to take a screenshot, capture a baseline, or verify how a page/element/region *looks* (not its text or value), call \`browser_visual_snapshot\` — it records a \`toHaveScreenshot()\` assertion so the generated test pixel-compares against a baseline on every run. **EXCEPTION:** when the look in question IS the change under test (a colour, class, attribute or element-order the diff makes), assert the property directly instead — see the next bullet. Do NOT use \`browser_take_screenshot\` for this: it captures a throwaway image that is dropped at export and never appears in the generated test (use it only to view the page yourself).
+  - **A colour, class or attribute change the diff makes**: record it directly — \`browser_assert\` \`type: css/class/attribute\` on the element that OWNS the property (the flex container for \`flex-direction\`, not its children). If that owner has no stable ref, say so in \`reasoning\` as a recording gap — do not assert the wrong element or screenshot it. Element order has no assert kind: use \`flex-direction\` when the diff flipped it, else a \`boundingBox()\` comparison at the enhance step. \`browser_visual_snapshot\` only for a look no property expresses (image, gradient, chart).
   - **Wait for stable state before the second capture**: After performing an action that affects computed fields (filling a discount, submitting a form, adding an item), check the current page state before calling the second \`browser_blueprint\` (the capture after the action). If a computed field — total, price, count, derived text — still shows its initial empty or zero value (e.g. \`$0.00\`, \`0\`, \`Loading...\`, empty string), that means async data hasn't finished loading yet. Use \`browser_wait_for\` to wait up to 10 seconds for the field to update to a real value (for example, wait for the total to show a non-zero amount like \`$799.99\` instead of \`$0.00\`). Once the field shows a real value, THEN call the second \`browser_blueprint\` to capture stable state. If after 10 seconds the field still hasn't updated, skip the assertion on that field — don't capture and assert a value that hasn't loaded.
   If \`browser_navigate\` fails (app not running / connection refused), apply skip condition (a) above: leave the planned test in your plan, say in \`businessCaseAnalysis\` why it was not written, AND record the outage in \`issuesFound\`.
   Each trace costs browser tool calls, so record the ones your plan holds and no more. One trace that asserts a real outcome is worth more than three that assert a heading.
@@ -537,31 +589,36 @@ ${EXEC_FAIL.EXPECTED_FAILURE}. **Expected failure check (no retry):** If the fai
 
    This path also covers an assertion failure that application behavior outside this PR's diff explains — for example child records that survive the deletion of their parent, state inherited when an ID is recycled or reused, or a value that ignores a status the test set. Before you keep such a test red, confirm the cause in the source: read the handler, model, or query that should have done the work, and find the specific operation that is missing or wrong. If you find it, report the test as \`status: "Fail"\` and add an \`issuesFound\` entry for it. Do NOT retry.
 
-   If you cannot point at the missing or wrong line in application code, the app is not at fault — shared or seeded data, parallel test workers, or setup the test itself never did explain the collision. Treat that as an infrastructure failure: fix it and retry once as in step ${EXEC_FAIL.INFRA_RETRY}.
+   If you cannot point at the missing or wrong line in application code, the app is not at fault — shared or seeded data, parallel test workers, or setup the test itself never did explain the collision. Treat that as an infrastructure failure: fix it and re-run inside the budget of step ${EXEC_FAIL.INFRA_RETRY}.
 
    **If you did confirm the missing or wrong operation in the source, do NOT make the test pass.** Never add a reset, cleanup, or setup call for isolation. Never weaken the assertion — no \`==\` to \`>=\`, no exact value to a range. A failing test whose diagnosis names a pre-existing bug is the most valuable output of this run; a passing version of it reports nothing.
 
-${EXEC_FAIL.INFRA_RETRY}. Apply a targeted fix and retry **once** only for **infrastructure failures** — that means exactly **2 total \`skyramp_execute_test\` calls per test file** for these cases. Examples of infrastructure failures worth fixing:
+${maxFixAttempts === 1
+            ? `${EXEC_FAIL.INFRA_RETRY}. **This run's budget is one final-phase execution per file — there is no fix-and-rerun iteration.** Diagnose an infrastructure failure from the output; if the cause is clear, fix the file so the delivered test is right, but do NOT execute it again — the tool refuses a second call. Report it as \`status: "Fail"\` with the cause. The unchanged-re-run allowances do not apply either: a no-output run or a connection error is reported, not re-run (the tool's own retry of a connection error it catches still happens inside the one execution, and its response says so).\n`
+            : `${EXEC_FAIL.INFRA_RETRY}. Apply a targeted fix and re-run, only for **infrastructure failures**, inside a per-file budget of **${maxFixAttempts} final-phase execution${maxFixAttempts === 1 ? "" : "s"}** (${fixBudgetClause}; a maintained test's \`phase: "before"\` baseline run and a call the tool refused before running do not count). Each iteration: read the failure output the tool returned, change the test file or its inputs to address that specific cause, then execute again. Never re-run an unchanged file — with ONE exception per file, for either of two failures: a run that produced no output at all, or a connection error (connection refused, EOF). It does not apply when the tool's response carries its retry note ("re-ran this file once unchanged before answering"), and it is spent once the response says the run was itself an unchanged re-run of the previous one: the tool compares the file's contents run to run. Do not re-apply a fix that already failed; if the new output names no new cause, stop and report. Because you pass \`stateFile\` and \`repository\` on every \`skyramp_execute_test\` call in this run, the tool counts each file's final-phase executions there, appends "Execution attempt k of ${maxFixAttempts}" to every failure, and refuses the call once the budget is spent. Examples of infrastructure failures worth fixing:
    - Assertion mismatch from floating-point precision, or an expected value mis-transcribed from the observed response or computed with an arithmetic slip. If application behavior outside the diff explains the mismatch, it is not an infrastructure failure — use step ${EXEC_FAIL.EXPECTED_FAILURE} instead.
    - Import error, syntax error, or missing dependency in the generated test file${FIX_ERRORS_RETRY_HINT}
-   - Connection refused or timeout unrelated to the app under test
-${EXEC_FAIL.REPORT_FAIL}. If it still fails after the retry, report it as \`status: "Fail"\` with the error details and move on — do NOT edit and re-run a third time. A failing test that documents a real bug is a valid outcome.
-   A report-time check can then object to that row — a test you declared green that failed, or a red that fell over before it reached the behavior it targets. Expect that objection here: the cap stopped you, not the test. Answer it through \`answers\` on a second \`skyramp_submit_report\` call. Say whether the failure is the bug or the test, and that you reached the two-attempt cap. Do NOT run the test a third time to close the objection.
-
-### UI Test Execution Fix-up (counts toward the 2-attempt cap above)
-If a generated UI test fails with a timeout waiting for an element after navigation (e.g. \`TimeoutError\` on \`getByTestId\` or \`locator\`), first read the test output \`skyramp_execute_test\` returned — its console lines and the URL the page ended on.
-- **The route is broken** when that output reports a failed load of the page the test navigated to, or when the page ended on a route that is neither the login page nor another spelling of the URL it navigated to. Report \`status: "Fail"\` and name in the details both the route the test asked for and the URL the page reached. Do not change the waits.
-- **Otherwise** apply BOTH fixes in a single edit before retrying:
-1. After the login submit, add \`await page.waitForURL((u) => !u.pathname.startsWith('/login'));\`. After every other \`page.goto()\`, wait for the first element the next step uses with \`await expect(locator).toBeVisible();\`. Do not add \`waitForLoadState('networkidle')\`.
-2. Add \`await page.locator('[data-testid="some-element"]').waitFor({ state: 'visible', timeout: 10000 });\` for the specific element the test needs.
-Do NOT use \`page.waitForTimeout()\` with fixed delays. Do NOT retry more than once — if the test still fails after this fix, report it as "Fail".
+   - Connection refused or timeout unrelated to the app under test\n`}
+${EXEC_FAIL.REPORT_FAIL}. If it still fails when the budget is spent, report it as \`status: "Fail"\` with the last error details and move on — do NOT edit and re-run past the cap. A failing test that documents a real bug is a valid outcome.
+   A report-time check can then object to that row — a test you declared green that failed, or a red that fell over before it reached the behavior it targets. Expect that objection here: the cap stopped you, not the test. Answer it through \`answers\` on a second \`skyramp_submit_report\` call. Say whether the failure is the bug or the test, and that you reached the ${maxFixAttempts}-attempt cap. Do NOT run the test again to close the objection.
+
+${maxFixAttempts === 1
+            ? `### UI Test Execution Fix-up (diagnosis only — this run's budget is one execution per file)
+The tool refuses a second execution, so a UI timeout is diagnosed and reported, never retried; the diagnosis below still decides what you report and what you fix in the delivered file. ${UI_TIMEOUT_READ_OUTPUT}
+${UI_TIMEOUT_ROUTE_BULLET}${UI_TIMEOUT_POSITIONAL_BULLET}- **Otherwise** the element was late or the wait was missing: make BOTH edits below in the delivered file, but do NOT execute it again; report \`status: "Fail"\` naming the element that timed out and the waits you added.
+${UI_TIMEOUT_WAIT_STEPS}\n`
+            : `### UI Test Execution Fix-up (counts toward the ${maxFixAttempts}-attempt cap above)
+${UI_TIMEOUT_READ_OUTPUT}
+${UI_TIMEOUT_ROUTE_BULLET}${UI_TIMEOUT_POSITIONAL_BULLET}- **Otherwise** apply BOTH fixes in a single edit before retrying:
+${UI_TIMEOUT_WAIT_STEPS}
+If the test still fails after this fix, spend a remaining attempt only on a different, specific cause the new output names — never re-apply the same waits. When the budget is spent, report it as "Fail".\n`}
 
 **After generation, complete these steps** (generation results may add their own CRITICAL NEXT STEPS — e.g. modularize-then-reuse for integration or UI tests generated with \`codeReuse: true\` — follow those too, in the order the result states):
-${POSTGEN.INTEGRATION_ENHANCE}. **[MANDATORY] After \`skyramp_integration_test_generation\`**: Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated integration test file, \`testType: "integration"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.
-${POSTGEN.CONTRACT_ENHANCE}. **[MANDATORY] After \`skyramp_contract_test_generation\` with \`providerMode\`**: Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated provider contract test file, \`testType: "contract"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.
+${POSTGEN.INTEGRATION_ENHANCE}. **[MANDATORY] After \`skyramp_integration_test_generation\`**: ${capitalize(enhanceAssertionsCall("integration", "generated integration test file"))}.
+${POSTGEN.CONTRACT_ENHANCE}. **[MANDATORY] After \`skyramp_contract_test_generation\` with \`providerMode\`**: ${capitalize(enhanceAssertionsCall("contract", "generated provider contract test file"))}.
 ${UI_CODE_REUSE_STEP}
 ${POSTGEN.UI_ENHANCE}. **[MANDATORY] After \`skyramp_ui_test_generation\`**: ${UI_ENHANCE_STEP} The HIGH-tier \`possibleAssertions\` from your second \`browser_blueprint\` captures (after each action) during trace recording are in your context — when the enhance instructions ask you to add assertions for state-changing actions, use those grounded candidates first (they contain exact computed values from the DOM delta, e.g. \`toHaveText('Total: $899.98')\`). Only fall back to deriving values from the test file or source code when no HIGH-tier candidate covers the action.
-${POSTGEN.WAIT}. **Wait**: Do NOT proceed to test execution until steps ${POSTGEN.INTEGRATION_ENHANCE}–${POSTGEN.UI_ENHANCE} (plus any generation-result CRITICAL NEXT STEPS) are complete and the verification checklist in the \`skyramp_enhance_assertions\` tool result has been validated for EVERY generated test file.
+${POSTGEN.WAIT}. **Wait**: Do NOT proceed to test execution until steps ${POSTGEN.INTEGRATION_ENHANCE}–${POSTGEN.UI_ENHANCE} (plus any generation-result CRITICAL NEXT STEPS) are complete and the assertion verification has passed for EVERY generated test file. Count them before you proceed: list the test files you generated, and confirm each one has both a recorded assertion baseline and a passing verification. A file missing either is not done — go back and finish it.
 Do not make any changes other than the code-reuse refactoring (step ${POSTGEN.UI_CODE_REUSE} and the generation-result reuse steps) and the assertion enhancements described above. For example: do not modify auth headers, cookies, tokens, env vars, or imports that the generation tool already set correctly — those are correct by construction and changing them breaks auth or execution.
 
 ${FINISH_CHECKS_BLOCK}
@@ -569,13 +626,15 @@ ${FINISH_CHECKS_BLOCK}
 **Execution timing:**
 - **beforeStatus** (maintained tests only): execute each maintained test file **once at the start** (before any edits) to capture \`beforeStatus\`. This is the only execution allowed before edits.
 - **Probe residue**: before the final execution, delete through the API the records your own probes and recordings created. Find each one by the id its create response returned, or by the exact value you typed for it during a recording. Do not delete anything else, and do not delete by a pattern. Do not use the database or a container. Do not add the deletion to a test. List in the report the records the API could not remove.
-- **Final execution**: Do NOT call \`skyramp_execute_test\` again until ALL maintenance edits AND ALL new test generation/enhancement are complete. Then execute every test file once — maintained files (for \`afterStatus\`) and new files together. For a maintained spec whose \`skyramp_actions\` entry carried \`rebaseline_snapshots\`, pass that exact list as \`rebaselineSnapshots\` on this run and only this run. **Execute tests SEQUENTIALLY (one at a time)** — do NOT send multiple \`skyramp_execute_test\` calls in the same tool call batch, as concurrent execution overwhelms the stdio transport and causes MCP disconnection. Exclude tests marked \`[external]\`.
+- **Final execution**: Apart from ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.VERIFY_EXTERNAL)}, do NOT call \`skyramp_execute_test\` again until ALL maintenance edits AND ALL new test generation/enhancement are complete. Then execute every test file once — maintained files (for \`afterStatus\`) and new files together — passing \`stateFile\` and \`repository\` on every call: the attempt cap and the \`afterStatus\` the report reads both live in that file, and \`repository\` names the section the result lands in. Omitting \`stateFile\` does not skip the cap — the tool falls back to this run's own state file — but a wrong or missing \`repository\` fails the call. For a maintained spec whose \`skyramp_actions\` entry carried \`rebaseline_snapshots\`, pass that exact list as \`rebaselineSnapshots\` on this run and only this run. **Execute tests SEQUENTIALLY (one at a time)** — do NOT send multiple \`skyramp_execute_test\` calls in the same tool call batch, as concurrent execution overwhelms the stdio transport and causes MCP disconnection. Exclude tests marked \`[external]\`.
 - Only report test results for files you actually ran.
+
+### Post-Execution: Assertion Alignment
+Once execution is final, for each ${ASSERTION_ENHANCEABLE_TEST_TYPES.join(", ")} test, new or maintained, verify its assertions validate the scenario it was created for: ${alignAssertionsStep()}
+
 **Auth**: If \`skyramp_analyze_changes\` reports an auth token or \`SKYRAMP_TEST_TOKEN\` is set, pass it in **every** \`skyramp_execute_test\` call from the first attempt — do NOT wait for a 401/403 to discover auth is needed.`;
     }
-    const primaryRepoBlock = primaryRepo
-        ? `<REPOSITORY>${primaryRepo}</REPOSITORY>\n`
-        : "";
+    const primaryRepoBlock = `<REPOSITORY>${primaryRepo}</REPOSITORY>\n`;
     // Placed AHEAD of Task 1, not next to the register call in Task 2: the agent has
     // to name the changed file it is about, and cite the file it sits
     // in, and cite `routes` from the checkout, and all of those happen while
@@ -614,10 +673,9 @@ In these cases:
 
 ${task3CountRule ? `${task3CountRule}\n\n` : ""}${reportLanguageBlock}Call \`skyramp_submit_report\`. Field names, types, and formats are defined in the tool's parameter schema — follow them exactly. A report check objects to an \`issuesFound\` entry with \`category: bug\` that no delivered test proves. The \`plannedTestId\` and \`defectId\` descriptions in the schema say what closes it. Answer an objection in one line.
 
-${hasRelatedRepos
-        ? `
-- **MULTI-REPO attribution**: Set the \`repository\` field (\`owner/repo\`) on EVERY \`newTestsCreated\`, \`testResults\` and \`issuesFound\` item — including items about the PRIMARY repo — so each objection is unambiguously attributed. The primary repo's \`repository\` is \`${primaryRepo || "<the primary repo's owner/repo>"}\`; items derived from a related repo's diff (from the \`<related_repositories>\` analysis) carry that repo's \`repository\` value. In \`businessCaseAnalysis\`, include a short per-repo subsection and call out any cross-repo correlations you found.
-`
+
+- **Repository attribution**: Set the \`repository\` field (\`owner/repo\`) on EVERY \`newTestsCreated\`, \`testResults\`, \`issuesFound\` and \`additionalRecommendations\` item. The primary repo's \`repository\` is \`${primaryRepo}\`.${hasRelatedRepos
+        ? ` Items derived from a related repo's diff (from the \`<related_repositories>\` analysis) carry that repo's \`repository\` value. In \`businessCaseAnalysis\`, include a short per-repo subsection and call out any cross-repo correlations you found.`
         : ""}
 
 ${getTraceRecordingPromptText({ outputDir: `${repositoryPath}/.skyramp`, modularize: false, modularizeViaGenerationResult: UI_UTILS_REUSE })}`;
@@ -670,8 +728,9 @@ export function registerTestbotPrompt(server) {
                 .describe("JSON-encoded array of {repo, repositoryPath, baseBranch?} for related repositories to analyze (multi-repo mode). `repo` is the owner/repo slug (resolved by the action; used verbatim, never inferred). Each is analyzed with its own skyramp_analyze_changes call; the agent correlates cross-repo changes and submits ONE plan covering every repo. Generated test files are delivered into each service's declared testDirectory, relative to the single delivery root (the primary repo, or the configured test repo)."),
             primaryRepo: z
                 .string()
-                .optional()
-                .describe("The primary repository's owner/repo slug (where the testbot workflow runs). Used verbatim as the `repository` attribution for the primary repo's analysis, tests, and report items in multi-repo runs."),
+                .trim()
+                .min(1)
+                .describe("The primary repository's 'owner/repo' (e.g. 'letsramp/api-insight'), read from its checkout's origin remote. Every report item, planned test and tool call attributes to this name or to a related repository's own."),
             planOnly: z
                 // Prompt/resource URL args arrive as strings — accept "true"/"1"
                 // alongside a real boolean; anything else (incl. undefined) is false.
@@ -682,6 +741,16 @@ export function registerTestbotPrompt(server) {
                 .string()
                 .optional()
                 .describe("Language code (e.g. 'ja') for user-facing report content. When set to a non-English language, the agent writes all free-text report fields in that language; identifiers, endpoints, file names, and enum values stay untranslated. Omitted or 'en' → English."),
+            // "perTest…" on the wire (the argument name reaches the agent's context;
+            // a bare "maxFixAttempts" reads as a run-wide total); `maxFixAttempts`
+            // in code.
+            perTestMaxFixAttempts: z
+                // Prompt args arrive as strings. The shared parser maps an unusable
+                // spelling or an out-of-range value to undefined, so this entry point
+                // falls through to SKYRAMP_MAX_FIX_ATTEMPTS and the default exactly
+                // like the resource does, instead of rejecting the call.
+                .preprocess((v) => parseMaxFixAttemptsArg(v), z.number().int().min(1).max(10).optional())
+                .describe("Per-TEST-FILE cap on skyramp_execute_test calls in the final phase: the first run plus the fix-and-rerun iterations the agent may spend on an infrastructure failure for that one file (SKYR-4460). 1..10; falls back to SKYRAMP_MAX_FIX_ATTEMPTS, then 3."),
         },
     }, async (args) => {
         const services = await readWorkspaceServices(args.repositoryPath);
@@ -699,6 +768,7 @@ export function registerTestbotPrompt(server) {
             primaryRepo: args.primaryRepo,
             planOnly: args.planOnly,
             language: args.language,
+            maxFixAttempts: args.perTestMaxFixAttempts,
         });
         if (args.workspaceValidationFailed) {
             prompt = buildWorkspaceRecoveryPrefix(args.repositoryPath) + prompt;

package/build/recommendation/answers.js

@@ -6,13 +6,13 @@ export const UNKNOWN_ANSWER_PREFIX = "answers:unknown:";
 export function answerFor(objection, acknowledged) {
     const wantsBlocker = needsBlocker(objection.objectionId);
     for (const entry of acknowledged) {
-        if (entry?.objectionId !== objection.objectionId)
+        if (entry.objectionId !== objection.objectionId)
             continue;
         const rawAnswer = entry.answer;
         const answer = typeof rawAnswer === "string" ? rawAnswer.trim() : "";
         if (answer.length === 0)
             continue;
-        if (wantsBlocker && String(entry?.blocker ?? "").trim().length === 0)
+        if (wantsBlocker && String(entry.blocker ?? "").trim().length === 0)
             continue;
         return answer;
     }
@@ -23,7 +23,9 @@ export function answerFor(objection, acknowledged) {
  *  recognised BY ITS PREFIX and never draws an objection of its own. `scope` and
  *  `suggestion` are passed in: the two callers raise this about different lists. */
 export function unknownAnswerObjections(objections, acknowledged, { scope, suggestion }) {
-    const answered = acknowledged.map((entry) => entry?.objectionId).filter((id) => typeof id === "string");
+    const answered = acknowledged
+        .map((entry) => entry.objectionId)
+        .filter((id) => typeof id === "string");
     const raised = new Set(objections.map((objection) => objection.objectionId));
     const raisedHere = [];
     const seen = new Set();
@@ -47,7 +49,8 @@ export function unknownAnswerObjections(objections, acknowledged, { scope, sugge
  *  leave the bug. `verifierContracts.ts` carries the evidence. */
 export const NON_ANSWERABLE_PREFIX = "coverage:stateTest:";
 export function isNonAnswerable(objectionId) {
-    return typeof objectionId === "string" && objectionId.startsWith(NON_ANSWERABLE_PREFIX);
+    return (typeof objectionId === "string" &&
+        objectionId.startsWith(NON_ANSWERABLE_PREFIX));
 }
 /** The objections a sentence alone does not close either. A change with no test
  *  needs the test, and a defect with no test needs the test — a defect the code
@@ -59,9 +62,13 @@ export function isNonAnswerable(objectionId) {
  *  Prose closed every uncovered change, including changes nothing prevented a test
  *  from reaching. Runs 34423214322 and 34423217796 then lost three defects the
  *  baseline reported: each was listed and closed by a sentence. */
-export const BLOCKER_ONLY_PREFIXES = ["coverage:change:", "defects:untested:"];
+export const BLOCKER_ONLY_PREFIXES = [
+    "coverage:change:",
+    "defects:untested:",
+];
 export function needsBlocker(objectionId) {
-    return typeof objectionId === "string" && BLOCKER_ONLY_PREFIXES.some((prefix) => objectionId.startsWith(prefix));
+    return (typeof objectionId === "string" &&
+        BLOCKER_ONLY_PREFIXES.some((prefix) => objectionId.startsWith(prefix)));
 }
 /** The objection raised below carries this prefix and the id it objects to. */
 export const REFUSED_ANSWER_PREFIX = "answers:refused:";
@@ -69,11 +76,13 @@ export const REFUSED_ANSWER_PREFIX = "answers:refused:";
  *  objection STAYS OPEN — this says so, rather than letting the answer pass in
  *  silence while the plan still owes the test. */
 export function refusedAnswerObjections(objections, acknowledged) {
-    const raised = new Set(objections.map((objection) => objection.objectionId).filter((id) => isNonAnswerable(id) || needsBlocker(id)));
+    const raised = new Set(objections
+        .map((objection) => objection.objectionId)
+        .filter((id) => isNonAnswerable(id) || needsBlocker(id)));
     const refused = [];
     const seen = new Set();
     for (const entry of acknowledged) {
-        const id = entry?.objectionId;
+        const id = entry.objectionId;
         if (typeof id !== "string" || !raised.has(id) || seen.has(id))
             continue;
         const answer = entry.answer;
@@ -81,7 +90,7 @@ export function refusedAnswerObjections(objections, acknowledged) {
             continue;
         // An answer that names a blocker DOES close an untested change, so it is not
         // refused. Only the sentence on its own is.
-        if (needsBlocker(id) && String(entry?.blocker ?? "").trim().length > 0)
+        if (needsBlocker(id) && String(entry.blocker ?? "").trim().length > 0)
             continue;
         seen.add(id);
         refused.push({

package/build/recommendation/pullRequestText.js

@@ -7,7 +7,7 @@
  *  ONE SLOT, last write wins. A run renders the prompt once, and a second render is
  *  a second run whose text replaces the first. */
 let recorded;
-const asText = (value) => (typeof value === "string" ? value : "");
+const asText = (value) => typeof value === "string" ? value : "";
 /** Called by every entry point that renders the testbot prompt, with the values it
  *  renders. */
 export function recordPullRequestText(title, description) {

package/build/recommendation/registerPlan.js

@@ -1,4 +1,4 @@
-import { answerFor, isNonAnswerable, refusedAnswerObjections, unknownAnswerObjections } from "./answers.js";
+import { answerFor, isNonAnswerable, refusedAnswerObjections, unknownAnswerObjections, } from "./answers.js";
 import { runPlanTimeVerifiers } from "./runVerifiers.js";
 import { logger } from "../utils/logger.js";
 function storedRegistrationNumber(registration) {
@@ -16,19 +16,29 @@ function carriedAnswerFor(objectionId, previous) {
     // Both buckets: a blocker close is stored apart from an answer, and an objection
     // that recurs still carries the one it was closed with.
     const answered = [
-        ...(Array.isArray(previous?.answeredObjections) ? previous.answeredObjections : []),
-        ...(Array.isArray(previous?.unverifiedCloses) ? previous.unverifiedCloses : []),
+        ...(Array.isArray(previous?.answeredObjections)
+            ? previous.answeredObjections
+            : []),
+        ...(Array.isArray(previous?.unverifiedCloses)
+            ? previous.unverifiedCloses
+            : []),
     ];
     if (answered.length === 0)
         return undefined;
     for (const entry of answered) {
+        // `previous` is the plan read back from the state file, which is cast, not
+        // validated. A null entry there must not stop a new registration being stored.
         if (entry?.objection?.objectionId !== objectionId)
             continue;
         const answer = typeof entry.answer === "string" ? entry.answer.trim() : "";
         // The blocker travels with the answer it belongs to. Carrying the sentence
         // alone would reopen every untested change the previous registration closed.
         if (answer.length > 0)
-            return { objectionId, answer, ...(entry.blocker ? { blocker: entry.blocker } : {}) };
+            return {
+                objectionId,
+                answer,
+                ...(entry.blocker ? { blocker: entry.blocker } : {}),
+            };
     }
     return undefined;
 }
@@ -50,16 +60,12 @@ function carriedAnswers(objections, acknowledged, previous) {
     return carried;
 }
 export function registerPlan(registration, ctx, previous) {
-    const acknowledged = Array.isArray(registration.answers) ? registration.answers : [];
-    const plannedTests = Array.isArray(registration.plannedTests) ? registration.plannedTests : [];
-    const changes = Array.isArray(registration.changes) ? registration.changes : [];
-    const defects = Array.isArray(registration.defects) ? registration.defects : [];
+    const acknowledged = registration.answers;
+    const plannedTests = registration.plannedTests;
+    const changes = registration.changes;
+    const defects = registration.defects;
     const registrationNumber = storedRegistrationNumber(registration);
-    // The verifiers see the same normalised fields the STORED plan gets, not the raw
-    // registration: handing them the raw one let a malformed top-level field crash
-    // every check at once, giving eight `:crashed` objections and no real ones.
-    // Crash containment is for a malformed field INSIDE a planned test.
-    const verified = runPlanTimeVerifiers({ ...registration, plannedTests, changes, defects, answers: acknowledged }, ctx);
+    const verified = runPlanTimeVerifiers(registration, ctx);
     const objections = [
         ...verified,
         ...unknownAnswerObjections(verified, acknowledged, {
@@ -81,9 +87,12 @@ export function registerPlan(registration, ctx, previous) {
         // a planned test too, unless the answer names what stopped this run from
         // writing one. Either way an answer that does not close it leaves it open and
         // draws the refusal objection raised above.
-        const answer = isNonAnswerable(objection.objectionId) ? undefined : answerFor(objection, answers);
+        const answer = isNonAnswerable(objection.objectionId)
+            ? undefined
+            : answerFor(objection, answers);
         if (answer) {
-            const blocker = answers.find((entry) => entry?.objectionId === objection.objectionId && String(entry?.blocker ?? "").trim().length > 0)?.blocker;
+            const blocker = answers.find((entry) => entry.objectionId === objection.objectionId &&
+                String(entry.blocker ?? "").trim().length > 0)?.blocker;
             // A blocker closes the objection and nothing here can check it, so it is
             // counted apart from an answer the plan itself makes checkable.
             if (blocker)
@@ -104,7 +113,12 @@ export function registerPlan(registration, ctx, previous) {
         objections,
         summary,
         ...(carried.length > 0 && previous
-            ? { carried: { registrationNumber: previous.registrationNumber, answers: carried } }
+            ? {
+                carried: {
+                    registrationNumber: previous.registrationNumber,
+                    answers: carried,
+                },
+            }
             : {}),
         plan: {
             changes,
@@ -112,7 +126,7 @@ export function registerPlan(registration, ctx, previous) {
             plannedTests,
             // Only when declared: the field is optional, and writing `[]` on every plan
             // would change the stored shape of every run that maintains nothing.
-            ...(Array.isArray(registration.maintains) && registration.maintains.length > 0
+            ...(registration.maintains?.length
                 ? { maintains: registration.maintains }
                 : {}),
             answeredObjections,