@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/recommendation/verifiers/coverage.js

@@ -0,0 +1,617 @@
+import { allChangedFiles } from "../types.js";
+import { LOCKFILE, NOT_A_ROUTE_FILE, NOT_SOURCE_DIR } from "./endpointGrounded.js";
+import { isTestPath } from "../../utils/testFileClassification.js";
+import { normalizeCitedPath } from "./citedPath.js";
+import { COVERAGE_CONTRACT, fillPlaceholders } from "../verifierContracts.js";
+import { isUIPlannedTest, stateRouteKey, subjectStep } from "../subjectStep.js";
+/** Whether a path can be product code at all, by the deny list route grounding
+ *  already applies to a cited file. Nothing else is excluded: a file's kind is
+ *  not this check's judgment to make. */
+function couldBeProductCode(file) {
+    const path = file.trim();
+    if (!path)
+        return false;
+    return !(isTestPath(path) || NOT_SOURCE_DIR.test(path) || LOCKFILE.test(path) || NOT_A_ROUTE_FILE.test(path));
+}
+/** Every changed file some planned test cites, in normalised spelling. THREE fields,
+ *  all name-level: `changedFile`, `routes[].file` and `screenEvidence.file`
+ *  — citing a changed file through any of them is being about that file. Coverage
+ *  by citation reads names alone, where an anchor search needed the diff text. */
+function citedFiles(plannedTests) {
+    const cited = new Set();
+    const add = (value) => {
+        const path = normalizeCitedPath(value);
+        if (path)
+            cited.add(path);
+    };
+    for (const plannedTest of plannedTests) {
+        add(plannedTest?.declarations?.changedFile);
+        add(plannedTest?.declarations?.screenEvidence?.file);
+        // 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 evidence = plannedTest?.declarations?.routes;
+        if (Array.isArray(evidence))
+            for (const entry of evidence)
+                add(entry?.file);
+    }
+    return cited;
+}
+/** The behaviour ids some planned test cites, trimmed. */
+function citedBehaviors(plannedTests) {
+    const cited = new Set();
+    for (const plannedTest of plannedTests) {
+        const declared = plannedTest?.declarations?.changes;
+        if (!Array.isArray(declared))
+            continue;
+        for (const id of declared) {
+            const trimmed = String(id ?? "").trim();
+            if (trimmed)
+                cited.add(trimmed);
+        }
+    }
+    return cited;
+}
+/** Every declared behaviour needs a planned test citing it, or an answer. Coverage per
+ *  file is the basic minimum — one shape test on a changed file satisfies it while
+ *  the behaviour that file promises goes untested. This half is the target.
+ *
+ *  Checked whether or not the run has a diff: the agent declared these itself, so
+ *  there is always something to hold it to. */
+function claimObjections(registration) {
+    const changes = Array.isArray(registration.changes) ? registration.changes : [];
+    const plannedTests = registration.plannedTests ?? [];
+    const objections = [];
+    if (changes.length === 0) {
+        return [
+            {
+                objectionId: "coverage:noChanges",
+                verifier: "coverage",
+                message: COVERAGE_CONTRACT.objections.noChanges.message,
+                evidence: "the registered plan declares an empty `changes` list.",
+                suggestion: COVERAGE_CONTRACT.objections.noChanges.suggestion,
+            },
+        ];
+    }
+    const declared = new Set();
+    for (const change of changes) {
+        const id = String(change?.id ?? "").trim();
+        if (id)
+            declared.add(id);
+    }
+    const cited = citedBehaviors(plannedTests);
+    const seen = new Set();
+    for (const change of changes) {
+        const id = String(change?.id ?? "").trim();
+        if (!id || seen.has(id))
+            continue;
+        seen.add(id);
+        if (cited.has(id))
+            continue;
+        objections.push({
+            objectionId: `coverage:change:${id}`,
+            verifier: "coverage",
+            message: COVERAGE_CONTRACT.objections.change.message,
+            evidence: `"${String(change?.text ?? "").trim()}" (${String(change?.source ?? "").trim()}): no planned test cites behaviour ${id}.`,
+            suggestion: COVERAGE_CONTRACT.objections.change.suggestion,
+        });
+    }
+    // One objection per planned test, not per id: a planned test with three unknown ids
+    // has one mistake to fix, and three objections would need three answers.
+    for (const plannedTest of plannedTests) {
+        const claimIds = plannedTest?.declarations?.changes;
+        if (!Array.isArray(claimIds))
+            continue;
+        const unknown = [...new Set(claimIds.map((id) => String(id ?? "").trim()))].filter((id) => id && !declared.has(id));
+        if (unknown.length === 0)
+            continue;
+        objections.push({
+            objectionId: `coverage:unknownChange:${plannedTest.plannedTestId}`,
+            verifier: "coverage",
+            plannedTestId: plannedTest.plannedTestId,
+            message: COVERAGE_CONTRACT.objections.unknownChange.message,
+            evidence: `${plannedTest.plannedTestId} cites ${unknown.map((id) => `"${id}"`).join(", ")}; this plan declares ${[...declared].map((id) => `"${id}"`).join(", ") || "no claims"}.`,
+            suggestion: COVERAGE_CONTRACT.objections.unknownChange.suggestion,
+        });
+    }
+    return objections;
+}
+// ── The state surface ───────────────────────────────────────────────────────
+/** The methods that write. A GET reads what is already there, so what the record
+ *  held before the call decides nothing; these four run new code against a value
+ *  the change did not write, which is where a latent bug sits. */
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/** Whether a planned test names the state its starting record is in. Presence is all
+ *  that is checked: no two repositories describe a record's state the same way, and
+ *  the test puts the record in that state itself rather than reading it from a file. */
+function declaresStartState(plannedTest) {
+    return String(plannedTest?.declarations?.startState ?? "").trim().length > 0;
+}
+/** The route a planned test's test mutates, by SHAPE — `stateRouteKey`, so the id a
+ *  step happened to write does not split one route in two. UI planned tests are OUT:
+ *  their subject is a screen, and their endpoints are attributions the agent wrote
+ *  rather than what the test asserts. */
+function mutatedRoute(plannedTest) {
+    if (isUIPlannedTest(plannedTest))
+        return undefined;
+    const step = subjectStep(plannedTest);
+    if (!MUTATING_METHODS.has(String(step?.method ?? "").trim().toUpperCase()))
+        return undefined;
+    return stateRouteKey(step);
+}
+/** The routes some planned test already tests from a non-default state. A UI planned test
+ *  COUNTS here where it does not above: a browser test that drives the mutation
+ *  against such a record is the same evidence as an API one. */
+function routesTestedFromNonDefaultState(plannedTests) {
+    const covered = new Set();
+    for (const plannedTest of plannedTests) {
+        if (!declaresStartState(plannedTest))
+            continue;
+        // Both sides of the comparison read the same key, or a covered route would
+        // never match the route that owes the test.
+        const route = stateRouteKey(subjectStep(plannedTest));
+        if (route)
+            covered.add(route);
+    }
+    return covered;
+}
+/** Every mutated route needs one test that starts from a record in a state a
+ *  freshly created record is not in. Read off the PLAN alone, like the behaviour
+ *  half — the agent declared the mutation itself, so a run with no diff has
+ *  something to hold it to. */
+function stateTestObjections(registration) {
+    const plannedTests = registration.plannedTests ?? [];
+    const covered = routesTestedFromNonDefaultState(plannedTests);
+    const objections = [];
+    const seen = new Set();
+    for (const plannedTest of plannedTests) {
+        const route = mutatedRoute(plannedTest);
+        if (!route || covered.has(route) || seen.has(route))
+            continue;
+        seen.add(route);
+        objections.push({
+            // Keyed on the ROUTE, not the planned test: the plan owes one state test per
+            // route, whichever planned test delivers it.
+            objectionId: `coverage:stateTest:${route}`,
+            verifier: "coverage",
+            message: fillPlaceholders(COVERAGE_CONTRACT.objections.stateTest.message, { route }),
+            evidence: `${plannedTest.plannedTestId} calls ${route} as its subject step; no planned test declaring startState has a subject step on it.`,
+            suggestion: COVERAGE_CONTRACT.objections.stateTest.suggestion,
+        });
+    }
+    return objections;
+}
+// ── The declared cases ──────────────────────────────────────────────────────
+/** One number, from a value a step sends or a case declares. A parameter is as
+ *  often a string as a number, so `"100"` and `100` are one value. Anything else
+ *  is no number at all: `Number("")` is 0, which would read as a value that was
+ *  sent. */
+function asNumber(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value !== "string")
+        return undefined;
+    const text = value.trim();
+    if (!text)
+        return undefined;
+    const parsed = Number(text);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/** Whether a value a step sends is the value a case declares. Numbers when both
+ *  sides read as numbers, text otherwise, so a query string's `"100"` matches a
+ *  declared `100` and `"asc"` matches `"asc"`. A declared `null` matches only a
+ *  value written as null. */
+function sameValue(sent, declared) {
+    // Only an `absent` case has no value, and that case never reaches here.
+    if (declared === undefined)
+        return false;
+    if (declared === null)
+        return sent === null;
+    const sentNumber = asNumber(sent);
+    const declaredNumber = asNumber(declared);
+    if (sentNumber !== undefined && declaredNumber !== undefined)
+        return sentNumber === declaredNumber;
+    return String(sent) === String(declared);
+}
+/** Every value of one parameter a step sends, wherever it carries it: the query
+ *  string written into the path, the `queryParams` object, or the top level of the
+ *  request body. Nothing reads deeper into a body — a constrained input is a field
+ *  of the request, not a field nested inside one. */
+function valuesSent(step, param) {
+    const found = [];
+    const query = String(step?.path ?? "").split("?").slice(1).join("?");
+    if (query)
+        found.push(...new URLSearchParams(query).getAll(param));
+    for (const carrier of [step?.queryParams, step?.requestBody]) {
+        if (carrier && typeof carrier === "object" && !Array.isArray(carrier)) {
+            const fields = carrier;
+            if (param in fields)
+                found.push(fields[param]);
+        }
+    }
+    return found;
+}
+/** The parameter name that names the request's verb rather than one of its inputs. */
+const METHOD_PARAM = "method";
+/** A path segment written as a placeholder: `{id}`, `:id` or `[id]`. */
+const PLACEHOLDER_SEGMENT = /^(?:\{(.+)\}|:(.+)|\[(.+)\])$/;
+/** A step's path segments, with any query string dropped. */
+function pathSegments(step) {
+    return String(step?.path ?? "").split("?")[0].trim().split("/");
+}
+/** The parameter a placeholder segment names, or undefined for a literal one. */
+function placeholderName(segment) {
+    const match = PLACEHOLDER_SEGMENT.exec(segment.trim());
+    if (!match)
+        return undefined;
+    return (match[1] ?? match[2] ?? match[3]).trim() || undefined;
+}
+/** Where `param` sits in a path, according to the steps that write it as a
+ *  placeholder. Only the plan says this: no route template is inferred from a
+ *  concrete path, so a plan whose steps are all concrete yields no slot and its
+ *  path cases read as not sent. */
+function pathSlots(steps, param) {
+    const slots = [];
+    for (const step of steps) {
+        const segments = pathSegments(step);
+        segments.forEach((segment, index) => {
+            if (placeholderName(segment) === param)
+                slots.push({ segments, index });
+        });
+    }
+    return slots;
+}
+/** Every name one parameter wears in a route. A case names the input — `id` —
+ *  where the step writes the route's own placeholder — `{collectionId}`. An accept
+ *  case whose value is that placeholder is the plan saying the two are the same
+ *  parameter, so its inner name counts as a name for `param` as well. The plan is
+ *  still the only source: the names come from what it declares, never from a
+ *  concrete path. */
+function pathSlotNames(cases, param) {
+    const names = new Set([param]);
+    for (const declared of cases ?? []) {
+        if (String(declared?.param ?? "").trim() !== param)
+            continue;
+        if (declared?.expect !== "accept" || declared?.absent === true)
+            continue;
+        if (!isPlaceholderValue(declared?.value))
+            continue;
+        const inner = String(declared.value).trim().slice(1, -1).trim();
+        if (inner)
+            names.add(inner);
+    }
+    return [...names];
+}
+/** The one slot a route with a single placeholder has. A step that writes exactly
+ *  one placeholder says where the record it names sits, whatever that placeholder
+ *  is called, so a case on a parameter whose name ends in `id` reads that segment
+ *  without the plan spelling out the alias. A step with no placeholder still says
+ *  nothing — no template is read from a concrete path — and a step with two says
+ *  nothing about which of them is the id. */
+function soleSlots(steps) {
+    const slots = [];
+    for (const step of steps) {
+        const segments = pathSegments(step);
+        const placeholders = segments.reduce((at, segment, index) => (placeholderName(segment) ? [...at, index] : at), []);
+        if (placeholders.length === 1)
+            slots.push({ segments, index: placeholders[0] });
+    }
+    return slots;
+}
+/** Where `param` sits in a path, under any of the names it wears. */
+function pathSlotsFor(steps, cases, param) {
+    const named = pathSlotNames(cases, param).flatMap((name) => pathSlots(steps, name));
+    return ID_PARAM.test(param) ? [...named, ...soleSlots(steps)] : named;
+}
+/** Whether a step carries `value` in the segment `param` occupies. Every other
+ *  segment has to be the template's own, so the same value at the same depth of a
+ *  different route does not count as sent. */
+function sendsInPath(step, slot, value) {
+    const segments = pathSegments(step);
+    if (segments.length !== slot.segments.length)
+        return false;
+    for (let at = 0; at < segments.length; at++) {
+        if (at !== slot.index && segments[at] !== slot.segments[at])
+            return false;
+    }
+    return sameValue(segments[slot.index], value);
+}
+/** Whether a step's verb is the declared value. A rejected method is the input. */
+function sendsAsMethod(step, value) {
+    const method = String(step?.method ?? "").trim();
+    if (!method)
+        return false;
+    return method.toUpperCase() === String(value).trim().toUpperCase();
+}
+/** Whether a step states that it leaves one parameter out. STATED, not inferred:
+ *  a step that does not carry a parameter is not distinguishable from a step the
+ *  parameter has nothing to do with. */
+function omittedBy(step, param) {
+    const omits = step?.omits;
+    if (!Array.isArray(omits))
+        return false;
+    return omits.some((named) => String(named ?? "").trim() === param);
+}
+/** One declared case as the objection spells it. */
+function renderCase(declared) {
+    const param = String(declared.param).trim();
+    const sent = declared.absent === true ? "absent" : `=${JSON.stringify(declared.value)}`;
+    return `${param}${declared.absent === true ? " " : ""}${sent} (${declared.expect})`;
+}
+/** Whether a planned test cites one change by id. */
+function citesChange(plannedTest, id) {
+    const declared = plannedTest?.declarations?.changes;
+    if (!Array.isArray(declared))
+        return false;
+    return declared.some((cited) => String(cited ?? "").trim() === id);
+}
+/** Every declared case needs a step of a citing test that sends it. The agent says
+ *  what proves the change; the server reads whether the plan sends it. Nothing here
+ *  knows a kind of input, so a constraint nobody anticipated is checked the same
+ *  way as a range.
+ *
+ *  Four runs on one fixture declared a 1-100 range on `take` and sent the upper
+ *  end in one of the four, while a report claimed both ends. A value the plan
+ *  never sends is the gap.
+ *
+ *  An `absent` case reads the step's `omits`: a step that simply does not carry a
+ *  parameter says nothing, so the omission has to be stated to be checked.
+ *
+ *  A case names a query parameter, a body field, a path segment, or the verb. Run
+ *  34078857176 declared five cases the plan did send — two ids in a path segment,
+ *  two rejected methods — and drew an objection for each, because only the query
+ *  string and the body were read. */
+function caseObjections(registration) {
+    const changes = Array.isArray(registration.changes) ? registration.changes : [];
+    const plannedTests = registration.plannedTests ?? [];
+    const objections = [];
+    const seen = new Set();
+    for (const change of changes) {
+        const id = String(change?.id ?? "").trim();
+        const cases = change?.cases;
+        if (!id || !Array.isArray(cases) || cases.length === 0 || seen.has(id))
+            continue;
+        // A change nothing cites already draws `coverage:change:<id>`. A second
+        // objection about the same gap would need a second answer for one fix.
+        const citing = plannedTests.filter((plannedTest) => citesChange(plannedTest, id));
+        if (citing.length === 0)
+            continue;
+        seen.add(id);
+        const citingSteps = citing.flatMap((plannedTest) => {
+            const steps = plannedTest?.scenario?.steps;
+            return Array.isArray(steps) ? steps : [];
+        });
+        const missing = cases.filter((declared) => {
+            const param = String(declared?.param ?? "").trim();
+            if (!param)
+                return false;
+            if (declared.absent === true)
+                return !citingSteps.some((step) => omittedBy(step, param));
+            const slots = pathSlotsFor(citingSteps, cases, param);
+            const isMethod = param.toLowerCase() === METHOD_PARAM;
+            return !citingSteps.some((step) => valuesSent(step, param).some((sent) => sameValue(sent, declared.value)) ||
+                (isMethod && sendsAsMethod(step, declared.value)) ||
+                slots.some((slot) => sendsInPath(step, slot, declared.value)));
+        });
+        // One objection per case. A single objection listing three cases took one
+        // answer that addressed two of them and closed: run 34167252679 answered
+        // patch-highlight-guards for id="abc" and id=999999, and the third case, a
+        // second user's id no step ever sent, went with it. The id carries the
+        // rendered case, so it is the same string on the next registration whatever
+        // order the cases arrive in, and each one needs its own answer.
+        for (const declared of missing) {
+            const rendered = renderCase(declared);
+            objections.push({
+                objectionId: `coverage:cases:${id}:${rendered}`,
+                verifier: "coverage",
+                message: fillPlaceholders(COVERAGE_CONTRACT.objections.cases.message, { missing: rendered }),
+                evidence: `${citing.map((plannedTest) => plannedTest.plannedTestId).join(", ")} cite ${id}; no step of theirs sends ${rendered}.`,
+                suggestion: COVERAGE_CONTRACT.objections.cases.suggestion,
+            });
+        }
+    }
+    return objections;
+}
+/** A value written as a placeholder: the record an earlier step created. A step
+ *  sends the same spelling, so `{memberUserId}` in a case is that record and a
+ *  literal is a value the plan chose. */
+const PLACEHOLDER_VALUE = /^\{[A-Za-z][A-Za-z0-9]*\}$/;
+/** A parameter that names a record by id, by its own name. */
+const ID_PARAM = /id$/i;
+function isPlaceholderValue(value) {
+    return typeof value === "string" && PLACEHOLDER_VALUE.test(value.trim());
+}
+/** Every parameter some change rejects with a value, anywhere in the plan. A
+ *  rejection belongs to whichever change lists it, so one change's reject case
+ *  answers another's accept on the same parameter. An `absent` case is out: it
+ *  rejects a missing parameter, not a record that is not there. */
+function paramsWithValuedReject(changes) {
+    const rejected = new Set();
+    for (const change of changes) {
+        const cases = change?.cases;
+        if (!Array.isArray(cases))
+            continue;
+        for (const declared of cases) {
+            if (declared?.expect !== "reject" || declared?.absent === true || declared?.value === undefined)
+                continue;
+            const param = String(declared?.param ?? "").trim();
+            if (param)
+                rejected.add(param);
+        }
+    }
+    return rejected;
+}
+/** A route that takes a record by id can be given one that is not there, or one
+ *  that belongs to another parent, and answer as if it were. `DELETE
+ *  /collections/:id/members?userId=N` answered 200 "Member removed." for a user
+ *  that was never a member; six runs on that fixture planned the accept and the
+ *  absent-parameter rejection, and none planned the userId that is not a member.
+ *
+ *  Read off the PLAN alone — no diff, no route table. An accept whose value is a
+ *  placeholder names a record an earlier step created, and the parameter is an id
+ *  either by its name or because a citing test sends it as a path segment. */
+function rejectObjections(registration) {
+    const changes = Array.isArray(registration.changes) ? registration.changes : [];
+    const plannedTests = registration.plannedTests ?? [];
+    const rejected = paramsWithValuedReject(changes);
+    const objections = [];
+    const seen = new Set();
+    for (const change of changes) {
+        const id = String(change?.id ?? "").trim();
+        const cases = change?.cases;
+        if (!id || !Array.isArray(cases) || cases.length === 0 || seen.has(id))
+            continue;
+        // A change nothing cites already draws `coverage:change:<id>`, as above.
+        const citing = plannedTests.filter((plannedTest) => citesChange(plannedTest, id));
+        if (citing.length === 0)
+            continue;
+        seen.add(id);
+        const citingSteps = citing.flatMap((plannedTest) => {
+            const steps = plannedTest?.scenario?.steps;
+            return Array.isArray(steps) ? steps : [];
+        });
+        const unsatisfied = cases.find((declared) => {
+            const param = String(declared?.param ?? "").trim();
+            if (!param || param.toLowerCase() === METHOD_PARAM)
+                return false;
+            if (declared?.expect !== "accept" || declared?.absent === true)
+                return false;
+            if (!isPlaceholderValue(declared?.value))
+                return false;
+            if (!ID_PARAM.test(param) && pathSlotsFor(citingSteps, cases, param).length === 0)
+                return false;
+            return !rejected.has(param);
+        });
+        if (!unsatisfied)
+            continue;
+        const param = String(unsatisfied.param).trim();
+        const value = String(unsatisfied.value);
+        objections.push({
+            objectionId: `coverage:reject:${id}`,
+            verifier: "coverage",
+            message: fillPlaceholders(COVERAGE_CONTRACT.objections.reject.message, { param, value }),
+            evidence: `${id} declares ${param}=${value} (accept); no change in this plan declares a reject case on ${param} with a value.`,
+            suggestion: fillPlaceholders(COVERAGE_CONTRACT.objections.reject.suggestion, { param }),
+        });
+    }
+    return objections;
+}
+// ── The surface a change is on ──────────────────────────────────────────────
+/** The test types that reach each surface. An `e2e` test drives the page AND the
+ *  requests behind it, so it counts for both. */
+const TEST_TYPES_FOR = {
+    api: { types: new Set(["contract", "integration", "e2e"]), kind: "contract, integration or e2e", name: "API" },
+    page: { types: new Set(["ui", "e2e"]), kind: "ui or e2e", name: "page" },
+};
+/** Every surface a change states, without repeats and without a name nothing maps. */
+function declaredSurfaces(change) {
+    const named = change?.surfaces;
+    if (!Array.isArray(named))
+        return [];
+    return [...new Set(named.map((surface) => String(surface ?? "").trim()))].filter((surface) => surface in TEST_TYPES_FOR);
+}
+/** A change on a page needs a test that opens the page, and a change on the API
+ *  needs one that calls it. Run 34065056830 cited a page change from an API test
+ *  and nothing objected: no test in that plan clicked the filter the change added.
+ *
+ *  Read off the PLAN alone, like the other two halves. */
+function surfaceObjections(registration) {
+    const changes = Array.isArray(registration.changes) ? registration.changes : [];
+    const plannedTests = registration.plannedTests ?? [];
+    const objections = [];
+    const seen = new Set();
+    for (const change of changes) {
+        const id = String(change?.id ?? "").trim();
+        if (!id)
+            continue;
+        // A change nothing cites already draws `coverage:change:<id>`. A second
+        // objection about the same gap would need a second answer for one fix.
+        const citing = plannedTests.filter((plannedTest) => citesChange(plannedTest, id));
+        if (citing.length === 0)
+            continue;
+        for (const surface of declaredSurfaces(change)) {
+            const { types, kind, name } = TEST_TYPES_FOR[surface];
+            const objectionId = `coverage:surface:${id}:${surface}`;
+            if (seen.has(objectionId))
+                continue;
+            if (citing.some((plannedTest) => types.has(String(plannedTest?.scenario?.testType ?? "").trim().toLowerCase())))
+                continue;
+            seen.add(objectionId);
+            objections.push({
+                objectionId,
+                verifier: "coverage",
+                message: fillPlaceholders(COVERAGE_CONTRACT.objections.surface.message, { kind, surface: name }),
+                evidence: `${citing.map((plannedTest) => plannedTest.plannedTestId).join(", ")} cite ${id}; none of them is a ${kind} test.`,
+                suggestion: COVERAGE_CONTRACT.objections.surface.suggestion,
+            });
+        }
+    }
+    return objections;
+}
+/** One repository's changed files, and the name to attribute uncovered ones to.
+ *  Keying the objection id on the path alone let two repositories that each change
+ *  `src/App.tsx` share one id. A single-repository run names no repository in its
+ *  ids, which is the id it produced before there was a second one. */
+function repositoryPartitions(ctx) {
+    const named = Object.entries(ctx.changedFiles ?? {});
+    if (named.length < 2)
+        return [{ changedFiles: named[0]?.[1] ?? [] }];
+    return named.map(([repository, changedFiles]) => ({ repository, changedFiles: changedFiles ?? [] }));
+}
+/** The planned tests that count as covering one repository's change: those naming it,
+ *  plus those naming no repository. ABSENT IS A WILDCARD, as `checkEveryDeliveredTestRan`
+ *  and `collectExecutionOutcomes` read it — silence is nothing to disagree with. */
+function candidatesFor(plannedTests, repository) {
+    if (!repository)
+        return plannedTests;
+    return plannedTests.filter((plannedTest) => {
+        const named = String(plannedTest?.repository ?? "").trim();
+        return named === "" || named === repository;
+    });
+}
+/** The completeness check, over three surfaces: every declared behaviour, every
+ *  mutated route, and every changed file needs a test in the plan. More is
+ *  welcome, fewer is the objection. ONE RULE for the file half, no classification
+ *  — every changed file is a surface unless it cannot be product code, including a
+ *  removed one. A FLOOR, never a cap. Only the file half needs a diff. */
+export const coverage = {
+    name: "coverage",
+    run(registration, ctx) {
+        const objections = [
+            ...claimObjections(registration),
+            ...stateTestObjections(registration),
+            ...caseObjections(registration),
+            ...rejectObjections(registration),
+            ...surfaceObjections(registration),
+        ];
+        if (allChangedFiles(ctx).length === 0)
+            return objections;
+        const all = registration.plannedTests ?? [];
+        for (const { repository, changedFiles } of repositoryPartitions(ctx)) {
+            const cited = citedFiles(candidatesFor(all, repository));
+            const seen = new Set();
+            for (const entry of changedFiles) {
+                // Compared in the normalised spelling the citations are reduced to. The
+                // objection quotes the path as `--name-status` gave it, which for a
+                // non-ASCII name is the unquoted form, not the escaped one the diff shows.
+                const file = entry?.path ?? "";
+                const path = normalizeCitedPath(file);
+                if (!path || !couldBeProductCode(path) || seen.has(path))
+                    continue;
+                seen.add(path);
+                if (cited.has(path))
+                    continue;
+                objections.push({
+                    objectionId: repository
+                        ? `coverage:${repository}/${file}`
+                        : `coverage:${file}`,
+                    verifier: "coverage",
+                    message: COVERAGE_CONTRACT.objections.file.message,
+                    evidence: `${repository ? `${repository} ` : ""}${file}${entry?.deleted ? " (removed by this change)" : ""}: no planned test cites it in changedFile, routes or screenEvidence.`,
+                    suggestion: COVERAGE_CONTRACT.objections.file.suggestion,
+                });
+            }
+        }
+        return objections;
+    },
+};

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

