@skyramp/mcp 0.4.3 → 0.4.4-rc.1

package/build/playwright/traceRecordingPrompt.js

@@ -5,6 +5,7 @@
 import { z } from "zod";
 import { logger } from "../utils/logger.js";
 import { getPersonaPrefix } from "../prompts/personas.js";
+import { ORDER_ASSERTION_RULE } from "../prompts/orderAssertionRule.js";
 export function getTraceRecordingPromptText(opts) {
     const outputDir = opts?.outputDir;
     const modularize = opts?.modularize ?? true;
@@ -65,7 +66,7 @@ Call \`browser_assert\` when assertions are needed. Provide \`expected\` for eve
 
 **Visual / screenshot assertions.** When the instruction asks to take a screenshot, capture a baseline, or verify how a page/element/region *looks* (as opposed to its text or value), call \`browser_visual_snapshot\` — it records a \`toHaveScreenshot()\` assertion so the generated test pixel-compares against a baseline image on every run.
 
-**When the change under test is how something looks** — a colour, class or attribute the diff changes — assert it directly with \`browser_assert\` \`type: css/class/attribute\` on the element that OWNS the property (the flex container for \`flex-direction\`, not its children); if it has no stable ref, note a recording gap rather than assert the wrong element. Order has no kind: \`flex-direction\` when the diff flipped it, else a \`boundingBox()\` comparison at enhance. \`browser_visual_snapshot\` only for a look no property expresses (image, gradient, chart).
+**When the change under test is how something looks** — a colour, class or attribute the diff changes — assert it directly with \`browser_assert\` \`type: css/class/attribute\` on the element that OWNS the property (the flex container for \`flex-direction\`, not its children); if it has no stable ref, note a recording gap rather than assert the wrong element. ${ORDER_ASSERTION_RULE} \`browser_visual_snapshot\` only for a look no property expresses (image, gradient, chart).
 
 Do NOT use \`browser_take_screenshot\` to record a visual check: it only captures a throwaway image, is dropped at export (it produces no assertion), and will NOT appear in the generated test. Use it only to view the page yourself while recording. \`filename\` is optional on \`browser_visual_snapshot\`: if the instruction names a baseline file (e.g. \`page-001.png\`) pass it as \`filename\`, otherwise omit it and one is auto-generated per \`snapshotType\` (\`page-NNN.png\` for a page, \`el-NNN.png\` for an element, \`region-NNN.png\` for a region).
 

package/build/prompts/orderAssertionRule.d.ts

@@ -0,0 +1,9 @@
+/**
+ * When to record a swap, move or reorder as an order assertion. It lives in the
+ * trace-recording prompt, which the testbot flow includes; the top-level testbot
+ * prompt does not repeat test-type details. The type's parameters are
+ * documented by browser_assert's own description, and the pairing rule (two
+ * sibling blocks, not a block and something inside it) is enforced and
+ * explained by the tool, so neither is repeated here.
+ */
+export declare const ORDER_ASSERTION_RULE = "**A swap, move or reorder** (left/right columns swapped, a sidebar moved, blocks reordered) is recorded with `browser_assert` `type: \"order\"` on two blocks (`ref` and `otherRef`), so the test fails if the swap is undone; `flex-direction` alone is not enough when the diff reorders markup.";

package/build/prompts/orderAssertionRule.js

@@ -0,0 +1,9 @@
+/**
+ * When to record a swap, move or reorder as an order assertion. It lives in the
+ * trace-recording prompt, which the testbot flow includes; the top-level testbot
+ * prompt does not repeat test-type details. The type's parameters are
+ * documented by browser_assert's own description, and the pairing rule (two
+ * sibling blocks, not a block and something inside it) is enforced and
+ * explained by the tool, so neither is repeated here.
+ */
+export const ORDER_ASSERTION_RULE = '**A swap, move or reorder** (left/right columns swapped, a sidebar moved, blocks reordered) is recorded with `browser_assert` `type: "order"` on two blocks (`ref` and `otherRef`), so the test fails if the swap is undone; `flex-direction` alone is not enough when the diff reorders markup.';

package/build/prompts/test-maintenance/driftAnalysisShared.js

@@ -55,6 +55,8 @@ ${opts.domainNotes}
 
 **When uncertain, use VERIFY not IGNORE:** If the diff touches code this test could exercise but you cannot confirm impact without reading more context, assign VERIFY — do not default to IGNORE.
 
+**If your rationale concludes the test is unaffected, assign IGNORE, not VERIFY.** Assign VERIFY only for a doubt that the code you read does not settle. A rule that forbids IGNORE still applies.
+
 **A stated requirement wins over the code.** Before you write a new value or refresh a screenshot in an existing test, compare it with what the pull request title, the description and any requirements file they name state. If the new value breaks a stated requirement, do not write it: keep that assertion on the requirement's value and make only the other edits. If no other edit remains, mark the test VERIFY. The test stays red; do not relax it. If the requirements file is unchanged and the description presents the new behaviour as intended, the file is out of date: update the test.
 
 **Pre-commit verification — confirm before finalizing UPDATE/REGENERATE/DELETE:**

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

@@ -6,7 +6,7 @@ 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 { recordPullRequestText, recordUiCredentials, } 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";
@@ -239,6 +239,9 @@ export function getTestbotPrompt(opts) {
     setPrimaryRepository({ repositoryPath, repo: primaryRepo });
     // Kept in the process for the plan tool, which is registered on this server.
     recordPullRequestText(prTitle, prDescription);
+    // Beside it and for the same reason: a `credential-missing` blocker is checked
+    // against whether this run was given any.
+    recordUiCredentials(uiCredentials);
     // The legacy count arguments are DECLARED NOWHERE, so zod strips them and their
     // names never reach the agent — not in a schema it lists, not in rendered text.
     // A number in front of the agent reads as a ceiling whatever the words around it
@@ -332,12 +335,12 @@ export function getTestbotPrompt(opts) {
     let maintenanceBeforeExecStep;
     let verifyExternalStep;
     if (planOnly) {
-        verifyExternalStep = `   ${MAINTAIN.VERIFY_EXTERNAL}. Plan-only run: do not run the external tests you edited.`;
+        verifyExternalStep = `   ${MAINTAIN.VERIFY_EXTERNAL}. Plan-only run: do not run the external tests you edited or the VERIFY files.`;
         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 {
-        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.`;
+        verifyExternalStep = `   ${MAINTAIN.VERIFY_EXTERNAL}. Run the external tests you edited again, and run each VERIFY file once. Do this step right after ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.APPLY_ACTIONS)}, before you plan new tests. 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, and to each file you marked VERIFY, except a test in a related repository. Run each such file with \`skyramp_execute_test\`, \`phase: "after"\` and \`stateFile\`. For an edited file, 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 and VERIFY 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, so its one run comes in ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.VERIFY_EXTERNAL)}, 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.
@@ -536,7 +539,7 @@ ${CONTRACT_MODE_GUIDANCE}
   - **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. **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).
+  - **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. \`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.
@@ -641,9 +644,9 @@ Do not make any changes other than the code-reuse refactoring (step ${POSTGEN.UI
 ${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.
+- **beforeStatus** (maintained tests only): execute each maintained test file you will edit **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**: 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]\`.
+- **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]\` and VERIFY files: both ran in ${stepSubRef(TASK1.MAINTAIN, MAINTAIN.VERIFY_EXTERNAL)}.
 - Only report test results for files you actually ran.
 
 ### Post-Execution: Assertion Alignment

package/build/recommendation/answers.d.ts

@@ -1,10 +1,25 @@
-import { ObjectionAnswer, Objection } from "./types.js";
+import { ObjectionAnswer, Objection, PlanBlocker } from "./types.js";
+import { BlockerVerdict } from "./blockers.js";
+export { BLOCKER_DESCRIPTION } from "./blockers.js";
+/** What the server made of one answer's blocker. Passed in, never computed here:
+ *  the probes are network and git calls and the verifiers reach neither. UNDEFINED
+ *  where the caller ran no probes, which reads as `unverifiable` — the position
+ *  every blocker close stood in before the checks existed. */
+export type BlockerJudge = (blocker: PlanBlocker) => BlockerVerdict;
 /** The objection raised below carries this prefix and the id it objects to. */
 export declare const UNKNOWN_ANSWER_PREFIX = "answers:unknown:";
-/** The answer to one objection, matched by `objectionId` and never by position — the
- *  agent reorders its list between registrations. A whitespace-only answer closes
- *  nothing, and the FIRST NON-BLANK entry wins when one id is answered twice. */
-export declare function answerFor(objection: Objection, acknowledged: ObjectionAnswer[]): string | undefined;
+/** The entry that closed one objection, matched by `objectionId` and never by
+ *  position — the agent reorders its list between registrations. A whitespace-only
+ *  answer closes nothing, and the FIRST NON-BLANK entry wins when one id is
+ *  answered twice. Its `answer` comes back trimmed.
+ *
+ *  The ENTRY, so a caller that files the blocker files the one that arrived with
+ *  THIS answer. Searching for the two separately took them from different entries:
+ *  a blank-answer entry supplied the blocker, and a refuted claim was published
+ *  beside an answer a later entry had closed. */
+export declare function closingAnswerFor(objection: Objection, acknowledged: ObjectionAnswer[], judge?: BlockerJudge): ObjectionAnswer | undefined;
+/** The closing answer as the sentence alone, for a caller that files no blocker. */
+export declare function answerFor(objection: Objection, acknowledged: ObjectionAnswer[], judge?: BlockerJudge): string | undefined;
 /** One objection per answer naming an objection this call did not raise — a stale
  *  id, a typo and a pre-emptive answer all used to pass in silence. An id is
  *  recognised BY ITS PREFIX and never draws an objection of its own. `scope` and
@@ -13,29 +28,49 @@ export declare function unknownAnswerObjections(objections: Objection[], acknowl
     scope: string;
     suggestion: string;
 }): Objection[];
-/** The one objection an answer does not close. Every other check in v2 can be
- *  answered, and this one cannot: the missed bugs it exists for were reached by
- *  prose twice and skipped twice, so an answer would close the objection and
- *  leave the bug. `verifierContracts.ts` carries the evidence. */
-export declare const NON_ANSWERABLE_PREFIX = "coverage:stateTest:";
+/** The objections an answer does not close, only a planned test.
+ *
+ *  `coverage:stateTest:` — the missed bugs it exists for were reached by prose twice
+ *  and skipped twice, so an answer would close the objection and leave the bug.
+ *  `verifierContracts.ts` carries the evidence.
+ *
+ *  `defects:untested:` — a declared defect's test can always be written, even when
+ *  the service it runs against is down: it is committed and runs once the service is
+ *  back. Every blocker Wipro repo-1 sent for a defect (14 on one run, 2 on the next)
+ *  named a limit of the browser tools, and none got a test.
+ *
+ *  `defects:expectedPass:` — a test that passes today proves nothing about a defect,
+ *  and a sentence here would let one cited passing test stand in for the red one. */
+export declare const NON_ANSWERABLE_PREFIXES: readonly ["coverage:stateTest:", "defects:untested:", "defects:expectedPass:"];
 export declare function isNonAnswerable(objectionId: unknown): boolean;
 /** The objections a sentence alone does not close either. A change with no test
- *  needs the test, a value a page and API change refuses needs a UI test or a
- *  maintained spec that names it (the XR02 evidence is at `surfaceReject` in
- *  `verifierContracts.ts`), and a defect with no test needs the test — a defect
- *  the code already had before this pull request included. Each closes only when the
- *  answer also names what stopped the test: a service that is not running, a
- *  branch that no longer exists, the one credential the run holds. Measured on run
+ *  needs the test, a value a page and API change accepts or refuses needs a UI step
+ *  that names it (the XR02 evidence is at `surfaceCase` and `surfaceReject` in
+ *  `verifierContracts.ts`). Each closes only when the answer also names what stopped
+ *  the test: a service that is not running, or the one credential the run holds. Measured on run
  *  34176038240: across eight fixtures 45 objections were raised and 45 were
  *  closed, and the one class that a sentence cannot close was never raised at all.
  *  Prose closed every uncovered change, including changes nothing prevented a test
  *  from reaching. Runs 34423214322 and 34423217796 then lost three defects the
- *  baseline reported: each was listed and closed by a sentence. */
-export declare const BLOCKER_ONLY_PREFIXES: readonly ["coverage:change:", "coverage:surfaceReject:", "defects:untested:"];
+ *  baseline reported: each was listed and closed by a sentence.
+ *
+ *  A bug the report states is the same promise made after the tests run, so it
+ *  closes the same way. Runs 34434835959 (repo15 RG21 and RG15) and 34434838150
+ *  (repo10 RG03) answered three `issueTraceability:` objections with "outside this
+ *  PR's surface" and "unobservable" and wrote no test — and RG21 and RG15 were the
+ *  same 404 bootstrap bug, reported twice and tested neither time. */
+export declare const BLOCKER_ONLY_PREFIXES: readonly ["coverage:change:", "coverage:surfaceCase:", "coverage:surfaceReject:", "issueTraceability:"];
 export declare function needsBlocker(objectionId: unknown): boolean;
 /** The objection raised below carries this prefix and the id it objects to. */
 export declare const REFUSED_ANSWER_PREFIX = "answers:refused:";
 /** One objection per answer to an objection only a planned test closes. The answered
  *  objection STAYS OPEN — this says so, rather than letting the answer pass in
  *  silence while the plan still owes the test. */
-export declare function refusedAnswerObjections(objections: Objection[], acknowledged: ObjectionAnswer[]): Objection[];
+export declare function refusedAnswerObjections(objections: Objection[], acknowledged: ObjectionAnswer[], judge?: BlockerJudge, 
+/** Whether an EARLIER call already closed this objection and that close still
+ *  stands. The report tool carries answers across calls, so an objection closed
+ *  on call 1 is raised again on call 2 and answered again there. Without this,
+ *  a weaker second answer raised `answers:refused:` beside a close the report
+ *  publishes as answered — the report then said both. `registerPlan` carries
+ *  the previous registration's closes the same way. */
+closedEarlier?: (objectionId: string) => boolean): Objection[];

package/build/recommendation/answers.js

@@ -1,9 +1,34 @@
+import { hasBlocker, refutedEvidence } from "./blockers.js";
+export { BLOCKER_DESCRIPTION } from "./blockers.js";
+/** Whether this answer's blocker closes the objection: present, and not refuted by
+ *  the server's own probe. */
+function blockerCloses(blocker, judge) {
+    if (!hasBlocker(blocker))
+        return false;
+    return !judge || judge(blocker) !== "refuted";
+}
+/** Whether one entry closes an objection that needs a blocker: the SAME rule
+ *  `closingAnswerFor` applies, so a sibling that suppresses a refusal is a sibling
+ *  that really closed. Reading the blocker alone let an entry with a good blocker
+ *  and an empty answer suppress the refusal while closing nothing. */
+function closes(entry, judge) {
+    const answer = entry?.answer;
+    if (typeof answer !== "string" || answer.trim().length === 0)
+        return false;
+    return blockerCloses(entry?.blocker, judge);
+}
 /** The objection raised below carries this prefix and the id it objects to. */
 export const UNKNOWN_ANSWER_PREFIX = "answers:unknown:";
-/** The answer to one objection, matched by `objectionId` and never by position — the
- *  agent reorders its list between registrations. A whitespace-only answer closes
- *  nothing, and the FIRST NON-BLANK entry wins when one id is answered twice. */
-export function answerFor(objection, acknowledged) {
+/** The entry that closed one objection, matched by `objectionId` and never by
+ *  position — the agent reorders its list between registrations. A whitespace-only
+ *  answer closes nothing, and the FIRST NON-BLANK entry wins when one id is
+ *  answered twice. Its `answer` comes back trimmed.
+ *
+ *  The ENTRY, so a caller that files the blocker files the one that arrived with
+ *  THIS answer. Searching for the two separately took them from different entries:
+ *  a blank-answer entry supplied the blocker, and a refuted claim was published
+ *  beside an answer a later entry had closed. */
+export function closingAnswerFor(objection, acknowledged, judge) {
     const wantsBlocker = needsBlocker(objection.objectionId);
     for (const entry of acknowledged) {
         if (entry.objectionId !== objection.objectionId)
@@ -12,12 +37,16 @@ export function answerFor(objection, acknowledged) {
         const answer = typeof rawAnswer === "string" ? rawAnswer.trim() : "";
         if (answer.length === 0)
             continue;
-        if (wantsBlocker && String(entry.blocker ?? "").trim().length === 0)
+        if (wantsBlocker && !blockerCloses(entry.blocker, judge))
             continue;
-        return answer;
+        return { ...entry, answer };
     }
     return undefined;
 }
+/** The closing answer as the sentence alone, for a caller that files no blocker. */
+export function answerFor(objection, acknowledged, judge) {
+    return closingAnswerFor(objection, acknowledged, judge)?.answer;
+}
 /** One objection per answer naming an objection this call did not raise — a stale
  *  id, a typo and a pre-emptive answer all used to pass in silence. An id is
  *  recognised BY ITS PREFIX and never draws an objection of its own. `scope` and
@@ -43,31 +72,50 @@ export function unknownAnswerObjections(objections, acknowledged, { scope, sugge
     }
     return raisedHere;
 }
-/** The one objection an answer does not close. Every other check in v2 can be
- *  answered, and this one cannot: the missed bugs it exists for were reached by
- *  prose twice and skipped twice, so an answer would close the objection and
- *  leave the bug. `verifierContracts.ts` carries the evidence. */
-export const NON_ANSWERABLE_PREFIX = "coverage:stateTest:";
+/** The objections an answer does not close, only a planned test.
+ *
+ *  `coverage:stateTest:` — the missed bugs it exists for were reached by prose twice
+ *  and skipped twice, so an answer would close the objection and leave the bug.
+ *  `verifierContracts.ts` carries the evidence.
+ *
+ *  `defects:untested:` — a declared defect's test can always be written, even when
+ *  the service it runs against is down: it is committed and runs once the service is
+ *  back. Every blocker Wipro repo-1 sent for a defect (14 on one run, 2 on the next)
+ *  named a limit of the browser tools, and none got a test.
+ *
+ *  `defects:expectedPass:` — a test that passes today proves nothing about a defect,
+ *  and a sentence here would let one cited passing test stand in for the red one. */
+export const NON_ANSWERABLE_PREFIXES = [
+    "coverage:stateTest:",
+    "defects:untested:",
+    "defects:expectedPass:",
+];
+const DEFECT_PREFIXES = ["defects:untested:", "defects:expectedPass:"];
 export function isNonAnswerable(objectionId) {
     return (typeof objectionId === "string" &&
-        objectionId.startsWith(NON_ANSWERABLE_PREFIX));
+        NON_ANSWERABLE_PREFIXES.some((prefix) => objectionId.startsWith(prefix)));
 }
 /** The objections a sentence alone does not close either. A change with no test
- *  needs the test, a value a page and API change refuses needs a UI test or a
- *  maintained spec that names it (the XR02 evidence is at `surfaceReject` in
- *  `verifierContracts.ts`), and a defect with no test needs the test — a defect
- *  the code already had before this pull request included. Each closes only when the
- *  answer also names what stopped the test: a service that is not running, a
- *  branch that no longer exists, the one credential the run holds. Measured on run
+ *  needs the test, a value a page and API change accepts or refuses needs a UI step
+ *  that names it (the XR02 evidence is at `surfaceCase` and `surfaceReject` in
+ *  `verifierContracts.ts`). Each closes only when the answer also names what stopped
+ *  the test: a service that is not running, or the one credential the run holds. Measured on run
  *  34176038240: across eight fixtures 45 objections were raised and 45 were
  *  closed, and the one class that a sentence cannot close was never raised at all.
  *  Prose closed every uncovered change, including changes nothing prevented a test
  *  from reaching. Runs 34423214322 and 34423217796 then lost three defects the
- *  baseline reported: each was listed and closed by a sentence. */
+ *  baseline reported: each was listed and closed by a sentence.
+ *
+ *  A bug the report states is the same promise made after the tests run, so it
+ *  closes the same way. Runs 34434835959 (repo15 RG21 and RG15) and 34434838150
+ *  (repo10 RG03) answered three `issueTraceability:` objections with "outside this
+ *  PR's surface" and "unobservable" and wrote no test — and RG21 and RG15 were the
+ *  same 404 bootstrap bug, reported twice and tested neither time. */
 export const BLOCKER_ONLY_PREFIXES = [
     "coverage:change:",
+    "coverage:surfaceCase:",
     "coverage:surfaceReject:",
-    "defects:untested:",
+    "issueTraceability:",
 ];
 export function needsBlocker(objectionId) {
     return (typeof objectionId === "string" &&
@@ -78,7 +126,14 @@ export const REFUSED_ANSWER_PREFIX = "answers:refused:";
 /** One objection per answer to an objection only a planned test closes. The answered
  *  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) {
+export function refusedAnswerObjections(objections, acknowledged, judge, 
+/** Whether an EARLIER call already closed this objection and that close still
+ *  stands. The report tool carries answers across calls, so an objection closed
+ *  on call 1 is raised again on call 2 and answered again there. Without this,
+ *  a weaker second answer raised `answers:refused:` beside a close the report
+ *  publishes as answered — the report then said both. `registerPlan` carries
+ *  the previous registration's closes the same way. */
+closedEarlier) {
     const raised = new Set(objections
         .map((objection) => objection.objectionId)
         .filter((id) => isNonAnswerable(id) || needsBlocker(id)));
@@ -91,21 +146,37 @@ export function refusedAnswerObjections(objections, acknowledged) {
         const answer = entry.answer;
         if (typeof answer !== "string" || answer.trim().length === 0)
             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)
+        // An answer whose blocker the server did not refute DOES close an untested
+        // change. Refused: the sentence on its own, and a claim the probe found untrue.
+        // Read across EVERY entry for this id, not just this one: the agent may send
+        // two, and one of them closing means the objection is closed — refusing on the
+        // other raised a refusal beside a close for the same objection.
+        if (needsBlocker(id) &&
+            (acknowledged.some((other) => other.objectionId === id && closes(other, judge)) ||
+                closedEarlier?.(id))) {
             continue;
+        }
         seen.add(id);
+        const blocker = entry?.blocker;
+        const refutedBlocker = needsBlocker(id) && hasBlocker(blocker) ? blocker : undefined;
         refused.push({
             objectionId: `${REFUSED_ANSWER_PREFIX}${id}`,
             verifier: "answers",
-            message: needsBlocker(id)
-                ? "The answer says why there is no test, and it does not say what stopped this run from writing one, so the objection stays open."
-                : "This objection is closed only by a planned test, so the answer closed nothing and the objection stays open.",
-            evidence: `answered "${id}"${needsBlocker(id) ? " with no `blocker`" : ", which no answer closes"}`,
-            suggestion: needsBlocker(id)
-                ? "Plan the test and register the plan again. If this run cannot write one, send the same answer with `blocker` naming what stopped it — a service that is not running, a paired branch that no longer exists, the one credential the run holds. A reason it is not worth testing is not a blocker."
-                : "Add a planned test that names the record's state as `startState` and runs this route's mutation on it, then register the plan again. Every other objection takes an answer; this one takes a test.",
+            message: refutedBlocker
+                ? "The server checked the blocker this answer names and found the opposite, so the objection stays open."
+                : needsBlocker(id)
+                    ? "The answer says why there is no test, and it does not say what stopped this run from writing one, so the objection stays open."
+                    : "This objection is closed only by a planned test, so the answer closed nothing and the objection stays open.",
+            evidence: refutedBlocker
+                ? `answered "${id}" with \`${refutedBlocker.kind}\`; ${refutedEvidence(refutedBlocker)}`
+                : `answered "${id}"${needsBlocker(id) ? " with no `blocker`" : ", which no answer closes"}`,
+            suggestion: refutedBlocker
+                ? "Write the test: what you named as the blocker is not in the way. If something else is, send the blocker that names it — the server checks each kind against the run it can see."
+                : needsBlocker(id)
+                    ? "Plan the test and register the plan again. If this run cannot write one, send the same answer with `blocker` — `service-unreachable` with the URL, or `credential-missing` with the URL of the page that asked for the login. A reason it is not worth testing is not a blocker."
+                    : DEFECT_PREFIXES.some((prefix) => id.startsWith(prefix))
+                        ? "Plan a test that cites the defect in `defects` and sets `expected.outcome` to `fail`, then register the plan again. If a service the test needs is down, write the test anyway: it is committed and runs once the service is back."
+                        : "Add a planned test that names the record's state as `startState` and runs this route's mutation on it, then register the plan again. Every other objection takes an answer; this one takes a test.",
         });
     }
     return refused;

