@skyramp/mcp 0.3.8 → 0.4.0-rc.1

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

@@ -0,0 +1,17 @@
+import { Verifier } from "../types.js";
+/** A path that leaves the checkout, in any of its spellings. Callers pass a
+ *  trimmed path: " ../routes.rb" splits to [" ..", "routes.rb"], so no segment
+ *  equals ".." and one leading space would carry it through. */
+export declare function escapesRepo(file: string): boolean;
+export declare const NOT_SOURCE_DIR: RegExp;
+/** What plainly cannot define a route. A DENY list on purpose: an allowlist would
+ *  rebuild the framework wall this verifier removes. When in doubt ALLOW — a false
+ *  accept costs one unfounded citation, a false reject a whole framework. */
+export declare const NOT_A_ROUTE_FILE: RegExp;
+/** Lockfiles, including the two that end in an allowed extension. */
+export declare const LOCKFILE: RegExp;
+/** Verifier 2. Every step a planned test makes cites the repository file that
+ *  declares it, and the citation is the WHOLE check — the route catalog and the
+ *  diff's routes it replaced were framework parsers, blind to GraphQL, Thrift and
+ *  gRPC. A `ui` or `e2e` planned test is exempt whole; a checked one, per step. */
+export declare const endpointGrounded: Verifier;

package/build/recommendation/verifiers/endpointGrounded.js

