@skyramp/mcp 0.4.0 → 0.4.1-rc.2

package/build/recommendation/verifierContracts.js

@@ -11,7 +11,6 @@
 // evidence stays computed in the verifier.
 export const CHANGED_FILE_CONTRACT = {
     id: "changedFile",
-    declarationFields: ["declarations.changedFile", "declarations.screenEvidence.file"],
     objections: {
         notStated: {
             message: "This test does not state which changed file it targets.",
@@ -34,7 +33,6 @@ export const CHANGED_FILE_CONTRACT = {
 };
 export const SCREEN_ROUTE_CONTRACT = {
     id: "screenRoute",
-    declarationFields: ["declarations.elements.pageUrl", "declarations.screenEvidence.file", "declarations.changedFile"],
     objections: {
         mismatch: {
             message: "The page this UI test opens is not a page that renders the changed file it is about.",
@@ -49,7 +47,6 @@ export const SCREEN_ROUTE_CONTRACT = {
 };
 export const ENDPOINT_GROUNDED_CONTRACT = {
     id: "endpointGrounded",
-    declarationFields: ["steps[]", "testType", "declarations.routes"],
     objections: {
         uncited: {
             message: "A call this test makes cites no file that declares it.",
@@ -68,7 +65,6 @@ export const ENDPOINT_GROUNDED_CONTRACT = {
 };
 export const STATED_DIFFERENCE_CONTRACT = {
     id: "statedDifference",
-    declarationFields: ["steps[]", "testType", "scenarioName", "declarations.differsFrom"],
     objections: {
         unexplainedPair: {
             message: "Another planned test in this plan tests the same endpoint and neither says how they differ.",
@@ -87,18 +83,24 @@ export const STATED_DIFFERENCE_CONTRACT = {
 };
 export const EXISTING_COVERAGE_CONTRACT = {
     id: "existingCoverage",
-    declarationFields: ["declarations.existingTests"],
     objections: {
         citedTestMissing: {
             message: "This planned test names an existing test file that is not in the checkout.",
             suggestion: "Name the file repository-relative, spelled as the analysis lists it. Drop the entry if it names a test you did not read — naming none is an answer too.",
         },
+        maintainedTestMissing: {
+            message: "`maintains` names an existing test file that is not in the checkout.",
+            suggestion: "Name the file repository-relative, spelled as the analysis lists it. A maintenance entry is what makes its changes count as covered, so it has to name a file this run can edit.",
+        },
+        maintainedUnknownChange: {
+            message: "A `maintains` entry cites a change id that this plan does not declare.",
+            suggestion: "Spell the change's `id` exactly as your own `changes` list gives it — the match is exact apart from surrounding space. Declare the change if it is missing.",
+        },
     },
-    suggestion: "Which existing tests did you read on this change, and how does this planned test differ from them?",
+    suggestion: "Which existing tests did you read on this change, how does this planned test differ from them, and which changes does the maintenance you are doing cover?",
 };
 export const EXPECTED_OUTCOME_CONTRACT = {
     id: "expectedOutcome",
-    declarationFields: ["category", "declarations.expected.outcome", "declarations.expected.why"],
     objections: {
         // `{category}` is the planned test's own `category` value, quoted back to it so
         // the agent recognises the value it sent.
@@ -119,16 +121,6 @@ export const EXPECTED_OUTCOME_CONTRACT = {
 };
 export const UI_ELEMENT_GROUNDED_CONTRACT = {
     id: "uiElementGrounded",
-    declarationFields: [
-        "testType",
-        "steps[]",
-        "declarations.elements.items",
-        "declarations.elements.pageUrl",
-        "declarations.asserts",
-        "scenarioName",
-        "description",
-        "declarations.expected.why",
-    ],
     objections: {
         nogrounding: {
             message: "This UI test names no `elements.items`, so nothing says the elements it targets are on the page.",
@@ -154,20 +146,10 @@ export const UI_ELEMENT_GROUNDED_CONTRACT = {
 };
 export const COVERAGE_CONTRACT = {
     id: "coverage",
-    declarationFields: [
-        "changes",
-        "declarations.changes",
-        "declarations.changedFile",
-        "declarations.routes",
-        "declarations.screenEvidence.file",
-        "declarations.startState",
-        "changes[].cases",
-        "changes[].surfaces",
-    ],
     objections: {
         change: {
             message: "This declared change has no test in the plan.",
-            suggestion: "Plan a test that exercises it. 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 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.",
         },
         noChanges: {
             message: "The plan declares no changes, so nothing says what the pull request must make different.",
@@ -225,7 +207,6 @@ export const COVERAGE_CONTRACT = {
 };
 export const REMOVED_ELEMENT_GUARDED_CONTRACT = {
     id: "removedElementGuarded",
-    declarationFields: ["declarations.elements.items", "declarations.asserts"],
     objections: {
         // v1 resolved a removed element to a page in the server, and fell back to the
         // root pages when the import graph found none, so that an element whose page
@@ -246,6 +227,143 @@ export const REMOVED_ELEMENT_GUARDED_CONTRACT = {
     },
     suggestion: "Does every element this diff removes have a planned test that asserts it is gone, and does no test claim a renamed identifier is gone?",
 };
+export const EXPECTED_VALUE_SOURCED_CONTRACT = {
+    id: "expectedValueSourced",
+    objections: {
+        // The whole point of the check. A value read off the running app is the one
+        // source that cannot disagree with a defect, so a test built from it passes
+        // on the broken code and fails once the code is fixed.
+        sourcedFromCode: {
+            message: "This case expects a value it read from the code as it stands, so a defect in that code becomes what the test demands.",
+            suggestion: "Read the value from the pull request title or description, from a requirements file the description names, or from a convention the application already follows elsewhere, and name that source. If none of them states it, leave `expectedValue` out and assert the shape instead.",
+        },
+        missingSource: {
+            message: "This case states an expected value and does not say where the value came from.",
+            suggestion: "Set `expectedFrom` to `pr-title`, `pr-description`, `spec:<path>`, `convention:<file:line>` or `code`.",
+        },
+        unreadableSource: {
+            message: "This case names a file as the source of its expected value, and that file is not in the checkout.",
+            suggestion: "Give the path as the repository spells it, from the repository root. If the file is not there, the value has no source: read it from the pull request title or description instead, or leave `expectedValue` out and assert the shape.",
+        },
+        // `convention:` is trusted for one reason: the pull request did not write the rule,
+        // so the rule can still disagree with the pull request. Cited inside the diff, the
+        // same change decides the behaviour and decides what counts as correct.
+        //
+        // Says only that, and not that the value came from the code under test: a large
+        // diff carries changed files that have nothing to do with this case, and the check
+        // cannot tell those from the ones it tests. Answerable for that reason.
+        changedConvention: {
+            message: "This case reads its expected value from a line this pull request writes, so the same change decides both the behaviour and what counts as correct.",
+            suggestion: "Cite a file the pull request leaves alone, or read the value from the description or a requirements file. If the cited file is changed but has nothing to do with this case, say so as the answer.",
+        },
+        // The server rendered the prompt, so it holds the words the run was given. It
+        // checks the RULE and not the value: "over 60 is rejected" states no 61, and run
+        // 34414643135 objected to five cases whose values that rule decides.
+        quoteMissing: {
+            message: "This case reads its value from the pull request, and its change does not quote the sentence that states the rule.",
+            suggestion: "Put the sentence from the title or description on the change as `quote`, as written there. If that sentence states the rule and not the number, put the rule in `derived` and leave `expectedValue` out.",
+        },
+        // The other half of the same reading. Run 34434835959 declared
+        // `expectedValue: 159.998` from `pr-description` on a change whose quote states
+        // how a percentage discount works and writes no number; the agent computed 10%
+        // of a subtotal it had seen and attributed the result to the description.
+        valueNotQuoted: {
+            message: "This case reads its value from the pull request, and the pull request does not state this value.",
+            suggestion: "Quote the sentence that states it, or, if the pull request states a rule, put the rule in `derived` and leave `expectedValue` out; the test computes the value from what it sent.",
+        },
+        // A test that expects to fail asserts what the code does not return today, so
+        // some source outside the code states that value. Run 34406282133 declared such
+        // tests and put `expectedValue` on no case at all.
+        failWithoutValue: {
+            message: "This test expects to fail, and no case on the changes it cites states the value it must assert.",
+            suggestion: "Put the value the code does not return today on the case this test sends, as `expectedValue`, and name where you read it. If the source states a rule rather than a number, put the rule in `derived` instead. If no source states either, answer with what the test asserts instead and where that comes from.",
+        },
+    },
+    suggestion: "Where does the correct value for this case come from?",
+};
+export const REQUIREMENT_SOURCED_CONTRACT = {
+    id: "requirementSourced",
+    objections: {
+        // `{change}` is the change id. Nothing on the server parses a pull request, so
+        // this field is the only record of where the change was read. An unrecognised
+        // spelling lands here: one that passed would be a check a typo switches off.
+        unsourced: {
+            message: "Change `{change}` does not name a source the plan accepts: `pr-title`, `pr-description`, `spec:<path>` or `diff`.",
+            suggestion: "Set `source` on this change to `pr-title` or `pr-description`, to `spec:<path>` for the requirements file that states it, or to `diff`.",
+        },
+        // `{source}` is the source text as the plan wrote it. A path that no file
+        // answers is a citation nobody can check.
+        unreadable: {
+            message: "Change `{change}` cites `{source}`, and the checkout holds no file at that path.",
+            suggestion: "Cite the requirements file by the path the checkout holds, or name the source you actually read this change in.",
+        },
+        // A conflict is a disagreement between a requirement and the code. A change
+        // read off the diff is the code, so it has no second side. The check reads the
+        // sources the cited changes name, and says only that, not where they came from.
+        fromDiff: {
+            message: "This test reports a requirement conflict, and none of the changes it cites was read from the pull request or a requirements file.",
+            suggestion: "Cite a change you read in the pull request or in a requirements file, or report this test as something other than a requirement conflict.",
+        },
+        // The server rendered the prompt, so it holds the title and description the run
+        // was given. A requirements file the pull request never names is a file the agent
+        // found by looking, which is reading the repository, not reading a requirement.
+        notNamed: {
+            message: "Change `{change}` cites `{source}`, and the pull request names no such file.",
+            suggestion: "Cite a file the title or description names. If neither names it, you read the change in the repository, so set `source` to `diff`.",
+        },
+        // Says only what was read: this pull request arrived with no words in it.
+        emptyPullRequest: {
+            message: "Change `{change}` says it was read from the pull request, and the pull request has no title or description.",
+            suggestion: "Set `source` to `spec:<path>` for the requirements file that states this change, or to `diff` if only the code states it.",
+        },
+        // The quote is what makes the claim checkable: without it the server has the
+        // pull request's words and no way to know which of them the change rests on.
+        notQuoted: {
+            message: "This test reports a requirement conflict, and change `{change}` quotes words the pull request does not carry.",
+            suggestion: "Quote the requirement as the title or description spells it, word for word. If you cannot find those words there, the change came from somewhere else: say where in `source`.",
+        },
+        unquoted: {
+            message: "This test reports a requirement conflict, and change `{change}` does not quote the requirement.",
+            suggestion: "Set `quote` on that change to the sentence in the title or description that states the requirement.",
+        },
+        // Nothing else objects to this: the coverage check reads a change and asks which
+        // test proves it, so a test that cites nothing is a test it never reaches.
+        noChange: {
+            message: "This test reports a requirement conflict and cites no change, so nothing says where the requirement came from.",
+            suggestion: "Name in `changes` the change that states the requirement, or report this test as something other than a requirement conflict.",
+        },
+    },
+    suggestion: "Does every change name where you read it, and does every requirement-conflict test cite a change that came from the pull request or a requirements file?",
+};
+export const DEFECTS_CONTRACT = {
+    id: "defects",
+    objections: {
+        // Run 34283539284 reported six bugs with no test behind them: the review
+        // happened at report time, after the plan was frozen. A plan that lists no
+        // defect is where the review is asked for, before the plan.
+        none: {
+            message: "The plan declares no defects, so nothing says the code review happened before the plan.",
+            suggestion: "Review the code that serves each change — the handler, the functions it calls to read or write data, the component and what it calls — and list each defect in `defects`. If the review found none, answer in one line what you read.",
+        },
+        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 something stopped this run from writing the test, answer it and set `blocker` to what stopped it.",
+        },
+        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.",
+        },
+        unknownId: {
+            message: "A planned test cites a defect id that this plan does not declare.",
+            suggestion: "Spell the defect's `id` exactly as your own `defects` list gives it — the match is exact apart from surrounding space. Declare the defect if it is missing.",
+        },
+        conflictWithoutDefect: {
+            message: "This test reports a requirement conflict and cites no defect.",
+            suggestion: "List the conflict in `defects`: the file and line that contradict the requirement, and a description that quotes the requirement. Cite that id from this test.",
+        },
+    },
+    suggestion: "Which planned test proves each defect the review found, and for one nothing proves, why does it need no test?",
+};
 /** Fills a contract sentence's `{placeholder}` spans from the run's or the
  *  planned test's own values. A placeholder with no value is left as written rather
  *  than blanked, so a missed key shows up as `{knob}` instead of reading as a gap

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

@@ -1,4 +1,14 @@
 import { Verifier } from "../types.js";
+/** One declared case as the objection spells it.
+ *
+ *  Exported: `expectedValueSourced` keys its objections on the same rendering, so
+ *  two cases on one parameter are two objections there too. */
+export declare function renderCase(declared: {
+    param: string;
+    value?: unknown;
+    absent?: true;
+    expect: string;
+}): string;
 /** 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

package/build/recommendation/verifiers/coverage.js

@@ -1,5 +1,6 @@
 import { allChangedFiles } from "../types.js";
-import { LOCKFILE, NOT_A_ROUTE_FILE, NOT_SOURCE_DIR } from "./endpointGrounded.js";
+import { canonicalJson } from "../../utils/canonicalJson.js";
+import { escapesRepo, 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";
@@ -37,9 +38,31 @@ function citedFiles(plannedTests) {
     }
     return cited;
 }
-/** The behaviour ids some planned test cites, trimmed. */
-function citedBehaviors(plannedTests) {
+/** The behaviour ids the plan cites, trimmed — from its planned tests AND from the
+ *  existing tests it maintains. A change covered by a spec this run edits is tested;
+ *  counting only planned tests made `coverage:change:` unanswerable for a correct
+ *  maintenance decision, since that objection closes with a `blocker` alone and
+ *  nothing stopped the run.
+ *
+ *  A maintenance entry credits its ids only when the file it names RESOLVES in the
+ *  checkout. `existingCoverage` objects about an unresolvable one, but that objection
+ *  takes prose, so crediting first would have handed `coverage:change:` — the one
+ *  class a sentence cannot close, and the reason `BLOCKER_ONLY_PREFIX` exists — a
+ *  route out through a file name nobody can open. */
+function citedBehaviors(plannedTests, maintains = [], fileResolves = () => false) {
     const cited = new Set();
+    for (const entry of maintains) {
+        const ids = entry?.changes;
+        if (!Array.isArray(ids))
+            continue;
+        if (!fileResolves(String(entry?.file ?? "").trim()))
+            continue;
+        for (const id of ids) {
+            const trimmed = String(id ?? "").trim();
+            if (trimmed)
+                cited.add(trimmed);
+        }
+    }
     for (const plannedTest of plannedTests) {
         const declared = plannedTest?.declarations?.changes;
         if (!Array.isArray(declared))
@@ -58,7 +81,7 @@ function citedBehaviors(plannedTests) {
  *
  *  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) {
+function claimObjections(registration, ctx) {
     const changes = Array.isArray(registration.changes) ? registration.changes : [];
     const plannedTests = registration.plannedTests ?? [];
     const objections = [];
@@ -79,7 +102,8 @@ function claimObjections(registration) {
         if (id)
             declared.add(id);
     }
-    const cited = citedBehaviors(plannedTests);
+    const maintains = Array.isArray(registration.maintains) ? registration.maintains : [];
+    const cited = citedBehaviors(plannedTests, maintains, (file) => !!file && !escapesRepo(file) && ctx.citedFileExists(file));
     const seen = new Set();
     for (const change of changes) {
         const id = String(change?.id ?? "").trim();
@@ -207,28 +231,100 @@ function sameValue(sent, declared) {
         return false;
     if (declared === null)
         return sent === null;
+    // A list or an object compares WHOLE, and only against another one. `String` made
+    // every structure a scalar: `String(["alpha","beta"])` is `"alpha,beta"`, so a
+    // case declaring that string was answered by a list no entry of which sends it,
+    // and `String([])` is `""`, so an empty list answered `tags=""`. An entry of the
+    // list is still a scalar of its own and still answers a scalar case.
+    const sentIsStructure = sent !== null && typeof sent === "object";
+    const declaredIsStructure = typeof declared === "object";
+    if (sentIsStructure || declaredIsStructure) {
+        // Both sides are non-null objects by the guard above, so neither call can be
+        // the `undefined` the helper returns for a value JSON renders as nothing.
+        return sentIsStructure && declaredIsStructure && canonicalJson(sent) === canonicalJson(declared);
+    }
     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. */
+/** The path a case's `param` names, as segments. Numeric segments drop: a plan
+ *  writes `items.0` for "the line items", not for the first one only. */
+function fieldPath(param) {
+    const segments = param
+        .split(/[.[\]]/)
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0 && !/^\d+$/.test(segment));
+    return segments.length > 0 ? segments : [param];
+}
+/** Every value at `rest`, below a key that already matched the path's first
+ *  segment. Only arrays are transparent between segments, so `billing.postcode` is
+ *  not sent by `billing.shipping.postcode`. A matched array yields the array AND
+ *  its entries, because `String(["beta"]) === "beta"` matched a one-item list only.
+ *
+ *  `open` holds the objects on the way down to this one, so a payload that points
+ *  back at itself ends rather than recurses. It is the way down and not every
+ *  object seen, because one object reached twice by two different routes is two
+ *  values the payload really sends. */
+function valuesAt(value, rest, open) {
+    if (rest.length === 0)
+        return [value, ...(Array.isArray(value) ? value : [])];
+    if (value === null || typeof value !== "object" || open.has(value))
+        return [];
+    open.add(value);
+    const found = Array.isArray(value)
+        ? value.flatMap((entry) => valuesAt(entry, rest, open))
+        : (() => {
+            const [head, ...next] = rest;
+            const fields = value;
+            return head in fields ? valuesAt(fields[head], next, open) : [];
+        })();
+    open.delete(value);
+    return found;
+}
+/** Every value carried at `path`, anywhere inside one payload. Only the FIRST
+ *  segment is found at any depth, which is what makes `quantity` find
+ *  `items.0.quantity`; the rest of the path is matched by `valuesAt`. */
+function valuesUnder(payload, path, open = new Set()) {
+    // A body that points back at itself ends the walk; how deeply a real body nests
+    // is the payload's business, and a depth cap here read a valid one as sending
+    // nothing.
+    if (payload === null || typeof payload !== "object" || open.has(payload))
+        return [];
+    open.add(payload);
+    const found = [];
+    if (Array.isArray(payload)) {
+        for (const entry of payload)
+            found.push(...valuesUnder(entry, path, open));
+    }
+    else {
+        for (const [key, value] of Object.entries(payload)) {
+            if (key === path[0])
+                found.push(...valuesAt(value, path.slice(1), open));
+            // The same head, deeper: this is the any-depth half of the search.
+            found.push(...valuesUnder(value, path, open));
+        }
+    }
+    open.delete(payload);
+    return found;
+}
+/** Every value of one parameter a step sends: the query string, the `queryParams`
+ *  object, or anywhere inside the request body. */
 function valuesSent(step, param) {
     const found = [];
+    // A query parameter is flat and its own name can hold a dot, so the query answers
+    // the parameter as written. Only the body is read as a path.
     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]);
-        }
+    const queryParams = step?.queryParams;
+    if (queryParams && typeof queryParams === "object" && !Array.isArray(queryParams)) {
+        const fields = queryParams;
+        if (param in fields)
+            found.push(fields[param]);
     }
+    found.push(...valuesUnder(step?.requestBody, fieldPath(param)));
     return found;
 }
 /** The parameter name that names the request's verb rather than one of its inputs. */
@@ -316,6 +412,15 @@ function sendsInPath(step, slot, value) {
     }
     return sameValue(segments[slot.index], value);
 }
+/** Whether a step writes the declared value as one of its own path segments. The
+ *  fallback for a plan that spells every route concretely, so no slot exists. Only
+ *  used when the parameter has no slot at all: where the plan does say where the
+ *  parameter sits, the slot rule stands. */
+function sendsAsPathSegment(step, value) {
+    if (value === undefined || value === null || String(value).trim().length === 0)
+        return false;
+    return pathSegments(step).some((segment) => sameValue(segment.trim(), 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();
@@ -332,8 +437,11 @@ function omittedBy(step, param) {
         return false;
     return omits.some((named) => String(named ?? "").trim() === param);
 }
-/** One declared case as the objection spells it. */
-function renderCase(declared) {
+/** One declared case as the objection spells it.
+ *
+ *  Exported: `expectedValueSourced` keys its objections on the same rendering, so
+ *  two cases on one parameter are two objections there too. */
+export 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})`;
@@ -381,6 +489,7 @@ function caseObjections(registration) {
             const steps = plannedTest?.scenario?.steps;
             return Array.isArray(steps) ? steps : [];
         });
+        const writesAnyPlaceholder = citingSteps.some((step) => pathSegments(step).some((segment) => placeholderName(segment) !== undefined));
         const missing = cases.filter((declared) => {
             const param = String(declared?.param ?? "").trim();
             if (!param)
@@ -389,9 +498,14 @@ function caseObjections(registration) {
                 return !citingSteps.some((step) => omittedBy(step, param));
             const slots = pathSlotsFor(citingSteps, cases, param);
             const isMethod = param.toLowerCase() === METHOD_PARAM;
+            // Only for a plan that wrote NO template at all, and only for a parameter that
+            // names a record. Wider than that, the URL answered everything: a `quantity=5`
+            // case passed on `GET /api/v1/orders/5`.
+            const byValueInPath = slots.length === 0 && !writesAnyPlaceholder && ID_PARAM.test(param) && !isMethod;
             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)));
+                slots.some((slot) => sendsInPath(step, slot, declared.value)) ||
+                (byValueInPath && sendsAsPathSegment(step, 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
@@ -405,7 +519,13 @@ function caseObjections(registration) {
                 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}.`,
+                evidence: `${citing.map((plannedTest) => plannedTest.plannedTestId).join(", ")} cite ${id}; no step of theirs sends ${rendered}.` +
+                    // Which spelling WOULD have matched, or the agent re-sends the same plan.
+                    // Id parameters only: it asked for `{quantity}` in a route otherwise.
+                    (ID_PARAM.test(String(declared?.param ?? "").trim()) &&
+                        citingSteps.some((step) => sendsAsPathSegment(step, declared.value))
+                        ? ` A step's path carries that value, in a segment this plan's own placeholders do not name \`${String(declared?.param ?? "").trim()}\`; write the route as a template, with \`{${String(declared?.param ?? "").trim()}}\` where it sits.`
+                        : ""),
                 suggestion: COVERAGE_CONTRACT.objections.cases.suggestion,
             });
         }
@@ -416,8 +536,10 @@ function caseObjections(registration) {
  *  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;
+/** A parameter that names a record by id, by its own name: `id` itself, `id` after
+ *  a separator, or `Id`/`ID` starting a word. `/id$/i` also read `paid`, `valid` and
+ *  `fluid` as record ids, which let `valid=5` take its value from `/orders/5`. */
+const ID_PARAM = /(?:^|[_\-.])[Ii][Dd]$|[a-z0-9](?:Id|ID)$/;
 function isPlaceholderValue(value) {
     return typeof value === "string" && PLACEHOLDER_VALUE.test(value.trim());
 }
@@ -578,7 +700,7 @@ export const coverage = {
     name: "coverage",
     run(registration, ctx) {
         const objections = [
-            ...claimObjections(registration),
+            ...claimObjections(registration, ctx),
             ...stateTestObjections(registration),
             ...caseObjections(registration),
             ...rejectObjections(registration),

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

@@ -0,0 +1,9 @@
+import { Verifier } from "../types.js";
+/** Every declared defect needs one planned test that cites it and expects to fail,
+ *  or an answer. Read off the PLAN alone, like the behaviour half of coverage: the
+ *  agent declared the defects itself, so there is always something to hold it to.
+ *
+ *  The one objection about the list as a whole, `defects:none`, is what asks for
+ *  the review before the plan: without it the review's only output was
+ *  `issuesFound`, which exists at report time, after every test is generated. */
+export declare const defects: Verifier;

package/build/recommendation/verifiers/defects.js

@@ -0,0 +1,117 @@
+import { normalizeCategory } from "../../types/TestRecommendation.js";
+import { DEFECTS_CONTRACT } from "../verifierContracts.js";
+/** A defect id as the plan spells it: trimmed, and exact otherwise. */
+function idKey(raw) {
+    return typeof raw === "string" ? raw.trim() : "";
+}
+/** The defect ids one planned test cites, trimmed and without repeats. Read
+ *  defensively: the plan comes off disk, so the array type holds only on the
+ *  validated path, and a throw here would hide every other objection. */
+function citedDefects(plannedTest) {
+    const declared = plannedTest?.declarations?.defects;
+    if (!Array.isArray(declared))
+        return [];
+    return [...new Set(declared.map(idKey))].filter(Boolean);
+}
+/** Whether a planned test expects to fail. Undeclared reads as not failing: a test
+ *  that says nothing about its outcome proves nothing about a defect either. */
+function expectsToFail(plannedTest) {
+    return plannedTest?.declarations?.expected?.outcome === "fail";
+}
+/** Where the defect sits, as the objection quotes it. */
+function locate(defect) {
+    const file = String(defect?.file ?? "").trim() || "no file";
+    return typeof defect?.line === "number" ? `${file}:${defect.line}` : file;
+}
+/** Every declared defect needs one planned test that cites it and expects to fail,
+ *  or an answer. Read off the PLAN alone, like the behaviour half of coverage: the
+ *  agent declared the defects itself, so there is always something to hold it to.
+ *
+ *  The one objection about the list as a whole, `defects:none`, is what asks for
+ *  the review before the plan: without it the review's only output was
+ *  `issuesFound`, which exists at report time, after every test is generated. */
+export const defects = {
+    name: "defects",
+    run(registration, _ctx) {
+        const declared = (Array.isArray(registration.defects) ? registration.defects : []).filter((defect) => idKey(defect?.id).length > 0);
+        const plannedTests = registration.plannedTests ?? [];
+        const objections = [];
+        // An empty list is its own objection and NOT an early return: a plan that
+        // declares nothing can still cite `D1` from a planned test, and that citation
+        // is a second mistake with a second answer. Returning here left it unraised,
+        // so one answer to `defects:none` closed the whole thing.
+        if (declared.length === 0) {
+            objections.push({
+                objectionId: "defects:none",
+                verifier: "defects",
+                message: DEFECTS_CONTRACT.objections.none.message,
+                evidence: "the registered plan declares an empty `defects` list.",
+                suggestion: DEFECTS_CONTRACT.objections.none.suggestion,
+            });
+        }
+        const known = new Set(declared.map((defect) => idKey(defect.id)));
+        const seen = new Set();
+        for (const defect of declared) {
+            const id = idKey(defect.id);
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            const citing = plannedTests.filter((plannedTest) => citedDefects(plannedTest).includes(id));
+            if (citing.length === 0) {
+                objections.push({
+                    // Keyed on the defect's id, not its position: the agent reorders the
+                    // list between registrations and the answer has to follow the defect.
+                    objectionId: `defects:untested:${id}`,
+                    verifier: "defects",
+                    message: DEFECTS_CONTRACT.objections.untested.message,
+                    evidence: `${id} (${locate(defect)}): "${String(defect.description ?? "").trim()}"; no planned test cites it in \`defects\`.`,
+                    suggestion: DEFECTS_CONTRACT.objections.untested.suggestion,
+                });
+                continue;
+            }
+            if (citing.some(expectsToFail))
+                continue;
+            objections.push({
+                objectionId: `defects:expectedPass:${id}`,
+                verifier: "defects",
+                message: DEFECTS_CONTRACT.objections.expectedPass.message,
+                evidence: `${citing.map((plannedTest) => plannedTest.plannedTestId).join(", ")} cite ${id}; none declares \`expected.outcome: fail\`.`,
+                suggestion: DEFECTS_CONTRACT.objections.expectedPass.suggestion,
+            });
+        }
+        // One objection per (planned test, unknown id): each is its own misspelling
+        // and owes its own answer.
+        for (const plannedTest of plannedTests) {
+            for (const id of citedDefects(plannedTest)) {
+                if (known.has(id))
+                    continue;
+                objections.push({
+                    objectionId: `defects:unknownId:${plannedTest.plannedTestId}:${id}`,
+                    verifier: "defects",
+                    plannedTestId: plannedTest.plannedTestId,
+                    message: DEFECTS_CONTRACT.objections.unknownId.message,
+                    evidence: `${plannedTest.plannedTestId} cites "${id}"; this plan declares ${known.size > 0 ? [...known].map((declaredId) => `"${declaredId}"`).join(", ") : "no defects"}.`,
+                    suggestion: DEFECTS_CONTRACT.objections.unknownId.suggestion,
+                });
+            }
+        }
+        // A requirement the code does not meet is a defect, and that defect's `file` is
+        // the code that contradicts the requirement.
+        for (const plannedTest of plannedTests) {
+            if (normalizeCategory(plannedTest?.scenario?.category) !== "requirement_conflict")
+                continue;
+            if (citedDefects(plannedTest).length > 0)
+                continue;
+            const plannedTestId = idKey(plannedTest?.plannedTestId) || "plan";
+            objections.push({
+                objectionId: `defects:conflictWithoutDefect:${plannedTestId}`,
+                verifier: "defects",
+                plannedTestId: plannedTest?.plannedTestId,
+                message: DEFECTS_CONTRACT.objections.conflictWithoutDefect.message,
+                evidence: `${plannedTestId} is planned as \`requirement_conflict\` and cites no defect in \`defects\`.`,
+                suggestion: DEFECTS_CONTRACT.objections.conflictWithoutDefect.suggestion,
+            });
+        }
+        return objections;
+    },
+};