@skyramp/mcp 0.4.3-rc.2 → 0.4.4-rc.1

package/build/recommendation/blockers.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+/** 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 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 — 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 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 const BLOCKER_DETAIL_DESCRIPTION = "The fact behind the claim: for `service-unreachable` the URL, spelled as the run tried it — the server requests it; for `credential-missing` the URL of the page that asked for the login — 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 const blockerSchema = z
+    .object({
+    kind: z
+        .enum(["service-unreachable", "credential-missing"])
+        .describe(BLOCKER_KIND_DESCRIPTION),
+    detail: z
+        .string()
+        .refine((value) => value.trim().length > 0, {
+        message: "a blocker's detail must not be blank",
+    })
+        .describe(BLOCKER_DETAIL_DESCRIPTION),
+})
+    .strict()
+    // A detail the server cannot make anything of used to be accepted and then called
+    // `unverifiable`, which closes — so `service-unreachable: outside this PR` was the
+    // free-text escape this schema exists to remove. Each kind states its detail in the
+    // shape its check takes, or the plan is refused here. `credential-missing` was a
+    // sentence, and it closed an XR02 page objection on a page that needs no login.
+    .superRefine((blocker, ctx) => {
+    const detail = String(blocker?.detail ?? "").trim();
+    if (!detail || probeUrl(detail))
+        return;
+    ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["detail"],
+        message: blocker.kind === "credential-missing"
+            ? "a `credential-missing` detail is the URL of the page that asked for the login, with an `http://` or `https://` scheme — the server reads it against the pages this run loaded."
+            : "a `service-unreachable` detail is the URL the run tried, with an `http://` or `https://` scheme — the server requests it. A cloud metadata address is not requested.",
+    });
+});
+/** 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 function hasBlocker(blocker) {
+    const kind = blocker?.kind;
+    const detail = blocker?.detail;
+    return ((kind === "service-unreachable" || kind === "credential-missing") &&
+        typeof detail === "string" &&
+        detail.trim().length > 0);
+}
+/** The blocker as one line, for a report field and an objection's evidence. */
+export function blockerText(blocker) {
+    return `${blocker.kind}: ${String(blocker.detail ?? "").trim()}`;
+}
+/** The addresses a probe must never be pointed at: the cloud metadata endpoint, in
+ *  the two spellings it wears. The service under test runs on the runner, so
+ *  loopback, `host.docker.internal` and the private ranges stay reachable — they
+ *  are the probe's whole purpose. Only the link-local range, which serves nothing
+ *  a test needs and serves instance credentials on every major cloud, is closed. */
+function isMetadataAddress(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    // 169.254.0.0/16, the same range mapped into IPv6 (the URL parser writes it as
+    // `::ffff:a9fe:…`), and fe80::/10 written as any of its four leading nibbles.
+    if (/^169\.254\./.test(host) ||
+        /^::ffff:a9fe:/.test(host) ||
+        /^fe[89ab][0-9a-f]:/.test(host))
+        return true;
+    return host === "metadata" || host === "metadata.google.internal";
+}
+/** 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 function probeUrl(detail) {
+    try {
+        const url = new URL(detail.trim());
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return undefined;
+        // `fetch` throws on a URL with a login in it, which would read as unreachable.
+        if (url.username || url.password)
+            return undefined;
+        return isMetadataAddress(url.hostname) ? undefined : url.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** What the server made of this blocker. Pure: every fact comes from `checks`. */
+export function verifyBlocker(blocker, checks) {
+    const detail = String(blocker?.detail ?? "").trim();
+    switch (blocker?.kind) {
+        case "service-unreachable": {
+            const url = probeUrl(detail);
+            if (!url)
+                return "unverifiable";
+            const answered = checks?.serviceAnswers(url);
+            return answered === undefined
+                ? "unverifiable"
+                : answered
+                    ? "refuted"
+                    : "verified";
+        }
+        case "credential-missing": {
+            // The run records ONE opaque credentials string, so `true` says a login was
+            // supplied and nothing about which one — and that login may be what let a
+            // capture reach the page. Only `false` states a fact about the claim, and then
+            // a capture of the page says the page needed no login.
+            const url = probeUrl(detail);
+            if (!url || checks?.credentialsSupplied !== false)
+                return "unverifiable";
+            const loaded = checks?.pageLoaded(url);
+            return loaded === undefined
+                ? "unverifiable"
+                : loaded
+                    ? "refuted"
+                    : "verified";
+        }
+        default:
+            return "unverifiable";
+    }
+}
+/** 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 function refutedEvidence(blocker) {
+    const detail = String(blocker?.detail ?? "").trim();
+    switch (blocker?.kind) {
+        case "service-unreachable":
+            return `${detail} answered an HTTP request, so the service is running`;
+        case "credential-missing":
+            return `this run loaded ${detail} with no login and read its elements, so the page needs none`;
+        default:
+            return blockerText(blocker);
+    }
+}

package/build/recommendation/pullRequestText.d.ts

@@ -9,6 +9,8 @@ export declare function pullRequestText(): {
     description: string;
 } | undefined;
 export declare function clearPullRequestText(): void;
+export declare function recordUiCredentials(value: unknown): void;
+export declare function uiCredentialsSupplied(): boolean | undefined;
 /** The pull request as one searchable string. Whitespace runs fold to one space, so
  *  a quote wrapped across lines still matches the sentence it was taken from. */
 export declare const searchable: (pr: {

package/build/recommendation/pullRequestText.js

@@ -21,6 +21,22 @@ export function pullRequestText() {
 }
 export function clearPullRequestText() {
     recorded = undefined;
+    credentialsSupplied = undefined;
+}
+/** Whether the run was given browser credentials, recorded from the same place and
+ *  for the same reason as the text above: the prompt and the plan tool share a
+ *  process, so the flag is already here. A blocker of kind `credential-missing`
+ *  is checked against it.
+ *
+ *  UNDEFINED when this process never rendered the prompt, which is not `false` —
+ *  the server cannot tell a run with no credentials from a run it never saw, and
+ *  the blocker is then unverifiable rather than true. */
+let credentialsSupplied;
+export function recordUiCredentials(value) {
+    credentialsSupplied = typeof value === "string" && value.trim().length > 0;
+}
+export function uiCredentialsSupplied() {
+    return credentialsSupplied;
 }
 /** The pull request as one searchable string. Whitespace runs fold to one space, so
  *  a quote wrapped across lines still matches the sentence it was taken from. */

package/build/recommendation/registerPlan.d.ts

@@ -1,4 +1,4 @@
-import { Objection, ObjectionAnswer, PlanChange, PlanDefect, PlanInput, PlanMaintenance, PlannedTest, VerifyContext } from "./types.js";
+import { Objection, ObjectionAnswer, PlanBlocker, PlanChange, PlanDefect, PlanInput, PlanMaintenance, PlannedTest, VerifyContext } from "./types.js";
 /** The plan as stored for the run. Every registration produces one; the newest
  *  replaces the last. */
 export interface Plan {
@@ -14,11 +14,14 @@ export interface Plan {
      *  `coverage` counts the changes they cite, so a reader of the plan has to be
      *  able to see which coverage came from maintenance rather than a new test. */
     maintains?: PlanMaintenance[];
-    /** Objections the agent answered, with the answers. */
+    /** Objections the agent answered, with the answers. A `blocker` here is one the
+     *  server PROBED and could not refute — an unreachable service that really did not
+     *  answer, a branch that really is gone — so the close is a checked one. */
     answeredObjections: Array<{
         objection: Objection;
         answer: string;
-        blocker?: string;
+        blocker?: PlanBlocker;
+        blockerVerified?: boolean;
     }>;
     /** Closed by a blocker nothing checked. Its own bucket rather than a flag on
      *  `answeredObjections`, so a run's count of them is a number the report can
@@ -29,7 +32,7 @@ export interface Plan {
     unverifiedCloses: Array<{
         objection: Objection;
         answer: string;
-        blocker: string;
+        blocker: PlanBlocker;
     }>;
     /** Objections with no answer. Rendered in the report — this is the accountability. */
     openObjections: Objection[];

package/build/recommendation/registerPlan.js

@@ -1,4 +1,5 @@
-import { answerFor, isNonAnswerable, refusedAnswerObjections, unknownAnswerObjections, } from "./answers.js";
+import { hasBlocker } from "./blockers.js";
+import { answerFor, closingAnswerFor, isNonAnswerable, refusedAnswerObjections, unknownAnswerObjections, } from "./answers.js";
 import { runPlanTimeVerifiers } from "./runVerifiers.js";
 import { logger } from "../utils/logger.js";
 function storedRegistrationNumber(registration) {
@@ -37,7 +38,7 @@ function carriedAnswerFor(objectionId, previous) {
             return {
                 objectionId,
                 answer,
-                ...(entry.blocker ? { blocker: entry.blocker } : {}),
+                ...(hasBlocker(entry.blocker) ? { blocker: entry.blocker } : {}),
             };
     }
     return undefined;
@@ -65,6 +66,9 @@ export function registerPlan(registration, ctx, previous) {
     const changes = registration.changes;
     const defects = registration.defects;
     const registrationNumber = storedRegistrationNumber(registration);
+    // Awaited by the caller before this context was built: every probe is an HTTP
+    // request or a `git` call, and nothing from here down is asynchronous.
+    const judge = ctx?.blockerVerdict?.bind(ctx);
     const verified = runPlanTimeVerifiers(registration, ctx);
     const objections = [
         ...verified,
@@ -72,7 +76,15 @@ export function registerPlan(registration, ctx, previous) {
             scope: "on this plan",
             suggestion: "Answer only the ids in the Objections list this registration returns. An objection you have since fixed is gone and needs no answer, and an objection raised after the tests run cannot be answered before them.",
         }),
-        ...refusedAnswerObjections(verified, acknowledged),
+        ...refusedAnswerObjections(verified, acknowledged, judge, (id) => {
+            // The previous registration's close is carried below when this answer does
+            // not close. If that carried close still stands, it is the close.
+            const objection = verified.find((o) => o.objectionId === id);
+            const carried = carriedAnswerFor(id, previous);
+            return (!!objection &&
+                !!carried &&
+                !!closingAnswerFor(objection, [carried], judge));
+        }),
     ];
     const carried = carriedAnswers(objections, acknowledged, previous);
     // The carried answers go last: `answerFor` takes the first non-blank entry, so
@@ -87,15 +99,29 @@ 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)
+        const closing = 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;
-            // 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)
+            : closingAnswerFor(objection, answers, judge);
+        if (closing) {
+            const answer = closing.answer;
+            // The blocker that arrived with THIS answer. Searching for it apart from the
+            // answer took the two from different entries, and filed a refuted blocker,
+            // or one no answer closed, as the close.
+            const blocker = hasBlocker(closing.blocker) && judge?.(closing.blocker) !== "refuted"
+                ? closing.blocker
+                : undefined;
+            // A blocker the server PROBED and could not refute is a checked close and sits
+            // with the answers. One nothing could look at is counted apart: a run whose
+            // objections all close that way must not read like one that answered.
+            if (blocker && judge?.(blocker) === "verified") {
+                answeredObjections.push({
+                    objection,
+                    answer,
+                    blocker,
+                    blockerVerified: true,
+                });
+            }
+            else if (blocker)
                 unverifiedCloses.push({ objection, answer, blocker });
             else
                 answeredObjections.push({ objection, answer });

package/build/recommendation/types.d.ts

@@ -164,13 +164,24 @@ export interface PlannedTest {
      *  included — the name is what joins the test to the diff it is checked against. */
     repository: string;
 }
+/** The kinds of thing that stop a run from writing a test AND that the server can
+ *  check. Free text let an argument close an untested defect — run 34434835959
+ *  closed one with "the PR description states no redirect or fallback" — so a
+ *  blocker is now a claim of one of these, and the server probes it. */
+export type PlanBlockerKind = "service-unreachable" | "credential-missing";
+/** What stopped this run from writing the test, as a checkable claim. */
+export interface PlanBlocker {
+    kind: PlanBlockerKind;
+    /** `service-unreachable`: the URL the run needed. `credential-missing`: the URL
+     *  of the page that asked for the login. */
+    detail: string;
+}
 export interface ObjectionAnswer {
     objectionId: string;
     answer: string;
-    /** What stopped this run from writing the test: a service that is not running,
-     *  a paired branch that no longer exists, the one credential the run holds.
-     *  An objection about an untested change closes only with one of these. */
-    blocker?: string;
+    /** What stopped this run from writing the test. An objection about an untested
+     *  change, an untested defect or a reported bug closes only with one. */
+    blocker?: PlanBlocker;
 }
 /** An existing test this run maintains instead of planning a new one, and the
  *  declared changes that maintenance covers. A removal already covered by a spec
@@ -255,6 +266,12 @@ export interface VerifyContext {
      *  the verifiers filesystem-free. Named a repository it asks that one, and a name
      *  this run does not know answers false. Omitted, it asks every one. */
     citedFileExists(relativePath: string, repository?: string): boolean;
+    /** What the server made of one answer's blocker. Injected for the same reason as
+     *  `citedFileExists`, and more so: the probes are HTTP requests and `git` calls,
+     *  and they are awaited before this context is built because the verifiers are
+     *  synchronous. UNDEFINED where the caller ran no probes — every blocker then
+     *  reads as unverifiable, which is where they all stood before the checks. */
+    blockerVerdict?(blocker: PlanBlocker): "verified" | "refuted" | "unverifiable";
     /** The text of a `spec:` file a plan change cites, from the first repository that
      *  holds it. UNDEFINED for a path no repository holds, a path outside every
      *  checkout, or a file too large to read. Injected for the same reason as

package/build/recommendation/verifierContracts.d.ts

@@ -126,7 +126,7 @@ export declare const EXPECTED_OUTCOME_CONTRACT: {
         };
         readonly executed: {
             readonly message: "This test failed, but it did not reach the behavior it was written for — it fell over earlier. A failure like this is not a caught bug.";
-            readonly suggestion: "If the blocker is the test's own setup — sign-in, token, a wrong path — fix it and run the test again. If the blocker is the defect this run reports (a route that is not mounted, a server error before the behaviour), answer this objection naming that issue: the failure then stands as evidence of that issue, not as a caught bug.";
+            readonly suggestion: "If the blocker is the test's own setup — sign-in, token, a wrong path — fix it and run the test again. If the blocker is the defect this run reports (a route that is not mounted, a server error before the behaviour), answer this objection naming that issue: the failure then stands as evidence of that issue, not as a caught bug. If a service the test needs is down, answer this objection and set `blocker` to `service-unreachable` with the URL: the test stays committed and runs once the service is back.";
         };
     };
     readonly suggestion: "Should this test fail until the defect is fixed, or is the category wrong for a test that pins behaviour the app already has?";
@@ -158,7 +158,7 @@ export declare const COVERAGE_CONTRACT: {
     readonly objections: {
         readonly change: {
             readonly message: "This declared change has no test in the plan.";
-            readonly suggestion: "Plan a test that exercises it. If an existing test already covers it and this run edits that test rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this change's id — maintenance is coverage, and a duplicate spec beside the one you edited is the mistake. If this run cannot write one, answer it and set `blocker` to what stopped the run — a service that is not running, a paired branch that no longer exists, the one credential the run holds. An answer with no blocker leaves this open: a change nothing prevented a test from reaching takes the test. Coverage per file is the basic minimum; coverage per change is what the plan is judged by, so a file covered by a shape test still leaves the change it makes untested.";
+            readonly suggestion: "Plan a test that exercises it. If an existing test already covers it and this run edits that test, or runs it unchanged as a VERIFY, rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this change's id — maintenance is coverage, and a duplicate spec beside the one you edited is the mistake. If this run cannot write one, answer it and set `blocker` to what stopped the run — a service that is not running, the one credential the run holds. An answer with no blocker leaves this open: a change nothing prevented a test from reaching takes the test. Coverage per file is the basic minimum; coverage per change is what the plan is judged by, so a file covered by a shape test still leaves the change it makes untested.";
         };
         readonly noChanges: {
             readonly message: "The plan declares no changes, so nothing says what the pull request must make different.";
@@ -190,11 +190,11 @@ export declare const COVERAGE_CONTRACT: {
         };
         readonly surfaceCase: {
             readonly message: "This change is on the page and the API, and no ui or e2e test that cites it chooses `{case}` on the page.";
-            readonly suggestion: "Add a ui or e2e test, or a step in one, that chooses that value on the page and names it in the step, as in `Principal radio`, or answer in one line why the page cannot send it.";
+            readonly suggestion: "Add a ui or e2e test, or a step in one, that chooses that value on the page and names it in the step. If this run cannot write the test, answer it and set `blocker` to what stopped the run; an answer with no blocker leaves this open.";
         };
         readonly surfaceReject: {
             readonly message: "This change is on the page and the API, and no ui or e2e test that cites it tries `{case}` on the page or checks that the page no longer offers it.";
-            readonly suggestion: "Add a ui or e2e test, or a step in one, that names that value in the step, as in `Intern radio absent`: try it and assert the page refuses it, or assert the page no longer offers it. If an existing UI spec already does this and this run edits it, declare it in `maintains` with its real path and name the value in `differsBy`. If this run cannot write the test, answer it and set `blocker` to what stopped the run; an answer with no blocker leaves this open.";
+            readonly suggestion: "Add a ui or e2e test, or a step in one, that names that value in the step: try it and assert the page refuses it, or assert the page no longer offers it. If this run cannot write the test, answer it and set `blocker` to what stopped the run; an answer with no blocker leaves this open.";
         };
     };
     readonly suggestion: "Which planned test tests each behaviour this change promises and each file it touches, and for one nothing covers, why does it need none?";
@@ -302,11 +302,11 @@ export declare const DEFECTS_CONTRACT: {
         };
         readonly untested: {
             readonly message: "This declared defect has no test in the plan.";
-            readonly suggestion: "Add a planned test that cites the defect in `defects` and sets `expected.outcome` to `fail`. A defect in a file this pull request touches gets the test whether or not this pull request introduced it. If an existing test already proves it and this run edits that test rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this defect's id — maintenance is proof, and a duplicate spec beside the one you edited is the mistake. If something stopped this run from writing the test, answer it and set `blocker` to what stopped it.";
+            readonly suggestion: "Add a planned test that cites the defect in `defects` and sets `expected.outcome` to `fail`. A defect in a file this pull request touches gets the test whether or not this pull request introduced it. If an existing test already proves it and this run edits that test, or runs it unchanged as a VERIFY, rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this defect's id — maintenance is proof, and a duplicate spec beside the one you edited is the mistake. Only a test closes this objection. If a service the test needs is down, write the test anyway: it is committed and runs once the service is back.";
         };
         readonly expectedPass: {
             readonly message: "Every test that cites this defect expects to pass, and a test that passes today proves nothing about a defect.";
-            readonly suggestion: "Assert what the fixed code returns, set `expected.outcome` to `fail` with `why`, or answer in one line why a passing test is the proof.";
+            readonly suggestion: "Assert what the fixed code returns and set `expected.outcome` to `fail` with `why`. Only a test that expects to fail closes this objection.";
         };
         readonly unknownId: {
             readonly message: "A planned test cites a defect id that this plan does not declare.";

package/build/recommendation/verifierContracts.js

@@ -114,7 +114,7 @@ export const EXPECTED_OUTCOME_CONTRACT = {
         // 33988304641, P11), which the run that wrote `true` never drew.
         executed: {
             message: "This test failed, but it did not reach the behavior it was written for — it fell over earlier. A failure like this is not a caught bug.",
-            suggestion: "If the blocker is the test's own setup — sign-in, token, a wrong path — fix it and run the test again. If the blocker is the defect this run reports (a route that is not mounted, a server error before the behaviour), answer this objection naming that issue: the failure then stands as evidence of that issue, not as a caught bug.",
+            suggestion: "If the blocker is the test's own setup — sign-in, token, a wrong path — fix it and run the test again. If the blocker is the defect this run reports (a route that is not mounted, a server error before the behaviour), answer this objection naming that issue: the failure then stands as evidence of that issue, not as a caught bug. If a service the test needs is down, answer this objection and set `blocker` to `service-unreachable` with the URL: the test stays committed and runs once the service is back.",
         },
     },
     suggestion: "Should this test fail until the defect is fixed, or is the category wrong for a test that pins behaviour the app already has?",
@@ -149,7 +149,7 @@ export const COVERAGE_CONTRACT = {
     objections: {
         change: {
             message: "This declared change has no test in the plan.",
-            suggestion: "Plan a test that exercises it. If an existing test already covers it and this run edits that test rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this change's id — maintenance is coverage, and a duplicate spec beside the one you edited is the mistake. If this run cannot write one, answer it and set `blocker` to what stopped the run — a service that is not running, a paired branch that no longer exists, the one credential the run holds. An answer with no blocker leaves this open: a change nothing prevented a test from reaching takes the test. Coverage per file is the basic minimum; coverage per change is what the plan is judged by, so a file covered by a shape test still leaves the change it makes untested.",
+            suggestion: "Plan a test that exercises it. If an existing test already covers it and this run edits that test, or runs it unchanged as a VERIFY, rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this change's id — maintenance is coverage, and a duplicate spec beside the one you edited is the mistake. If this run cannot write one, answer it and set `blocker` to what stopped the run — a service that is not running, the one credential the run holds. An answer with no blocker leaves this open: a change nothing prevented a test from reaching takes the test. Coverage per file is the basic minimum; coverage per change is what the plan is judged by, so a file covered by a shape test still leaves the change it makes untested.",
         },
         noChanges: {
             message: "The plan declares no changes, so nothing says what the pull request must make different.",
@@ -203,17 +203,18 @@ export const COVERAGE_CONTRACT = {
             suggestion: "Add a test on that surface that cites this change, or answer in one line why that surface needs no test.",
         },
         // `{case}` is the rendered case, as in `level="Principal" (accept)`. SKYR-4529: a form offered Lead and Principal, and
-        // only an API test sent Principal.
+        // only an API test sent Principal. SKYR-4554: a later XR02 run closed this with "a third red for one defect adds
+        // nothing", and no UI test saved Principal.
         surfaceCase: {
             message: "This change is on the page and the API, and no ui or e2e test that cites it chooses `{case}` on the page.",
-            suggestion: "Add a ui or e2e test, or a step in one, that chooses that value on the page and names it in the step, as in `Principal radio`, or answer in one line why the page cannot send it.",
+            suggestion: "Add a ui or e2e test, or a step in one, that chooses that value on the page and names it in the step. If this run cannot write the test, answer it and set `blocker` to what stopped the run; an answer with no blocker leaves this open.",
         },
         // `{case}` is the rendered case, as in `level="Principal" (accept)`. The XR02 run removed Intern from a form; the page
         // objection closed by a sentence, and no generated test checked the option was
         // gone.
         surfaceReject: {
             message: "This change is on the page and the API, and no ui or e2e test that cites it tries `{case}` on the page or checks that the page no longer offers it.",
-            suggestion: "Add a ui or e2e test, or a step in one, that names that value in the step, as in `Intern radio absent`: try it and assert the page refuses it, or assert the page no longer offers it. If an existing UI spec already does this and this run edits it, declare it in `maintains` with its real path and name the value in `differsBy`. If this run cannot write the test, answer it and set `blocker` to what stopped the run; an answer with no blocker leaves this open.",
+            suggestion: "Add a ui or e2e test, or a step in one, that names that value in the step: try it and assert the page refuses it, or assert the page no longer offers it. If this run cannot write the test, answer it and set `blocker` to what stopped the run; an answer with no blocker leaves this open.",
         },
     },
     suggestion: "Which planned test tests each behaviour this change promises and each file it touches, and for one nothing covers, why does it need none?",
@@ -374,11 +375,11 @@ export const DEFECTS_CONTRACT = {
         },
         untested: {
             message: "This declared defect has no test in the plan.",
-            suggestion: "Add a planned test that cites the defect in `defects` and sets `expected.outcome` to `fail`. A defect in a file this pull request touches gets the test whether or not this pull request introduced it. If an existing test already proves it and this run edits that test rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this defect's id — maintenance is proof, and a duplicate spec beside the one you edited is the mistake. If something stopped this run from writing the test, answer it and set `blocker` to what stopped it.",
+            suggestion: "Add a planned test that cites the defect in `defects` and sets `expected.outcome` to `fail`. A defect in a file this pull request touches gets the test whether or not this pull request introduced it. If an existing test already proves it and this run edits that test, or runs it unchanged as a VERIFY, rather than writing a new one, declare it in `maintains` with the file, what your edit changes, and this defect's id — maintenance is proof, and a duplicate spec beside the one you edited is the mistake. Only a test closes this objection. If a service the test needs is down, write the test anyway: it is committed and runs once the service is back.",
         },
         expectedPass: {
             message: "Every test that cites this defect expects to pass, and a test that passes today proves nothing about a defect.",
-            suggestion: "Assert what the fixed code returns, set `expected.outcome` to `fail` with `why`, or answer in one line why a passing test is the proof.",
+            suggestion: "Assert what the fixed code returns and set `expected.outcome` to `fail` with `why`. Only a test that expects to fail closes this objection.",
         },
         unknownId: {
             message: "A planned test cites a defect id that this plan does not declare.",

package/build/recommendation/verifiers/citedPath.d.ts

@@ -3,8 +3,8 @@ import { PlanMaintenance, VerifyContext } from "../types.js";
 /** Whether a `maintains` entry names a file that stays inside the repository and is
  *  present in the repository the entry names.
  *
- *  An entry credits its ids only when it is. `coverage:change:` and
- *  `defects:untested:` close only with a blocker, so crediting a file nobody can
+ *  An entry credits its ids only when it is. `coverage:change:` closes only with a
+ *  blocker and `defects:untested:` only with a test, so crediting a file nobody can
  *  open would route around both. */
 export declare function maintainedFileIsInItsRepository(entry: PlanMaintenance, ctx: VerifyContext): boolean;
 /** A cited path reduced to the spelling `git diff --name-status` produces: `./`,

package/build/recommendation/verifiers/citedPath.js

@@ -3,8 +3,8 @@ import { escapesRepo } from "./endpointGrounded.js";
 /** Whether a `maintains` entry names a file that stays inside the repository and is
  *  present in the repository the entry names.
  *
- *  An entry credits its ids only when it is. `coverage:change:` and
- *  `defects:untested:` close only with a blocker, so crediting a file nobody can
+ *  An entry credits its ids only when it is. `coverage:change:` closes only with a
+ *  blocker and `defects:untested:` only with a test, so crediting a file nobody can
  *  open would route around both. */
 export function maintainedFileIsInItsRepository(entry, ctx) {
     const path = entry.file.trim();

package/build/recommendation/verifiers/coverage.js

@@ -744,27 +744,24 @@ const REFUSING_VERBS = new Set([
     "assert",
 ]);
 /** The text that can name a value on the page: the steps of the UI tests whose verb
- *  is in `verbs`, and the edit note of each maintained spec, which is prose with no
- *  verb to read. */
-function pageTexts(uiTests, maintained, verbs) {
-    return [
-        ...uiTests.flatMap((plannedTest) => plannedTest.scenario.steps
-            .filter((step) => verbs.has(normalizeStepMethod(step.method) ?? ""))
-            .flatMap((step) => [step.path, step.description ?? ""])),
-        ...maintained.map((entry) => entry.differsBy),
-    ];
+ *  is in `verbs`. A maintained spec's edit note is prose with no verb to read: an
+ *  XR02 note named Principal in "4 radios (incl. Principal) render" and Intern in
+ *  "switches from the removed Intern radio", and neither chose or refused it. */
+function pageTexts(uiTests, verbs) {
+    return uiTests.flatMap((plannedTest) => plannedTest.scenario.steps
+        .filter((step) => verbs.has(normalizeStepMethod(step.method) ?? ""))
+        .flatMap((step) => [step.path, step.description ?? ""]));
 }
 /** A change on the page AND the API needs each accepted value chosen on the page,
  *  and each refused value tried or shown absent there, not only sent by an API
  *  test. `surfaceObjections` passes the page once any UI test cites the change,
  *  whatever value it picks. A UI step is free text (`Senior radio`), so the check
  *  reads whether a page step of a citing ui or e2e test that chooses the value (or,
- *  for a refused one, asserts it), or the `differsBy` of a citing maintained spec,
- *  names the value.
+ *  for a refused one, asserts it) names the value.
  *
- *  A refused value takes a test, a resolving maintained spec, or a blocker, never a
- *  sentence: in the XR02 run the page objection for a removed option closed by
- *  prose, and only an existing spec checked that the option was gone. */
+ *  Either value takes a UI test step or a blocker, never a
+ *  sentence: in XR02 runs the page objection for a removed option and for an added
+ *  one each closed by prose, and no generated test checked that value on the page. */
 function surfaceCaseObjections(registration, ctx) {
     const objections = [];
     const seen = new Set();
@@ -777,15 +774,15 @@ function surfaceCaseObjections(registration, ctx) {
         const uiTests = registration.plannedTests.filter((plannedTest) => citesChange(plannedTest, id) &&
             pageTypes.has(plannedTest.scenario.testType.toLowerCase()));
         // A maintained spec counts only when its file resolves, the bar
-        // `citedBehaviors` sets: the refused half closes by no sentence, so a note on a
-        // file nobody can open must not close it either.
+        // `citedBehaviors` sets. It decides whether the values are checked, never
+        // whether one is met.
         const maintained = (registration.maintains ?? []).filter((entry) => entry.changes.some((cited) => cited.trim() === id) &&
             maintainedFileIsInItsRepository(entry, ctx));
         const citedAtAll = maintained.length > 0 ||
             registration.plannedTests.some((plannedTest) => citesChange(plannedTest, id));
         const texts = {
-            surfaceCase: pageTexts(uiTests, maintained, CHOOSING_VERBS),
-            surfaceReject: pageTexts(uiTests, maintained, REFUSING_VERBS),
+            surfaceCase: pageTexts(uiTests, CHOOSING_VERBS),
+            surfaceReject: pageTexts(uiTests, REFUSING_VERBS),
         };
         for (const testCase of change.testCases ?? []) {
             const kind = pageObjectionKind(testCase);
@@ -817,19 +814,22 @@ function surfaceCaseObjections(registration, ctx) {
             if (seen.has(key))
                 continue;
             seen.add(key);
-            const citers = [
-                ...uiTests.map((plannedTest) => plannedTest.plannedTestId),
-                ...maintained.map((entry) => entry.file),
-            ];
+            const citers = uiTests.map((plannedTest) => plannedTest.plannedTestId);
+            // A maintained spec has no steps to name the value, so say its note is not
+            // read rather than fault it for a step it cannot carry.
+            const notes = maintained.length > 0
+                ? ` The edit note of ${maintained.map((entry) => entry.file).join(", ")} is not read.`
+                : "";
             objections.push({
                 objectionId,
                 verifier: "coverage",
                 message: fillPlaceholders(COVERAGE_CONTRACT.objections[kind].message, {
                     case: rendered,
                 }),
-                evidence: citers.length === 0
-                    ? `No ui or e2e test or maintained spec cites ${id}.`
-                    : `${citers.join(", ")} cite ${id}; no step or maintained edit of theirs names ${word}.`,
+                evidence: (citers.length === 0
+                    ? `No ui or e2e test cites ${id}.`
+                    : `${citers.join(", ")} cite ${id}; no page step of theirs names ${word}.`) +
+                    notes,
                 suggestion: COVERAGE_CONTRACT.objections[kind].suggestion,
             });
         }

package/build/recommendation/verifiers/deliveredMatchesPlan.js

@@ -81,9 +81,9 @@ export function checkMaintenanceDelivered(plan, maintained) {
         objections.push({
             objectionId,
             verifier: "deliveredMatchesPlan",
-            message: "The plan says this existing test covers a change, and no maintenance row says it was edited.",
-            evidence: `plan maintains ${file}; the maintenance rows that changed a file name ${editedPaths.length > 0 ? editedPaths.join(", ") : "no file"}`,
-            suggestion: "The maintenance rows come from the triage, not from this call, so this is not a field to fill in here: make the edit on the file you claimed and let the maintenance step record it, or drop the entry from `maintains` and register the plan again — coverage counted the change because the plan said you were editing that test. If the test already covered the change and needed no edit, or the edit landed somewhere the rows do not name, say which as the answer.",
+            message: "The plan says this existing test covers a change, and no maintenance row says it was edited or run unchanged after the edits.",
+            evidence: `plan maintains ${file}; the maintenance rows that edited or ran a file name ${editedPaths.length > 0 ? editedPaths.join(", ") : "no file"}`,
+            suggestion: 'The maintenance rows come from the triage, not from this call, so this is not a field to fill in here: make the edit on the file you claimed and let the maintenance step record it, run a file you marked VERIFY with `skyramp_execute_test` and `phase: "after"`, or drop the entry from `maintains` and register the plan again — coverage counted the change because the plan said you were editing that test. If the test already covered the change and needed no edit, or the edit landed somewhere the rows do not name, say which as the answer.',
         });
     }
     return objections;

package/build/recommendation/verifiers/issueTraceability.d.ts

@@ -46,11 +46,7 @@ export interface TraceabilityLane {
  *  accepted that entry — the same claim a planned test makes. See
  *  {@link maintainedDefects} for how that acceptance is read.
  *  `deliveredMatchesPlan:maintains:` checks separately that the edit landed.
- *
- *  A declared `defectId` also counts when the agent answered `defects:untested:<id>`
- *  at plan time (or closed it with a blocker). The plan-time verifier asked why no
- *  test proves that defect and the agent said; asking again here is the same
- *  question twice, and the answer is already published with the plan. */
+ */
 export declare function checkIssueTraceability(plan: Plan, delivered: DeliveredForTraceability[], issues: ReportedIssueForTraceability[], lane?: TraceabilityLane): Objection[];
 /** Report-time. Every defect the plan declared is an `issuesFound` entry that
  *  names it by `defectId`. The review found it; the report must show it. */