@@ -0,0 +1,128 @@
+import { isUIPlannedTest } from "../subjectStep.js";
+import { ENDPOINT_GROUNDED_CONTRACT } from "../verifierContracts.js";
+import { isTestPath } from "../../utils/testFileClassification.js";
+/** A path that leaves the checkout, in any of its spellings. Callers pass a
+ *  trimmed path: " ../routes.rb" splits to [" ..", "routes.rb"], so no segment
+ *  equals ".." and one leading space would carry it through. */
+export function escapesRepo(file) {
+    // POSIX absolute, a Windows drive, a bare leading backslash, and a UNC share.
+    if (file.startsWith("/") || file.startsWith("\\") || /^[A-Za-z]:[\\/]/.test(file))
+        return true;
+    // A URL, which both citation describes promise is not a citation: `http://host/x`
+    // has no leading slash and no `..`, so without this it resolved against the
+    // checkout. A lone colon is NOT enough (`orders:batchGet.rb` is a legal name), so
+    // a scheme counts only with a leading slash, a nested URL, or a non-file scheme.
+    const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):([\s\S]*)$/.exec(file);
+    if (scheme) {
+        const [, name, rest] = scheme;
+        if (rest.startsWith("/") || rest.includes("://") || /^(file|data|javascript|jar|blob)$/i.test(name))
+            return true;
+    }
+    return file.split(/[\\/]/).some((segment) => segment === "..");
+}
+export const NOT_SOURCE_DIR = /(^|[\\/])(node_modules|vendor|dist|build|\.next|target)([\\/]|$)/i;
+/** What plainly cannot define a route. A DENY list on purpose: an allowlist would
+ *  rebuild the framework wall this verifier removes. When in doubt ALLOW — a false
+ *  accept costs one unfounded citation, a false reject a whole framework. */
+export const NOT_A_ROUTE_FILE = /\.(md|markdown|rst|adoc|txt|log|csv|tsv|pdf|png|jpe?g|gif|svg|ico|webp|bmp|mp4|mov|zip|gz|tgz|tar|woff2?|ttf|eot|snap)$/i;
+/** Lockfiles, including the two that end in an allowed extension. */
+export const LOCKFILE = /(^|[\\/])([^\\/]*[-.]lock\.(json|ya?ml)|[^\\/]*\.lock)$/i;
+/** Whether a cited file could plausibly define a route. DISQUALIFICATION, not
+ *  proof: it does NOT look inside, because frameworks assemble paths from scopes
+ *  and prefixes. A string check only — symlinks are the file reader's job. */
+function citationDisqualified(rawFile, ctx) {
+    // Normalise once, before any check: every check below reads this value, so a
+    // check that ran on the raw string could disagree with the one before it.
+    const file = String(rawFile ?? "").trim();
+    if (!file)
+        return "no file cited";
+    if (escapesRepo(file))
+        return `cited path "${file}" points outside the repository`;
+    if (NOT_SOURCE_DIR.test(file))
+        return `cited file ${file} is vendored or built output, not source`;
+    if (isTestPath(file))
+        return `cited file ${file} is a test file, not the source that defines the route`;
+    if (LOCKFILE.test(file))
+        return `cited file ${file} is a lockfile, not a file that can define a route`;
+    if (NOT_A_ROUTE_FILE.test(file))
+        return `cited file ${file} is documentation or a binary, not a file that can define a route`;
+    if (!ctx.citedFileExists(file))
+        return `cited file not found: ${file}`;
+    return undefined;
+}
+/** How the objection reads when the routes have no citation, when their
+ *  citations are implausible, and when the planned test has some of each. */
+function describeObjection(uncited, disqualified) {
+    if (disqualified === 0)
+        return ENDPOINT_GROUNDED_CONTRACT.objections.uncited;
+    if (uncited === 0)
+        return ENDPOINT_GROUNDED_CONTRACT.objections.disqualifiedCitation;
+    return ENDPOINT_GROUNDED_CONTRACT.objections.uncitedAndDisqualified;
+}
+/** Verifier 2. Every step a planned test makes cites the repository file that
+ *  declares it, and the citation is the WHOLE check — the route catalog and the
+ *  diff's routes it replaced were framework parsers, blind to GraphQL, Thrift and
+ *  gRPC. A `ui` or `e2e` planned test is exempt whole; a checked one, per step. */
+export const endpointGrounded = {
+    name: "endpointGrounded",
+    run(registration, ctx) {
+        const objections = [];
+        for (const plannedTest of registration.plannedTests) {
+            if (isUIPlannedTest(plannedTest))
+                continue;
+            const evidence = plannedTest.declarations?.routes ?? [];
+            const ungrounded = [];
+            let uncited = 0;
+            let disqualified = 0;
+            for (const step of plannedTest.scenario?.steps ?? []) {
+                // A step naming no path calls nothing there is a file to cite for — a wait,
+                // a pause, a setup line. The verb is deliberately NOT read: requiring one
+                // made a Thrift or GraphQL call look like a click and skip this check.
+                if (!String(step?.path ?? "").trim())
+                    continue;
+                const key = `${String(step?.method ?? "ANY").trim() || "ANY"} ${String(step?.path).trim()}`;
+                // Named by the step's own `order`, so nothing here compares two spellings
+                // of one route. The number must be a number: a string `"2"` names no step.
+                const cited = evidence.filter((e) => typeof e?.step === "number" && e.step === (step?.order ?? 0));
+                if (cited.length === 0) {
+                    uncited += 1;
+                    pushOnce(ungrounded, `${key} (no file cited)`);
+                    continue;
+                }
+                // ANY one plausible citation grounds the route. A planned test that cites
+                // two files for one route must not fail on the weaker of them.
+                const reasons = [];
+                let grounded = false;
+                for (const citation of cited) {
+                    const reason = citationDisqualified(citation.file, ctx);
+                    if (reason === undefined) {
+                        grounded = true;
+                        break;
+                    }
+                    reasons.push(reason);
+                }
+                if (grounded)
+                    continue;
+                disqualified += 1;
+                pushOnce(ungrounded, `${key} (${reasons[0]})`);
+            }
+            if (ungrounded.length > 0) {
+                const { message, suggestion } = describeObjection(uncited, disqualified);
+                objections.push({
+                    objectionId: `endpointGrounded:${plannedTest.plannedTestId}`,
+                    verifier: "endpointGrounded",
+                    plannedTestId: plannedTest.plannedTestId,
+                    message,
+                    evidence: `ungrounded: ${ungrounded.join("; ")}`,
+                    suggestion,
+                });
+                continue;
+            }
+        }
+        return objections;
+    },
+};
+function pushOnce(list, note) {
+    if (!list.includes(note))
+        list.push(note);
+}

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

@@ -0,0 +1,6 @@
+import { Verifier } from "../types.js";
+/** Verifier 6. The existing tests a planned test says it read are really in the
+ *  checkout, and nothing more: deciding that one already covers the planned test came
+ *  from route-parsed `METHOD::resource` keys, wrong in both directions. `differsBy`
+ *  is recorded, never judged, and citing nothing raises nothing. */
+export declare const existingCoverage: Verifier;

