@skyramp/mcp 0.4.0 → 0.4.1-rc.2

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

@@ -4,8 +4,30 @@ import { Plan } from "../registerPlan.js";
 export interface DeliveredTest {
     plannedTestId: string;
 }
+/** One maintenance row that LEFT COVERAGE BEHIND, as the report publishes it. The
+ *  caller filters by action: a row this check is handed is one whose edit a later
+ *  run can still rely on, so a no-op assessment and a deleted test never reach it.
+ *  Both fields are absolute paths. */
+export interface MaintainedTest {
+    testFilePath?: string;
+    /** Where the edit landed when that is not the spec — a page object it delegates
+     *  its selectors to. Counted, so a spec maintained through its POM still joins. */
+    pomFile?: 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[];
+/** The maintenance mirror of "planned but not delivered". A `maintains` entry is
+ *  what makes its changes count as covered, and until this ran nothing downstream
+ *  checked the file was edited at all: the plan claimed it, `coverage` credited it,
+ *  and the report published it, three records that never met.
+ *
+ *  Matched with `testFileMatches`, which keeps the directories: the plan names a file
+ *  repository-relative and a row names it absolutely, so the row's path has to END at
+ *  the claimed one on a segment boundary. Basename alone would let an edit to
+ *  `tests/admin/navbar.spec.ts` answer for `tests/store/navbar.spec.ts`. Answerable,
+ *  unlike `coverage:change:` — an edit that landed somewhere the rows do not name is
+ *  a real case, and the answer says where. */
+export declare function checkMaintenanceDelivered(plan: Plan, maintained: MaintainedTest[]): Objection[];

package/build/recommendation/verifiers/deliveredMatchesPlan.js

@@ -1,3 +1,4 @@
+import { testFileMatches } from "../../utils/utils.js";
 /** 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
@@ -31,3 +32,45 @@ export function checkDeliveredMatchesPlan(plan, delivered) {
     }
     return objections;
 }
+/** The maintenance mirror of "planned but not delivered". A `maintains` entry is
+ *  what makes its changes count as covered, and until this ran nothing downstream
+ *  checked the file was edited at all: the plan claimed it, `coverage` credited it,
+ *  and the report published it, three records that never met.
+ *
+ *  Matched with `testFileMatches`, which keeps the directories: the plan names a file
+ *  repository-relative and a row names it absolutely, so the row's path has to END at
+ *  the claimed one on a segment boundary. Basename alone would let an edit to
+ *  `tests/admin/navbar.spec.ts` answer for `tests/store/navbar.spec.ts`. Answerable,
+ *  unlike `coverage:change:` — an edit that landed somewhere the rows do not name is
+ *  a real case, and the answer says where. */
+export function checkMaintenanceDelivered(plan, maintained) {
+    const claimed = Array.isArray(plan?.maintains) ? plan.maintains : [];
+    if (claimed.length === 0)
+        return [];
+    const text = (value) => (typeof value === "string" ? value.trim() : "");
+    const editedPaths = [];
+    for (const row of Array.isArray(maintained) ? maintained : []) {
+        for (const full of [text(row?.testFilePath), text(row?.pomFile)])
+            if (full)
+                editedPaths.push(full);
+    }
+    const objections = [];
+    const seen = new Set();
+    for (const entry of claimed) {
+        const file = text(entry?.file);
+        if (!file || editedPaths.some((full) => testFileMatches(full, file)))
+            continue;
+        const objectionId = `deliveredMatchesPlan:maintains:${file}`;
+        if (seen.has(objectionId))
+            continue;
+        seen.add(objectionId);
+        objections.push({
+            objectionId,
+            verifier: "deliveredMatchesPlan",
+            message: "The plan says this existing test covers a change, and no maintenance row says it was edited.",
+            evidence: `plan maintains ${file}; the maintenance rows that changed a file name ${editedPaths.length > 0 ? editedPaths.join(", ") : "no file"}`,
+            suggestion: "The maintenance rows come from the triage, not from this call, so this is not a field to fill in here: make the edit on the file you claimed and let the maintenance step record it, or drop the entry from `maintains` and register the plan again — coverage counted the change because the plan said you were editing that test. If the test already covered the change and needed no edit, or the edit landed somewhere the rows do not name, say which as the answer.",
+        });
+    }
+    return objections;
+}

package/build/recommendation/verifiers/existingCoverage.js

@@ -42,6 +42,59 @@ export const existingCoverage = {
                 suggestion: EXISTING_COVERAGE_CONTRACT.objections.citedTestMissing.suggestion,
             });
         }
