@skyramp/mcp 0.4.0 → 0.4.1-rc.1

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,7 +83,6 @@ 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.",
@@ -98,7 +93,6 @@ export const EXISTING_COVERAGE_CONTRACT = {
 };
 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 +113,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,16 +138,6 @@ 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.",
@@ -225,7 +199,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 +219,135 @@ 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. Derive this case's value from that rule; the value itself need not appear in the pull request.",
+        },
+        // 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 no source states the value, 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/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;
+    },
+};

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

@@ -0,0 +1,14 @@
+import { Verifier } from "../types.js";
+/** Verifier 10. A case that states what the response must carry says where that
+ *  value came from, and the value did not come from the code under test.
+ *
+ *  This is the check for the failure that costs the most and looks like success: a
+ *  test whose expected value was copied out of the running app passes on the broken
+ *  code and fails the moment the code is fixed, so it defends the defect instead of
+ *  catching it. The plan is the only place the value can be decided, because by
+ *  generation time the response is the only thing to hand.
+ *
+ *  Silent on a case with no `expectedValue`: asserting the shape of a value nobody
+ *  states is a legitimate position, and the objection would fire on every
+ *  rejection case in every plan. */
+export declare const expectedValueSourced: Verifier;

package/build/recommendation/verifiers/expectedValueSourced.js