package/build/recommendation/verifiers/existingCoverage.js

@@ -0,0 +1,51 @@
+import { escapesRepo } from "./endpointGrounded.js";
+import { EXISTING_COVERAGE_CONTRACT } from "../verifierContracts.js";
+/** Verifier 6. The existing tests a planned test says it read are really in the
+ *  checkout, and nothing more: deciding that one already covers the planned test came
+ *  from route-parsed `METHOD::resource` keys, wrong in both directions. `differsBy`
+ *  is recorded, never judged, and citing nothing raises nothing. */
+export const existingCoverage = {
+    name: "existingCoverage",
+    run(registration, ctx) {
+        const objections = [];
+        for (const plannedTest of registration.plannedTests) {
+            // The plan is read off disk, so this is an array only on the validated
+            // path. A throw here would reach the agent as `:crashed`, hiding the real
+            // objection instead of raising it.
+            const cited = plannedTest?.declarations?.existingTests;
+            if (!Array.isArray(cited))
+                continue;
+            const unreadable = [];
+            for (const entry of cited) {
+                const file = String(entry?.file ?? "").trim();
+                if (!file) {
+                    pushOnce(unreadable, "an entry names no file");
+                    continue;
+                }
+                // Confinement first: `citedFileExists` resolves inside the checkout, and
+                // a path that leaves it is not a citation of anything this run holds.
+                if (escapesRepo(file)) {
+                    pushOnce(unreadable, `${file} (points outside the repository)`);
+                    continue;
+                }
+                if (!ctx.citedFileExists(file))
+                    pushOnce(unreadable, `${file} (not found)`);
+            }
+            if (unreadable.length === 0)
+                continue;
+            objections.push({
+                objectionId: `existingCoverage:${plannedTest.plannedTestId}`,
+                verifier: "existingCoverage",
+                plannedTestId: plannedTest.plannedTestId,
+                message: EXISTING_COVERAGE_CONTRACT.objections.citedTestMissing.message,
+                evidence: `cited existing tests not in the checkout: ${unreadable.join("; ")}`,
+                suggestion: EXISTING_COVERAGE_CONTRACT.objections.citedTestMissing.suggestion,
+            });
+        }
+        return objections;
+    },
+};
+function pushOnce(list, note) {
+    if (!list.includes(note))
+        list.push(note);
+}

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

@@ -0,0 +1,31 @@
+import { Objection, Verifier } from "../types.js";
+import { Plan } from "../registerPlan.js";
+/** One test's outcome, as the execution stage reports it. */
+export interface ExecutionOutcome {
+    plannedTestId: string;
+    passed: boolean;
+    /** The failure text, when it failed. */
+    failureDetail?: string;
+    /** Whether the test reached the behaviour it was written for before it failed, as
+     *  the agent states it. ABSENT means unstated and raises nothing: inferring it
+     *  from the failure text meant an allowlist of blocker phrases over free prose. */
+    reachedBehavior?: boolean;
+}
+/** One `issuesFound` entry, as much of it as this check reads. */
+export interface ReportedBlocker {
+    severity?: string;
+    description?: string;
+    sourceFile?: string;
+}
+/** Verifier 4, post-execution half: separates a failure that caught the bug from one
+ *  that fell over before reaching it. Joined by `plannedTestId`, never by array
+ *  position, and a planned test with no result produces nothing. The ids carry an
+ *  `executed` segment so one answer cannot close both halves. `issues` is the
+ *  report's own `issuesFound`: when one of them names the blocked test's route,
+ *  the objection quotes it so the answer is one sentence. */
+export declare function checkExpectedOutcomeAfterExecution(plan: Plan, results: ExecutionOutcome[], issues?: ReportedBlocker[]): Objection[];
+/** Verifier 4, plan time. STRUCTURAL ONLY: a planned test in a bug-catching category
+ *  that expects to pass on the current app is contradicting itself. Whether the
+ *  `asserts` prose describes the fixed behaviour or the broken one needs a model,
+ *  and string matching cannot stand in for it — do not add one. */
+export declare const expectedOutcomeAtPlanTime: Verifier;

package/build/recommendation/verifiers/expectedOutcome.js