@@ -0,0 +1,11 @@
+import { Objection } from "../types.js";
+import { Plan } from "../registerPlan.js";
+/** One test as it appears in the submitted report. */
+export interface DeliveredTest {
+    plannedTestId: string;
+}
+/** Verifier 5, post-execution half. Both directions on one pass: a report entry
+ *  that was in no plan, and a planned planned test that never shipped. The two lists
+ *  join on `plannedTestId` exactly — never a name, an endpoint or a similarity
+ *  score. Objections go to the report: the tests already exist. */
+export declare function checkDeliveredMatchesPlan(plan: Plan, delivered: DeliveredTest[]): Objection[];

package/build/recommendation/verifiers/deliveredMatchesPlan.js

@@ -0,0 +1,33 @@
+/** Verifier 5, post-execution half. Both directions on one pass: a report entry
+ *  that was in no plan, and a planned planned test that never shipped. The two lists
+ *  join on `plannedTestId` exactly — never a name, an endpoint or a similarity
+ *  score. Objections go to the report: the tests already exist. */
+export function checkDeliveredMatchesPlan(plan, delivered) {
+    const planned = new Set(plan.plannedTests.map((c) => c.plannedTestId));
+    const shipped = new Set(delivered.map((d) => d.plannedTestId));
+    const objections = [];
+    for (const id of shipped) {
+        if (planned.has(id))
+            continue;
+        objections.push({
+            objectionId: `deliveredMatchesPlan:${id}`,
+            verifier: "deliveredMatchesPlan",
+            message: "This test is in the report but was not in the plan. Every test written must be declared first.",
+            evidence: `delivered but unplanned: ${id}`,
+            suggestion: "Declare it in the plan and register it again, or take it out of the report.",
+        });
+    }
+    for (const id of planned) {
+        if (shipped.has(id))
+            continue;
+        objections.push({
+            objectionId: `deliveredMatchesPlan:${id}`,
+            verifier: "deliveredMatchesPlan",
+            plannedTestId: id,
+            message: "This test was in the plan and is not in the report. Say why it did not ship.",
+            evidence: `planned but not delivered: ${id}`,
+            suggestion: "Add the test to the report, or record in the report why it was dropped.",
+        });
+    }
+    return objections;
+}