+        // `maintains` is what makes a change covered by an edited test count in
+        // `coverage`, so the same file check applies to it, plus the change ids it
+        // cites: an id no `changes` entry declares would credit coverage for nothing.
+        const maintains = Array.isArray(registration?.maintains) ? registration.maintains : [];
+        const declaredChanges = new Set((Array.isArray(registration?.changes) ? registration.changes : [])
+            .map((change) => String(change?.id ?? "").trim())
+            .filter(Boolean));
+        // Gathered per file BEFORE any objection is pushed: the schema allows two
+        // entries naming the same file, the objection id is keyed on the file so the
+        // agent answers a file once, and keying alone dropped the second entry's ids.
+        const missingByFile = new Map();
+        const unknownByFile = new Map();
+        for (const entry of maintains) {
+            const file = String(entry?.file ?? "").trim();
+            const key = file || "unnamed";
+            const missing = !file
+                ? "an entry names no file"
+                : escapesRepo(file)
+                    ? `${file} (points outside the repository)`
+                    : !ctx.citedFileExists(file)
+                        ? `${file} (not found)`
+                        : "";
+            if (missing && !missingByFile.has(key))
+                missingByFile.set(key, missing);
+            const ids = Array.isArray(entry?.changes) ? entry.changes : [];
+            for (const raw of ids) {
+                const id = String(raw ?? "").trim();
+                if (!id || declaredChanges.has(id))
+                    continue;
+                const unknown = unknownByFile.get(key) ?? [];
+                if (!unknown.includes(id))
+                    unknown.push(id);
+                unknownByFile.set(key, unknown);
+            }
+        }
+        for (const [key, missing] of missingByFile) {
+            objections.push({
+                objectionId: `existingCoverage:maintains:${key}`,
+                verifier: "existingCoverage",
+                message: EXISTING_COVERAGE_CONTRACT.objections.maintainedTestMissing.message,
+                evidence: `maintained test not in the checkout: ${missing}`,
+                suggestion: EXISTING_COVERAGE_CONTRACT.objections.maintainedTestMissing.suggestion,
+            });
+        }
+        for (const [key, unknown] of unknownByFile) {
+            objections.push({
+                objectionId: `existingCoverage:maintains:unknownChange:${key}`,
+                verifier: "existingCoverage",
+                message: EXISTING_COVERAGE_CONTRACT.objections.maintainedUnknownChange.message,
+                evidence: `${key === "unnamed" ? "an unnamed entry" : key} cites ${unknown.map((id) => `"${id}"`).join(", ")}; this plan declares ${[...declaredChanges].map((id) => `"${id}"`).join(", ") || "no changes"}`,
+                suggestion: EXISTING_COVERAGE_CONTRACT.objections.maintainedUnknownChange.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,246 @@
+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";
+import { escapeRegExp } from "../../utils/regex.js";
+import { renderCase } from "./coverage.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 ?? "?")}`;
+}
+/** Every number the pull request writes, as a number. One value has many
+ *  spellings — `1e21`, `1e+21`, `1E21`, the digits in full — and matching the
+ *  value's OWN spelling refused every other one, so a pull request stating the
+ *  limit as `1e21` did not state `1e21`.
+ *
+ *  A token glued to a word or to another number is not a number the text states:
+ *  that is what keeps `3600` from stating 60, `159.9989` from stating 159.998, and
+ *  the `60` of `1e60` from being a number at all. The sign belongs to the token, so
+ *  `-60` states -60 and not 60, while `+60` states 60. `Number` reads the rest:
+ *  `1599.80` is 1599.8 and `10.0` is 10. */
+function statedNumbers(prText) {
+    const stated = [];
+    for (const match of prText.matchAll(/[+-]?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g)) {
+        const token = match[0];
+        const start = match.index ?? 0;
+        const end = start + token.length;
+        const before = prText[start - 1] ?? "";
+        const after = prText[end] ?? "";
+        if (/[\dA-Za-z.]/.test(before))
+            continue;
+        if (/[\dA-Za-z]/.test(after))
+            continue;
+        // A dot that carries more digits makes this the first part of something
+        // longer — a version, a list — rather than a number of its own.
+        if (after === "." && /\d/.test(prText[end + 1] ?? ""))
+            continue;
+        const parsed = Number(token);
+        if (Number.isFinite(parsed))
+            stated.push(parsed);
+    }
+    return stated;
+}
+/** Whether the pull request writes this word or phrase, on its own rather than
+ *  inside a longer word. A plain substring let `active` read itself out of
+ *  `inactive`. The boundary is a letter or a digit, so a phrase that ends in
+ *  punctuation still matches the sentence that carries it. */
+function statesTheString(prText, value) {
+    const folded = value.replace(/\s+/g, " ").trim().toLowerCase();
+    if (!folded)
+        return false;
+    return new RegExp(`(?<![\\p{L}\\p{N}])${escapeRegExp(folded)}(?![\\p{L}\\p{N}])`, "u").test(prText);
+}
+/** Whether the pull request writes this value, anywhere in the title or the
+ *  description. A string or a literal — `true`, `false`, `null` — has to appear as
+ *  a word of its own; a number is compared against the numbers the text writes,
+ *  whatever spelling either side uses.
+ *
+ *  TRUE for a value that is not there to state: a case whose expectation is only a
+ *  `derived` rule declares no value, and the rule is checked through the change's
+ *  quote instead. */
+function statesTheValue(prText, value) {
+    if (typeof value === "string")
+        return statesTheString(prText, value);
+    // Three values with no spelling of their own. An empty spelling list used to read
+    // as "stated", so a case could claim `true` from a pull request that writes the
+    // opposite.
+    if (value === true || value === false || value === null)
+        return statesTheString(prText, String(value));
+    // Nothing to state: `undefined` is the derived-only case, and a non-finite
+    // number has no spelling a pull request could carry.
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return true;
+    return statedNumbers(prText).includes(value);
+}
+const text = (value) => (typeof value === "string" ? value.trim() : "");
+/** 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 raised = new Set();
+        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.
+                // A case states an expectation either as a value or as the rule behind one,
+                // and BOTH are read from somewhere: crediting `derived` without reading its
+                // `expectedFrom` let a rule "read" off the running app satisfy the check
+                // this verifier exists to be.
+                if (!entry || (entry.expectedValue === undefined && text(entry.derived).length === 0))
+                    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}`;
+                // The CASE, not its parameter. Two bound cases on one parameter each invent
+                // their own value, and keying on the parameter published one of them and
+                // carried its answer to the other. The rendering is the case's content, so
+                // it is the same string whatever order the cases arrive in — the identity
+                // `coverage:cases` already uses.
+                const caseId = renderCase({ param, value: entry.value, absent: entry.absent, expect: String(entry.expect ?? "") });
+                const raise = (kind, objection, evidence) => {
+                    if (raised.has(`${kind}:${changeId}:${caseId}`))
+                        return;
+                    raised.add(`${kind}:${changeId}:${caseId}`);
+                    objections.push({
+                        objectionId: `expectedValueSourced:${kind}:${changeId}:${caseId}`,
+                        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, 
+                    // A derived-only case pins no value, so quoting one read `expected
+                    // undefined` — a sentence naming nothing the agent can act on.
+                    `expected value read from the code under test: ${label} (${entry.expectedValue === undefined
+                        ? `derived as "${text(entry.derived)}"`
+                        : `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") {
+                    // Two readings, and the quote settles which one applies. A rule the pull
+                    // request states decides values it never writes — "over 60 is rejected"
+                    // states no 61, and demanding the value itself objected to five correct
+                    // cases in run 34414643135 — so a case whose source states a rule puts
+                    // that rule in `derived` and declares no number.
+                    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 (!statesTheValue(prText, entry.expectedValue)) {
+                        // `derived` is the case saying it pins NO number, so a case that still
+                        // carries one is not excused by it: the number is what has to be stated.
+                        raise("valueNotQuoted", CONTRACT.objections.valueNotQuoted, `${label} reads ${JSON.stringify(entry.expectedValue)} from the pull request, which writes no such value${text(entry.derived) ? " — and `derived` does not stand in for a value the case still declares" : ""}`);
+                    }
+                }
+                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;
+            // `derived` counts: it states the rule the value follows from, which is a
+            // stated value in every sense except that no number is written down.
+            const statesAValue = cited.some((change) => (Array.isArray(change?.cases) ? change.cases : []).some((entry) => entry && (entry.expectedValue !== undefined || text(entry.derived).length > 0)));
+            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\` or a \`derived\` rule`,
+                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[];

package/build/recommendation/verifiers/issueTraceability.js

@@ -0,0 +1,197 @@
+const NORMAL_LANE = { planOnly: false };
+/** An id as the plan spells it: trimmed, and exact otherwise. */
+function idKey(raw) {
+    return typeof raw === "string" ? raw.trim() : "";
+}
+/** The plan's defects that carry an id. Read defensively: the plan comes off disk,
+ *  and a plan stored before this field existed has none. */
+function declaredDefects(plan) {
+    const raw = plan?.defects;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((defect) => idKey(defect?.id).length > 0);
+}
+/** The defect ids one planned test cites. */
+function citedDefects(plannedTest) {
+    const declared = plannedTest?.declarations?.defects;
+    return Array.isArray(declared) ? declared.map(idKey).filter(Boolean) : [];
+}
+/** Whether the plan declares this test as one that expects to fail. Undeclared
+ *  reads as not failing, exactly as the plan-time `defects` verifier reads it: a
+ *  test that says nothing about its outcome proves nothing about a bug. */
+function expectsToFail(plannedTest) {
+    return plannedTest?.declarations?.expected?.outcome === "fail";
+}
+/** How many characters of an issue's description the objection quotes. */
+const QUOTE_LENGTH = 80;
+function quote(description) {
+    const text = String(description ?? "").trim().replace(/\s+/g, " ");
+    return text.length > QUOTE_LENGTH ? `${text.slice(0, QUOTE_LENGTH)}…` : text;
+}
+/** The plan-time `defects:untested:<id>` objection, as the plan-time verifier ids it. */
+const UNTESTED_PREFIX = "defects:untested:";
+/** Defect ids whose `defects:untested:<id>` objection the agent closed when it
+ *  registered the plan, by an answer or by a blocker. Both buckets: a blocker
+ *  close is stored apart from an answer and is a close all the same. Read
+ *  defensively: the plan comes off disk. */
+function answeredUntested(plan) {
+    const closed = [
+        ...(Array.isArray(plan?.answeredObjections) ? plan.answeredObjections : []),
+        ...(Array.isArray(plan?.unverifiedCloses) ? plan.unverifiedCloses : []),
+    ];
+    const ids = new Set();
+    for (const entry of closed) {
+        const objectionId = idKey(entry?.objection?.objectionId);
+        if (!objectionId.startsWith(UNTESTED_PREFIX))
+            continue;
+        if (idKey(entry?.answer).length === 0)
+            continue;
+        const id = idKey(objectionId.slice(UNTESTED_PREFIX.length));
+        if (id)
+            ids.add(id);
+    }
+    return ids;
+}
+/** 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;
+}
+/** 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 function checkIssueTraceability(plan, delivered, issues, lane = NORMAL_LANE) {
+    const shipped = new Set(delivered.map((test) => idKey(test?.plannedTestId)).filter(Boolean));
+    const plannedTests = Array.isArray(plan?.plannedTests) ? plan.plannedTests : [];
+    // The join that gives a delivered test its expected outcome. First entry wins:
+    // a repeated id is the plan's own duplicate, and the checks that own it are the
+    // plan-time ones.
+    const plannedById = new Map();
+    for (const plannedTest of plannedTests) {
+        const id = idKey(plannedTest?.plannedTestId);
+        if (id && !plannedById.has(id))
+            plannedById.set(id, plannedTest);
+    }
+    // In the plan-only lane a planned test stands where a delivered one would.
+    const inHand = (plannedTestId) => shipped.has(plannedTestId) || (lane.planOnly && plannedById.has(plannedTestId));
+    const proves = (plannedTestId) => inHand(plannedTestId) && expectsToFail(plannedById.get(plannedTestId));
+    /** Why this id proves nothing, in the words the objection uses. */
+    const gap = (plannedTestId) => {
+        if (!inHand(plannedTestId)) {
+            return plannedById.has(plannedTestId)
+                ? `plannedTestId "${plannedTestId}" names a planned test the run did not deliver`
+                : `plannedTestId "${plannedTestId}" names no delivered or planned test`;
+        }
+        const word = lane.planOnly ? "planned" : "delivered";
+        return plannedById.has(plannedTestId)
+            ? `plannedTestId "${plannedTestId}" names a ${word} test the plan declares as expecting to pass, and a test that passes today proves nothing about a bug`
+            : `plannedTestId "${plannedTestId}" names a ${word} test that no planned test declares, so nothing says it expects to fail`;
+    };
+    const known = new Set(declaredDefects(plan).map((defect) => idKey(defect.id)));
+    // Declared defect id -> the tests that prove it: in hand, and red by declaration.
+    const provenBy = new Map();
+    // Declared defect id -> the tests that cite it and prove nothing. Evidence only.
+    const citedWeakly = new Map();
+    for (const plannedTest of plannedTests) {
+        const id = idKey(plannedTest?.plannedTestId);
+        if (!id || !inHand(id))
+            continue;
+        const bucket = proves(id) ? provenBy : citedWeakly;
+        for (const defectId of citedDefects(plannedTest)) {
+            if (!known.has(defectId))
+                continue;
+            bucket.set(defectId, [...(bucket.get(defectId) ?? []), id]);
+        }
+    }
+    const answered = answeredUntested(plan);
+    const objections = [];
+    issues.forEach((issue, index) => {
+        if (String(issue?.category ?? "").trim().toLowerCase() !== "bug")
+            return;
+        const plannedTestId = idKey(issue?.plannedTestId);
+        if (plannedTestId && proves(plannedTestId))
+            return;
+        const defectId = idKey(issue?.defectId);
+        const declaredDefect = defectId.length > 0 && known.has(defectId);
+        if (declaredDefect && ((provenBy.get(defectId) ?? []).length > 0 || answered.has(defectId)))
+            return;
+        const named = [];
+        if (plannedTestId)
+            named.push(gap(plannedTestId));
+        if (defectId) {
+            const word = lane.planOnly ? "planned" : "delivered";
+            if (!declaredDefect) {
+                named.push(`defectId "${defectId}" names no defect this plan declares`);
+            }
+            else if ((citedWeakly.get(defectId) ?? []).length > 0) {
+                named.push(`defectId "${defectId}" is cited by no ${word} test that expects to fail: ${(citedWeakly.get(defectId) ?? []).join(", ")} cite it and the plan declares each as expecting to pass`);
+            }
+            else {
+                named.push(`defectId "${defectId}" is cited by no ${word} test that expects to fail and no plan-time answer closed ${UNTESTED_PREFIX}${defectId}`);
+            }
+        }
+        const where = String(issue?.sourceFile ?? "").trim() || "no sourceFile";
+        objections.push({
+            // Keyed on the entry's position: an issue has no id of its own. The
+            // message NAMES the issue because the report-stage carry matches on the id
+            // AND the message: with a fixed message, an answer given for the bug at
+            // index 0 would follow index 0 to whatever bug the next call put there.
+            objectionId: `issueTraceability:${index}`,
+            verifier: "issueTraceability",
+            message: `No test proves this bug: "${quote(issue?.description)}" (${where}).`,
+            evidence: `issuesFound[${index}]: ${named.length > 0 ? named.join("; ") : "no plannedTestId and no defectId"}.`,
+            suggestion: "Set `plannedTestId` to the delivered test that proves this bug — one the plan declares with `expected.outcome: fail`, so it stays red until the bug is fixed — or set `defectId` to a declared plan defect such a test cites. If no test proves it, answer in one line why.",
+        });
+    });
+    return objections;
+}
+/** 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 function checkDefectsReported(plan, issues) {
+    // Only a `category: bug` entry reports a defect. The schema takes a `defectId`
+    // on a lint, type or config entry too, and the report renders those in its own
+    // Configuration Errors section — a defect parked there is one the reader never
+    // meets under Issues Found, and it would close this check all the same.
+    const reported = new Set(issues
+        .filter((issue) => String(issue?.category ?? "").trim().toLowerCase() === "bug")
+        .map((issue) => idKey(issue?.defectId))
+        .filter(Boolean));
+    const objections = [];
+    const seen = new Set();
+    for (const defect of declaredDefects(plan)) {
+        const id = idKey(defect.id);
+        if (seen.has(id) || reported.has(id))
+            continue;
+        seen.add(id);
+        objections.push({
+            objectionId: `defects:unreported:${id}`,
+            verifier: "defects",
+            message: "The plan declares this defect and no issue in the report names it.",
+            evidence: `defect ${id} (${locate(defect)}): "${String(defect.description ?? "").trim()}"; no issuesFound entry carries defectId "${id}".`,
+            suggestion: "Add an `issuesFound` entry for it with `category: bug`, `defectId` set to this id, and the `plannedTestId` of the test that proves it. If the review was wrong and there is no defect, answer in one line what you found.",
+        });
+    }
+    return objections;
+}