package/build/recommendation/blockerProbes.d.ts

@@ -0,0 +1,13 @@
+import { BlockerChecks } from "./blockers.js";
+import { PlanBlocker } from "./types.js";
+/** The three checks, resolved. Every await happens HERE, before the plan verifiers
+ *  run: they are synchronous, so a probe cannot be reached from inside one. Each
+ *  distinct URL and branch is probed once however many answers name it.
+ *
+ *  Called by both tools. The plan tool has a `VerifyContext` to hang the result on
+ *  and the report tool does not, so this returns the checks rather than the context. */
+export declare function probeBlockers(blockers: PlanBlocker[]): Promise<BlockerChecks>;
+/** The blockers an answers list carries. */
+export declare function blockersIn(answers: ReadonlyArray<{
+    blocker?: PlanBlocker;
+}>): PlanBlocker[];

package/build/recommendation/blockerProbes.js

@@ -0,0 +1,91 @@
+import { probeUrl } from "./blockers.js";
+import { uiCredentialsSupplied } from "./pullRequestText.js";
+import { capturedBlueprintDigests } from "../playwright/blueprintDigestStore.js";
+import { logger } from "../utils/logger.js";
+/** How long a service gets to answer before the run calls it unreachable. Long
+ *  enough for a container still warming up, short enough that a plan registration
+ *  with several blockers does not stall the agent. */
+const PROBE_TIMEOUT_MS = 5_000;
+/** Whether the service at `url` answered. ANY status counts — a 500 is a service
+ *  that is running, and the claim under test is only that the run could not reach
+ *  it. UNDEFINED is never returned here: a request either gets a response or does
+ *  not, and `verifyBlocker` decides what an unparseable URL means. */
+async function serviceAnswers(url) {
+    for (const method of ["HEAD", "GET"]) {
+        try {
+            await fetch(url, {
+                method,
+                signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+                redirect: "manual",
+            });
+            return true;
+        }
+        catch {
+            // HEAD is refused by some servers that answer GET perfectly well, so a
+            // failure on it is not yet an unreachable service.
+        }
+    }
+    return false;
+}
+/** A URL's path with no trailing slash, or UNDEFINED. The host is not compared: the
+ *  agent writes `localhost` where the capture wrote `127.0.0.1`, and the reverse. */
+function pagePath(raw) {
+    try {
+        const path = new URL(raw).pathname.replace(/\/+$/, "");
+        return path || "/";
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether a capture this run took reached the page at `url` and read elements
+ *  from it. */
+function pageLoaded(url) {
+    const wanted = pagePath(url);
+    return capturedBlueprintDigests().some((capture) => capture.elements.length > 0 && pagePath(capture.url) === wanted);
+}
+/** The three checks, resolved. Every await happens HERE, before the plan verifiers
+ *  run: they are synchronous, so a probe cannot be reached from inside one. Each
+ *  distinct URL and branch is probed once however many answers name it.
+ *
+ *  Called by both tools. The plan tool has a `VerifyContext` to hang the result on
+ *  and the report tool does not, so this returns the checks rather than the context. */
+export async function probeBlockers(blockers) {
+    const urls = new Set();
+    for (const blocker of blockers) {
+        const detail = String(blocker?.detail ?? "").trim();
+        if (!detail)
+            continue;
+        if (blocker.kind === "service-unreachable")
+            urls.add(detail);
+    }
+    const serviceResults = new Map();
+    await Promise.all([
+        ...[...urls].map(async (raw) => {
+            // The SAME filter `verifyBlocker` applies, and it gates the request. Reading
+            // the detail with a bare `new URL` sent the server after whatever the agent
+            // wrote — `file:`, `data:`, a link-local address — and made the verdict a
+            // reachability oracle for anything the URL could name.
+            const url = probeUrl(raw);
+            if (!url)
+                return;
+            serviceResults.set(url, await serviceAnswers(url));
+        }),
+    ]).catch((error) => {
+        // A probe that throws leaves its entry unset, and an unset entry reads as
+        // "could not tell". A blocker must never close because a check crashed, and it
+        // must never be refused for that either.
+        logger.warning(`Blocker probe failed: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    return {
+        serviceAnswers: (url) => serviceResults.get(url),
+        credentialsSupplied: uiCredentialsSupplied(),
+        pageLoaded,
+    };
+}
+/** The blockers an answers list carries. */
+export function blockersIn(answers) {
+    return answers
+        .map((entry) => entry.blocker)
+        .filter((blocker) => blocker !== undefined);
+}

package/build/recommendation/blockers.d.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { PlanBlocker } from "./types.js";
+/** What `blocker` is, in the words both tools' schemas give the agent. One string:
+ *  the plan states the rule before the tests run and the report states it after, and
+ *  two copies drifted the moment either was edited. */
+export declare const BLOCKER_DESCRIPTION = "What stopped this run from writing the test, as one of two claims the server checks: `service-unreachable` with the URL the run needed, or `credential-missing` with the URL of the page the missing login guards. An objection about a change or a reported bug with no test, or about a value a page and API change accepts or refuses that no UI test names, closes only with one of these, and the server probes it \u2014 a claim it finds untrue leaves the objection open. A reason the test is not worth writing is not a blocker. A step that the browser tools cannot record is not a blocker either: record the steps they can, then edit the test file the generator writes and add the missing step yourself.";
+/** The `kind` values, in the schema's own words. */
+export declare const BLOCKER_KIND_DESCRIPTION = "Which of the two checkable things stopped the test. `service-unreachable`: the run could not reach a service it needed. `credential-missing`: the run holds no login for a page the test has to get past.";
+export declare const BLOCKER_DETAIL_DESCRIPTION = "The fact behind the claim: for `service-unreachable` the URL, spelled as the run tried it \u2014 the server requests it; for `credential-missing` the URL of the page that asked for the login \u2014 the server reads it against the pages this run already loaded, and a page the run loaded with no login needs none.";
+/** The blocker both tools take, as the schema that rejects anything else. An
+ *  OBJECT, not a sentence: free text let an argument close an untested defect, and
+ *  each kind here names one fact the server can probe. `.strict()` so an invented
+ *  kind or an extra field fails the schema rather than reading as a claim nothing
+ *  could check. */
+export declare const blockerSchema: z.ZodEffects<z.ZodObject<{
+    kind: z.ZodEnum<["service-unreachable", "credential-missing"]>;
+    detail: z.ZodEffects<z.ZodString, string, string>;
+}, "strict", z.ZodTypeAny, {
+    kind: "service-unreachable" | "credential-missing";
+    detail: string;
+}, {
+    kind: "service-unreachable" | "credential-missing";
+    detail: string;
+}>, {
+    kind: "service-unreachable" | "credential-missing";
+    detail: string;
+}, {
+    kind: "service-unreachable" | "credential-missing";
+    detail: string;
+}>;
+/** What the server made of a blocker's claim.
+ *
+ *  `refuted` is the one that costs the agent something: the probe found the
+ *  opposite of what the blocker said, so the answer closes nothing. `unverifiable`
+ *  is not a soft refusal — it is the server saying it could not look, which is
+ *  where every close stood before these checks existed. */
+export type BlockerVerdict = "verified" | "refuted" | "unverifiable";
+/** The three probes, INJECTED so this module reaches neither the network nor the
+ *  filesystem — the same rule `VerifyContext.citedFileExists` follows. Each returns
+ *  UNDEFINED when it could not tell, which is a verdict of its own and never a
+ *  silent pass. */
+export interface BlockerChecks {
+    /** Whether the service at this URL answered an HTTP request. Any status counts:
+     *  a 500 is a service that is running. */
+    serviceAnswers(url: string): boolean | undefined;
+    /** Whether the run was given browser credentials. */
+    credentialsSupplied: boolean | undefined;
+    /** Whether a page capture this run took reached this URL's page and read its
+     *  elements. A page that redirected to a login reports the login's URL. */
+    pageLoaded(url: string): boolean | undefined;
+}
+/** Whether an answer carries a blocker at all: a kind the schema knows and a detail
+ *  that says something. Read defensively — the plan comes off disk, so the declared
+ *  type holds only on the validated path. */
+export declare function hasBlocker(blocker: unknown): blocker is PlanBlocker;
+/** The blocker as one line, for a report field and an objection's evidence. */
+export declare function blockerText(blocker: PlanBlocker): string;
+/** An http(s) URL the probe can be pointed at, or UNDEFINED. A detail that is not
+ *  one is not a wrong claim — it is a claim nothing can be made of. */
+export declare function probeUrl(detail: string): string | undefined;
+/** What the server made of this blocker. Pure: every fact comes from `checks`. */
+export declare function verifyBlocker(blocker: PlanBlocker, checks: BlockerChecks): BlockerVerdict;
+/** What the server saw, in the words the refusal quotes back. Only ever called on a
+ *  `refuted` verdict, so each branch states the opposite of the claim. */
+export declare function refutedEvidence(blocker: PlanBlocker): string;