@@ -0,0 +1,149 @@
+import { allChangedFiles } from "../types.js";
+import { changedPathSet, normalizeCitedPath } from "./citedPath.js";
+import { EXPECTED_VALUE_SOURCED_CONTRACT as CONTRACT } from "../verifierContracts.js";
+import { appearsIn, searchable } from "../pullRequestText.js";
+function readSource(raw) {
+    const source = typeof raw === "string" ? raw.trim() : "";
+    if (source.length === 0)
+        return { kind: "none", file: "" };
+    if (/^code$/i.test(source))
+        return { kind: "code", file: "" };
+    if (/^(pr-title|pr-description)$/i.test(source))
+        return { kind: "pullRequest", file: "" };
+    const named = /^(spec|convention):(.*)$/i.exec(source);
+    if (!named)
+        return { kind: "none", file: "" };
+    const kind = named[1].toLowerCase();
+    const cited = named[2].split(/[#\u00a7]/)[0].replace(/(?::\d+)+(?:-\d+)?$/, "").trim();
+    // `spec:` with nothing after it names no file, so there is nothing to check and
+    // nothing to trust either. A path that IS written and still normalises away is a
+    // named source, and it is named wrongly.
+    if (cited.length === 0)
+        return { kind: "none", file: "" };
+    const file = normalizeCitedPath(cited);
+    return file ? { kind, file } : { kind: "unresolvable", file: "" };
+}
+/** One case's address, for the evidence line. A case has no id of its own, so it
+ *  is named the way the agent wrote it. */
+function caseLabel(change, entry) {
+    return `${String(change?.id ?? "?")}:${String(entry?.param ?? "?")}`;
+}
+/** Verifier 10. A case that states what the response must carry says where that
+ *  value came from, and the value did not come from the code under test.
+ *
+ *  This is the check for the failure that costs the most and looks like success: a
+ *  test whose expected value was copied out of the running app passes on the broken
+ *  code and fails the moment the code is fixed, so it defends the defect instead of
+ *  catching it. The plan is the only place the value can be decided, because by
+ *  generation time the response is the only thing to hand.
+ *
+ *  Silent on a case with no `expectedValue`: asserting the shape of a value nobody
+ *  states is a legitimate position, and the objection would fire on every
+ *  rejection case in every plan. */
+export const expectedValueSourced = {
+    name: "expectedValueSourced",
+    run(registration, ctx) {
+        const objections = [];
+        // The plan comes off disk, so both arrays hold their declared type only on the
+        // validated path. A throw here reaches the agent as `:crashed` and hides
+        // whatever real objection this pass would have raised.
+        // A `convention:` is trusted BECAUSE the pull request did not change it. Comparing
+        // against the run's own changed files is the only way to hold it to that.
+        const changed = changedPathSet(allChangedFiles(ctx), true);
+        const readable = typeof ctx?.citedFileExists === "function" ? ctx.citedFileExists : undefined;
+        const prText = searchable(ctx?.pullRequest ?? { title: "", description: "" });
+        const changes = Array.isArray(registration.changes) ? registration.changes : [];
+        for (const change of changes) {
+            const changeId = String(change?.id ?? "?");
+            const cases = Array.isArray(change?.cases) ? change.cases : [];
+            cases.forEach((entry, index) => {
+                // `undefined` is "this case states no expected value"; `null` is a stated
+                // expectation that the field comes back null, which needs a source like
+                // any other value.
+                if (!entry || entry.expectedValue === undefined)
+                    return;
+                const label = caseLabel(change, entry);
+                const where = `${label} (source "${String(entry.expectedFrom ?? "")}")`;
+                const source = readSource(entry.expectedFrom);
+                // One objection per CASE. A single objection listing three cases took one
+                // answer that addressed two of them and closed, and the id an answer is
+                // carried forward by must therefore name the case as well as the change.
+                const param = String(entry?.param ?? "").trim() || `case-${index + 1}`;
+                const raise = (kind, objection, evidence) => objections.push({
+                    objectionId: `expectedValueSourced:${kind}:${changeId}:${param}`,
+                    verifier: "expectedValueSourced",
+                    message: objection.message,
+                    evidence,
+                    suggestion: objection.suggestion,
+                });
+                if (source.kind === "none") {
+                    raise("unsourced", CONTRACT.objections.missingSource, `expected value with no usable \`expectedFrom\`: ${where}`);
+                }
+                else if (source.kind === "code") {
+                    raise("code", CONTRACT.objections.sourcedFromCode, `expected value read from the code under test: ${label} (expected ${JSON.stringify(entry.expectedValue)})`);
+                }
+                else if (source.kind === "unresolvable") {
+                    // A path no repository file can answer, so the citation opens nothing.
+                    raise("unreadable", CONTRACT.objections.unreadableSource, `source file not in the checkout: ${where}`);
+                }
+                else if (source.kind === "pullRequest") {
+                    // The RULE is what the pull request states; the value is derived from it.
+                    // "over 60 is rejected" states no 61, so looking for the value itself
+                    // objected to five correct cases in run 34414643135.
+                    const quote = String(change?.quote ?? "").trim();
+                    if (quote.length === 0) {
+                        raise("noQuote", CONTRACT.objections.quoteMissing, `${label} reads its value from the pull request; change ${changeId} states no \`quote\``);
+                    }
+                    else if (!appearsIn(prText, quote)) {
+                        raise("noQuote", CONTRACT.objections.quoteMissing, `${label} reads its value from the pull request; change ${changeId} quotes \`${quote}\`, which is in neither the title nor the description`);
+                    }
+                }
+                else if (!source.file) {
+                    // A kind that names no file and is not the pull request has nothing to check.
+                }
+                else if (source.kind === "convention" && changed.has(source.file)) {
+                    // Asked BEFORE readability: a convention cited in a file the pull request
+                    // DELETED is not a spelling problem, it is the rule this check exists for.
+                    raise("changedConvention", CONTRACT.objections.changedConvention, `convention cited in a file this pull request changed: ${where}`);
+                }
+                else if (readable && !readable(source.file)) {
+                    // A named source nothing opens is a source in name only.
+                    raise("unreadable", CONTRACT.objections.unreadableSource, `source file not in the checkout: ${where}`);
+                }
+            });
+        }
+        // A test that expects to fail asserts what the code does not return today, so a
+        // source outside the code has to state that value, and a case has to carry it.
+        const plannedTests = Array.isArray(registration?.plannedTests) ? registration.plannedTests : [];
+        for (const plannedTest of plannedTests) {
+            if (plannedTest?.declarations?.expected?.outcome !== "fail")
+                continue;
+            // A test that calls nothing sends no case, so it has no case to state a value
+            // on. That is the plan-only lane, whose ui tests declare a page and no steps.
+            if (!Array.isArray(plannedTest?.scenario?.steps) || plannedTest.scenario.steps.length === 0)
+                continue;
+            const citedIds = (Array.isArray(plannedTest?.declarations?.changes) ? plannedTest.declarations.changes : [])
+                .map((changeId) => (typeof changeId === "string" ? changeId.trim() : ""))
+                .filter((changeId) => changeId.length > 0);
+            // An id no change carries is the coverage check's finding, not this one.
+            const cited = changes.filter((change) => citedIds.includes(String(change?.id ?? "").trim()));
+            if (cited.length === 0)
+                continue;
+            const statesAValue = cited.some((change) => (Array.isArray(change?.cases) ? change.cases : []).some((entry) => entry && entry.expectedValue !== undefined));
+            if (statesAValue)
+                continue;
+            const plannedTestId = String(plannedTest?.plannedTestId ?? "").trim();
+            objections.push({
+                objectionId: `expectedValueSourced:noValue:${plannedTestId || "plan"}`,
+                verifier: "expectedValueSourced",
+                ...(plannedTestId ? { plannedTestId } : {}),
+                message: CONTRACT.objections.failWithoutValue.message,
+                evidence: `planned test ${plannedTestId || "(unnamed)"} expects to fail and cites ${cited
+                    .map((change) => String(change?.id ?? "?"))
+                    .join(", ")}; no case on those changes states an \`expectedValue\``,
+                suggestion: CONTRACT.objections.failWithoutValue.suggestion,
+            });
+        }
+        return objections;
+    },
+};

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

@@ -0,0 +1,52 @@
+import { Objection } from "../types.js";
+import { Plan } from "../registerPlan.js";
+/** One `issuesFound` entry, as much of it as these checks read. Every field is
+ *  optional: the entries come off a submitted report, and only the schema-validated
+ *  path guarantees a shape. */
+export interface ReportedIssueForTraceability {
+    description?: string;
+    category?: string;
+    sourceFile?: string;
+    plannedTestId?: string;
+    defectId?: string;
+}
+/** One delivered test, as much of it as these checks read. */
+export interface DeliveredForTraceability {
+    plannedTestId?: string;
+}
+/** Which lane the report comes from. Passed by the caller, not read off the
+ *  process, so the check stays a pure function of its inputs. */
+export interface TraceabilityLane {
+    /** The plan-only lane delivers nothing: `newTestsCreated` DECLARES the plan.
+     *  A planned test is as far as a trace can go there. */
+    planOnly: boolean;
+}
+/** Report-time. Every `category: bug` issue names the test that proves it, by
+ *  `plannedTestId` or through a `defectId`, or it draws an objection the agent
+ *  answers. Run 34283539284 reported six bugs with no test behind any of them and
+ *  nothing said so; the one test near the headline bug asserted a value that
+ *  passes against the broken output.
+ *
+ *  A test proves a bug when the run DELIVERED it and the plan declares it as one
+ *  that expects to fail. Both halves matter. A planned test the run never wrote is
+ *  a promise, not proof, and the plan-time objections already hold the agent to
+ *  those — except in the plan-only lane, which delivers nothing by design, so
+ *  there a planned test is as far as a trace can go. A test the plan declares
+ *  green is the run-34283539284 case itself: it passes against the broken output,
+ *  so it says nothing about the bug. The plan is the only place a delivered test's
+ *  expected outcome is written down, so a delivered test that joins to no planned
+ *  test carries no such declaration and does not count either.
+ *
+ *  A `defectId` counts the same way, and only for an id the plan's own `defects`
+ *  list declares: `declarations.defects` is free text until it is joined to that
+ *  list, so an unjoined id would let a report invent a defect and trace every bug
+ *  through it.
+ *
+ *  A declared `defectId` also counts when the agent answered `defects:untested:<id>`
+ *  at plan time (or closed it with a blocker). The plan-time verifier asked why no
+ *  test proves that defect and the agent said; asking again here is the same
+ *  question twice, and the answer is already published with the plan. */
+export declare function checkIssueTraceability(plan: Plan, delivered: DeliveredForTraceability[], issues: ReportedIssueForTraceability[], lane?: TraceabilityLane): Objection[];
+/** Report-time. Every defect the plan declared is an `issuesFound` entry that
+ *  names it by `defectId`. The review found it; the report must show it. */
+export declare function checkDefectsReported(plan: Plan, issues: ReportedIssueForTraceability[]): Objection[];