@@ -0,0 +1,105 @@
+import { categoryExpectsRed } from "../../types/TestRecommendation.js";
+import { fillPlaceholders, EXPECTED_OUTCOME_CONTRACT } from "../verifierContracts.js";
+import { subjectStep } from "../subjectStep.js";
+/** The severities that count as the run's own reported defect. */
+const BLOCKER_FLOOR = ["critical", "high"];
+/** The reported issue that names this test's own route, if one does. Containment
+ *  on the path and nothing more: the aim is to hand the agent the sentence it
+ *  would otherwise retype, not to decide whether the issue really is the cause. */
+function blockingIssue(plannedTest, issues) {
+    const path = String(subjectStep(plannedTest)?.path ?? "").trim();
+    if (!path)
+        return undefined;
+    for (const issue of issues) {
+        if (!BLOCKER_FLOOR.includes(String(issue?.severity ?? "").trim().toLowerCase()))
+            continue;
+        const description = String(issue?.description ?? "");
+        const sourceFile = String(issue?.sourceFile ?? "");
+        if (!description.includes(path) && !sourceFile.includes(path))
+            continue;
+        const text = description.trim() || sourceFile.trim();
+        if (text)
+            return text.slice(0, 100);
+    }
+    return undefined;
+}
+/** Verifier 4, post-execution half: separates a failure that caught the bug from one
+ *  that fell over before reaching it. Joined by `plannedTestId`, never by array
+ *  position, and a planned test with no result produces nothing. The ids carry an
+ *  `executed` segment so one answer cannot close both halves. `issues` is the
+ *  report's own `issuesFound`: when one of them names the blocked test's route,
+ *  the objection quotes it so the answer is one sentence. */
+export function checkExpectedOutcomeAfterExecution(plan, results, issues = []) {
+    const byId = new Map(results.map((r) => [r.plannedTestId, r]));
+    const objections = [];
+    for (const plannedTest of plan.plannedTests) {
+        const result = byId.get(plannedTest.plannedTestId);
+        if (!result)
+            continue;
+        const declared = plannedTest.declarations?.expected?.outcome;
+        if (declared === "fail" && result.passed) {
+            objections.push({
+                objectionId: `expectedOutcome:executed:${plannedTest.plannedTestId}`,
+                verifier: "expectedOutcome",
+                plannedTestId: plannedTest.plannedTestId,
+                message: "This test was declared should-fail and passed. Either the bug is not there or the test does not reach it.",
+                evidence: `declared fail, passed`,
+                suggestion: "Say which it is: the behaviour is already correct, so the objection does not stand, or the test misses the path that carries the defect and needs to target it.",
+            });
+            continue;
+        }
+        if (declared === "pass" && !result.passed) {
+            objections.push({
+                objectionId: `expectedOutcome:executed:${plannedTest.plannedTestId}`,
+                verifier: "expectedOutcome",
+                plannedTestId: plannedTest.plannedTestId,
+                message: "This test was declared should-pass and failed. Say whether the failure is the bug or the test.",
+                evidence: `declared pass, failed: ${result.failureDetail ?? "no detail"}`,
+                suggestion: "If the failure is a real defect, report it as one. If the test itself is wrong, fix the test rather than reporting the failure.",
+            });
+            continue;
+        }
+        // Stated by the agent, not inferred: a 404 the test asked for and a 404 that
+        // stopped it read the same in the failure text, and only whoever wrote the
+        // test knows which it was. A row that leaves the field out raises nothing.
+        if (declared === "fail" && !result.passed && result.reachedBehavior === false) {
+            const blocker = blockingIssue(plannedTest, issues);
+            objections.push({
+                objectionId: `expectedOutcome:executed:${plannedTest.plannedTestId}`,
+                verifier: "expectedOutcome",
+                plannedTestId: plannedTest.plannedTestId,
+                message: EXPECTED_OUTCOME_CONTRACT.objections.executed.message,
+                evidence: blocker ? `blocked by reported issue: ${blocker}` : (result.failureDetail ?? ""),
+                suggestion: EXPECTED_OUTCOME_CONTRACT.objections.executed.suggestion,
+            });
+        }
+    }
+    return objections;
+}
+/** Verifier 4, plan time. STRUCTURAL ONLY: a planned test in a bug-catching category
+ *  that expects to pass on the current app is contradicting itself. Whether the
+ *  `asserts` prose describes the fixed behaviour or the broken one needs a model,
+ *  and string matching cannot stand in for it — do not add one. */
+export const expectedOutcomeAtPlanTime = {
+    name: "expectedOutcome",
+    run(registration, _ctx) {
+        const objections = [];
+        for (const plannedTest of registration.plannedTests) {
+            // Compared normalised, reported as written: the agent has to recognise the
+            // value it sent in the objection.
+            const category = String(plannedTest.scenario?.category ?? "");
+            const declaredOutcome = plannedTest.declarations?.expected?.outcome;
+            if (declaredOutcome !== "pass" || !categoryExpectsRed(category))
+                continue;
+            objections.push({
+                objectionId: `expectedOutcome:${plannedTest.plannedTestId}`,
+                verifier: "expectedOutcome",
+                plannedTestId: plannedTest.plannedTestId,
+                message: fillPlaceholders(EXPECTED_OUTCOME_CONTRACT.objections.passInShouldFailCategory.message, { category }),
+                evidence: `category ${category}, declared pass: "${plannedTest.declarations?.expected?.why ?? ""}"`,
+                suggestion: EXPECTED_OUTCOME_CONTRACT.objections.passInShouldFailCategory.suggestion,
+            });
+        }
+        return objections;
+    },
+};

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

@@ -0,0 +1,2 @@
+import { Verifier } from "../types.js";
+export declare const removedElementGuarded: Verifier;

package/build/recommendation/verifiers/removedElementGuarded.js

@@ -0,0 +1,57 @@
+/** Verifier 9. Every element the diff removed needs a planned test that says it is
+ *  gone.
+ *
+ *  v1 solved this in the server: SKYR-4339 resolved each removed element to a page
+ *  through the import graph and, when that found none, through a root fallback —
+ *  the fallback existing only so an element whose page could not be resolved still
+ *  produced a guard instead of being dropped. v2 took page attribution out of the
+ *  server, so the same protection has to read the plan instead: the run is free to
+ *  decide which page the element belongs on, and is not free to leave it out.
+ *
+ *  This is the direction `uiElementGrounded` does not check. That one asks whether
+ *  a declared element is real; this one asks whether a real removal was declared. */
+const text = (value) => (typeof value === "string" ? value.trim() : "");
+/** How a plan names an element. `testId` is the one field that carries the value
+ *  for a `data-testid`; a guard on `data-cy` or `data-qa` reaches the plan with
+ *  `testId` null, so the value is looked for in the prose the test states too. */
+function namesElement(plannedTest, value) {
+    const declared = plannedTest?.declarations;
+    const items = Array.isArray(declared?.elements?.items) ? declared.elements.items : [];
+    if (items.some((item) => text(item?.testId) === value || text(item?.stableId) === value))
+        return true;
+    return [text(declared?.asserts), text(plannedTest?.plannedTestId)].some((prose) => prose.includes(value));
+}
+/** `attribute=value` identifies an element across the run, so the objection id is
+ *  the same string on every registration whatever order the list arrives in. */
+const objectionIdFor = (element) => `removedElementGuarded:${text(element?.attribute)}=${text(element?.value)}`;
+export const removedElementGuarded = {
+    name: "removedElementGuarded",
+    run(registration, ctx) {
+        const removed = Array.isArray(ctx?.removedUiElements) ? ctx.removedUiElements : [];
+        if (removed.length === 0)
+            return [];
+        const plannedTests = Array.isArray(registration?.plannedTests) ? registration.plannedTests : [];
+        const objections = [];
+        const seen = new Set();
+        for (const element of removed) {
+            const value = text(element?.value);
+            const attribute = text(element?.attribute);
+            if (!value || !attribute)
+                continue;
+            const objectionId = objectionIdFor(element);
+            if (seen.has(objectionId))
+                continue;
+            seen.add(objectionId);
+            if (plannedTests.some((plannedTest) => namesElement(plannedTest, value)))
+                continue;
+            objections.push({
+                objectionId,
+                verifier: "removedElementGuarded",
+                message: `The diff removes \`${attribute}="${value}"\` and no planned test says it is gone.`,
+                evidence: `removed from ${text(element?.file) || "a changed frontend file"}; no planned test names ${value}`,
+                suggestion: "Plan a UI test on the page that still renders, asserting this element is absent, and name it in that test's elements. Removing it is what this pull request ships, so the removal is what gets tested. If the diff shows it still rendering under a new identifier it is a rename, not a removal — say so as the answer.",
+            });
+        }
+        return objections;
+    },
+};

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

@@ -0,0 +1,26 @@
+import { Objection } from "../types.js";
+import { Plan } from "../registerPlan.js";
+/** One test as the report describes it. */
+export interface ReportedTest {
+    plannedTestId?: string;
+    fileName: string;
+    category?: string;
+}
+/** One entry of the report's `issuesFound`. Every field optional: the caller
+ *  reads them off a submitted report, where only the schema-validated path
+ *  guarantees a shape. */
+export interface ReportedIssue {
+    severity?: string;
+    /** The planned test this issue is about, when the report names one. */
+    plannedTestId?: string;
+}
+/** Verifier 9, post-execution. The category a test is REPORTED under is the one it
+ *  was PLANNED under — a direct comparison, since both sides take the same category
+ *  list. An objection, never a rejection: the tests exist, and a category changed
+ *  on purpose is answerable. */
+export declare function checkReportedCategoryMatchesPlan(plan: Plan, delivered: ReportedTest[]): Objection[];
+/** Verifier 10, post-execution. A requirement conflict is reported as an issue at
+ *  `critical` or `high`, read plan-side, one objection per run. It asks only that
+ *  SOMETHING met the floor: the only field both sides share is a path, and the
+ *  route's file and the wrong code's file differ by design in a layered app. */
+export declare function checkRequirementConflictReported(plan: Plan, delivered: ReportedTest[], issues: ReportedIssue[]): Objection[];

package/build/recommendation/verifiers/reportedCategory.js

@@ -0,0 +1,84 @@
+import { normalizeCategory } from "../../types/TestRecommendation.js";
+/** The severities a requirement conflict is allowed to be reported at. */
+const REQUIREMENT_CONFLICT_FLOOR = ["critical", "high"];
+/** The planned planned test a reported test joins to, by id and never by name. */
+function plannedTest(plan, test) {
+    const id = test.plannedTestId?.trim();
+    if (!id)
+        return undefined;
+    return plan.plannedTests.find((plannedTest) => plannedTest.plannedTestId === id);
+}
+function plannedCategory(plan, test) {
+    return plannedTest(plan, test)?.scenario?.category;
+}
+/** Verifier 9, post-execution. The category a test is REPORTED under is the one it
+ *  was PLANNED under — a direct comparison, since both sides take the same category
+ *  list. An objection, never a rejection: the tests exist, and a category changed
+ *  on purpose is answerable. */
+export function checkReportedCategoryMatchesPlan(plan, delivered) {
+    const objections = [];
+    for (const test of delivered) {
+        const planned = plannedCategory(plan, test);
+        const reported = String(test.category ?? "").trim();
+        if (!planned || !reported)
+            continue;
+        if (reported === planned)
+            continue;
+        objections.push({
+            objectionId: `reportedCategory:${test.plannedTestId}`,
+            verifier: "reportedCategory",
+            plannedTestId: test.plannedTestId,
+            message: "This test is reported under a different category from the one it was planned under.",
+            evidence: `planned ${planned}, report says ${reported}`,
+            suggestion: "Say which category the test really belongs to. If the plan's was wrong, the report's category stands and this objection records the change; if the report's is a slip, correct it so the two agree.",
+        });
+    }
+    return objections;
+}
+/** Verifier 10, post-execution. A requirement conflict is reported as an issue at
+ *  `critical` or `high`, read plan-side, one objection per run. It asks only that
+ *  SOMETHING met the floor: the only field both sides share is a path, and the
+ *  route's file and the wrong code's file differ by design in a layered app. */
+export function checkRequirementConflictReported(plan, delivered, issues) {
+    // Normalised, not compared as written: `Requirement-Conflict` counts as red
+    // everywhere else and still escaped this severity floor.
+    const conflicts = delivered.filter((test) => normalizeCategory(plannedCategory(plan, test)) === "requirement_conflict");
+    if (conflicts.length === 0)
+        return [];
+    const severities = issues.map((issue) => String(issue?.severity ?? "").trim().toLowerCase());
+    const isAtFloor = (issue) => REQUIREMENT_CONFLICT_FLOOR.includes(String(issue?.severity ?? "").trim().toLowerCase());
+    const atFloor = issues.filter(isAtFloor);
+    if (atFloor.length === 0) {
+        const named = conflicts.map((test) => test.fileName).join(", ");
+        return [
+            {
+                objectionId: "requirementConflictReported:severity",
+                verifier: "requirementConflictReported",
+                message: "This run wrote a requirement-conflict test and reported no issue at critical or high.",
+                evidence: severities.length === 0
+                    ? `${conflicts.length} requirement-conflict test(s): ${named}; issuesFound is empty`
+                    : `${conflicts.length} requirement-conflict test(s): ${named}; issuesFound severities: ${severities.join(", ")}`,
+                suggestion: "Record the conflict in `issuesFound` at `critical` or `high`, quoting the requirement it contradicts — a stated requirement the code does not meet is not a medium. If the conflict turned out not to hold, say so here and drop the category from the test.",
+            },
+        ];
+    }
+    // Per CANDIDATE once the report names planned tests at all: a run-wide "some issue
+    // is severe" let an unrelated outage stand in for a conflict nobody wrote up. A
+    // report whose issues name no planned test keeps the run-level answer above.
+    if (!issues.some((issue) => String(issue?.plannedTestId ?? "").trim().length > 0))
+        return [];
+    const unnamed = conflicts.filter((test) => !atFloor.some((issue) => String(issue?.plannedTestId ?? "").trim() === String(test.plannedTestId ?? "").trim()
+        && String(test.plannedTestId ?? "").trim().length > 0));
+    if (unnamed.length === 0)
+        return [];
+    return [
+        {
+            objectionId: "requirementConflictReported:association",
+            verifier: "requirementConflictReported",
+            message: "A requirement-conflict test has no issue of its own at critical or high.",
+            evidence: `${unnamed.length} of ${conflicts.length} requirement-conflict test(s) named by no severe issue: ${unnamed.map((test) => test.fileName).join(", ")}`,
+            suggestion: "Set `plannedTestId` on the `issuesFound` entry that records each conflict, so the issue names the test that asserts it. One severe issue covering an unrelated defect does not stand in for a conflict nobody wrote up.",
+        },
+    ];
+    return [];
+}

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

@@ -0,0 +1,10 @@
+import { Verifier } from "../types.js";
+/** Verifier 8. A UI planned test opens `elements.pageUrl`; the file it is about
+ *  renders on some set of routes. Those two have to be the same page, or the
+ *  trace records a screen the diff did not change.
+ *
+ *  Mechanical, and needs no browser: the route patterns come from the repository
+ *  scan the caller already runs, and the comparison is segment-wise. SILENT
+ *  wherever it cannot state a fact — an unknown framework, an unstated file, a
+ *  pageUrl another check already objects to. Plan time only. */
+export declare const screenRoute: Verifier;

package/build/recommendation/verifiers/screenRoute.js

@@ -0,0 +1,118 @@
+import { isUIPlannedTest } from "../subjectStep.js";
+import { SCREEN_ROUTE_CONTRACT } from "../verifierContracts.js";
+/** A route PATTERN's parameter segment, in the four spellings the frameworks this
+ *  run meets use: TanStack `$id`, Express/Vue `:id`, Next `[id]`, OpenAPI-ish
+ *  `{id}`. A pattern segment matches any one concrete segment; it never spans
+ *  two, so depth still has to agree. */
+function isParameter(segment) {
+    return (segment.startsWith("$") ||
+        segment.startsWith(":") ||
+        (segment.startsWith("[") && segment.endsWith("]")) ||
+        (segment.startsWith("{") && segment.endsWith("}")));
+}
+function segments(path) {
+    return path.split("/").filter(Boolean);
+}
+/** Whether a concrete url path is that route pattern with its parameters filled
+ *  in. Depth agrees or nothing does: a prefix is a different page, and the run
+ *  this check exists for opened the PARENT of the route it needed. */
+function fills(pattern, path) {
+    const wanted = segments(pattern);
+    const actual = segments(path);
+    if (wanted.length !== actual.length)
+        return false;
+    return wanted.every((segment, i) => isParameter(segment) || segment === actual[i]);
+}
+/** The path half of a url, trailing slash dropped, root kept as `/`. A pageUrl is
+ *  a route path on a lane where no host serves the app and an absolute url when
+ *  one does; both name the same page. */
+function urlPath(raw) {
+    const value = String(raw ?? "").trim();
+    if (!value)
+        return "";
+    try {
+        return new URL(value).pathname.replace(/\/+$/, "") || "/";
+    }
+    catch {
+        return value.startsWith("/") ? value.split(/[?#]/)[0].replace(/\/+$/, "") || "/" : "";
+    }
+}
+function field(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+/** The routes the resolver gives for a file, or undefined when it cannot speak
+ *  for it. A resolver that throws or answers with the wrong type is treated as
+ *  one that cannot speak: a scan is best-effort, and its failure is not evidence
+ *  about the plan. */
+function routesFor(ctx, file) {
+    if (typeof ctx?.routesRenderingFile !== "function")
+        return undefined;
+    try {
+        const routes = ctx.routesRenderingFile(file);
+        return Array.isArray(routes) ? routes.map(field).filter(Boolean) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function list(values) {
+    return values.join("; ");
+}
+/** Verifier 8. A UI planned test opens `elements.pageUrl`; the file it is about
+ *  renders on some set of routes. Those two have to be the same page, or the
+ *  trace records a screen the diff did not change.
+ *
+ *  Mechanical, and needs no browser: the route patterns come from the repository
+ *  scan the caller already runs, and the comparison is segment-wise. SILENT
+ *  wherever it cannot state a fact — an unknown framework, an unstated file, a
+ *  pageUrl another check already objects to. Plan time only. */
+export const screenRoute = {
+    name: "screenRoute",
+    run(registration, ctx) {
+        const objections = [];
+        for (const plannedTest of registration.plannedTests ?? []) {
+            if (!isUIPlannedTest(plannedTest))
+                continue;
+            const elements = plannedTest.declarations?.elements;
+            const url = field(elements && typeof elements === "object" ? elements.pageUrl : "");
+            // `uiElementGrounded:pagecontext` already objects to an empty pageUrl.
+            if (!url)
+                continue;
+            const path = urlPath(url);
+            if (!path)
+                continue;
+            // `screenEvidence.file` names the file that renders the screen; on a mixed
+            // PR that is not the file the test is about. `changedFile` is the fallback,
+            // and `changedFile:notStated` already objects when neither is stated.
+            const screen = field(plannedTest.declarations?.screenEvidence?.file) || field(plannedTest.declarations?.changedFile);
+            if (!screen)
+                continue;
+            const routes = routesFor(ctx, screen);
+            // The resolver does not know this file. Not a fact about the plan.
+            if (routes === undefined)
+                continue;
+            if (routes.length === 0) {
+                objections.push({
+                    objectionId: `screenRoute:unmounted:${plannedTest.plannedTestId}`,
+                    verifier: "screenRoute",
+                    plannedTestId: plannedTest.plannedTestId,
+                    message: SCREEN_ROUTE_CONTRACT.objections.unmounted.message,
+                    evidence: `${screen} is rendered by no route this run found; this test opens ${url}`,
+                    suggestion: SCREEN_ROUTE_CONTRACT.objections.unmounted.suggestion,
+                });
+                continue;
+            }
+            if (routes.some((route) => fills(route, path)))
+                continue;
+            objections.push({
+                objectionId: `screenRoute:mismatch:${plannedTest.plannedTestId}`,
+                verifier: "screenRoute",
+                plannedTestId: plannedTest.plannedTestId,
+                message: SCREEN_ROUTE_CONTRACT.objections.mismatch.message,
+                evidence: `${screen} is rendered on: ${list(routes)}; this test opens ${url}`,
+                suggestion: SCREEN_ROUTE_CONTRACT.objections.mismatch.suggestion,
+            });
+        }
+        return objections;
+    },
+};

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

@@ -0,0 +1,6 @@
+import { Verifier } from "../types.js";
+/** Verifier 3. Two planned tests whose subject steps name the same method and path
+ *  must say how they differ — ASKING, where the old dedup key removed one of the
+ *  pair on a string that says nothing about what either asserts. Both sides get an
+ *  objection; a stated difference is taken at its word. No request, no compare. */
+export declare const statedDifference: Verifier;