@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/recommendation/subjectStep.d.ts

@@ -1,36 +1,34 @@
-import { ScenarioStep } from "../types/RepositoryAnalysis.js";
-import { PlannedTest } from "./types.js";
+import { PlannedStep, PlannedTest } from "./types.js";
 export declare const HTTP_METHODS: ReadonlySet<string>;
 /** Whether the planned test carries a `ui` or `e2e` label. The label alone exempts
  *  nothing (see `isUICandidate`); the schema reads it alone only for a planned test
  *  with no steps to look at. */
 export declare function hasUITestTypeLabel(rawTestType: unknown): boolean;
 /** Whether a step is an HTTP call: a real request method AND a path, since a verb
- *  with no path names no route. `interactionType` is deliberately not consulted —
- *  it labels what a step exercises, not how it reaches the app. Applied PER STEP. */
-export declare function isHTTPStep(step: ScenarioStep | undefined): boolean;
+ *  with no path names no route. Applied PER STEP. */
+export declare function isHTTPStep(step: PlannedStep | undefined): boolean;
 /** Whether a step calls the app rather than driving a screen: anything with a
  *  target whose method is not a page interaction, so an HTTP request and an
  *  `OPERATION` both count. The page interactions are the closed set. */
-export declare function isCallStep(step: ScenarioStep | undefined): boolean;
+export declare function isCallStep(step: PlannedStep | undefined): boolean;
 /** Whether a planned test is exempt from the route checks. A UI test's endpoints are
  *  attributions the agent wrote, not what it asserts. THE LABEL DECIDES: inferring
  *  from method names read a fixed list of HTTP verbs, so a GraphQL or Thrift call
  *  looked like a browser click. Every verifier reads this one function. */
 export declare function isUIPlannedTest(plannedTest: PlannedTest): boolean;
 /** Every step that calls the app rather than driving a screen. */
-export declare function callSteps(plannedTest: PlannedTest): ScenarioStep[];
+export declare function callSteps(plannedTest: PlannedTest): PlannedStep[];
 /** The step a planned test's test is about: the one `stepUnderTest` names, or the only
  *  call the planned test makes. A planned test that makes several calls and names none
  *  has NO subject — the agent states it and the server asks when it is missing,
  *  rather than ranking write methods and path prefixes to guess. A `stepUnderTest`
  *  matching no call is undefined too: the declaration is wrong, not a hint. */
-export declare function subjectStep(plannedTest: PlannedTest): ScenarioStep | undefined;
+export declare function subjectStep(plannedTest: PlannedTest): PlannedStep | undefined;
 /** One step's route as a single key, `METHOD path`. The method is trimmed and
  *  upper-cased, because a method is case-insensitive by protocol; the PATH is
  *  compared AS WRITTEN, so two spellings of one route stay two routes. A step
  *  with no path names no route and gets no key. */
-export declare function stepRouteKey(step: ScenarioStep | undefined): string | undefined;
+export declare function stepRouteKey(step: PlannedStep | undefined): string | undefined;
 /** One step's route as `METHOD path` with every record id folded to `{id}`.
  *
  *  The state test asks whether the PLAN covers a route, and the id a step happened
@@ -39,4 +37,4 @@ export declare function stepRouteKey(step: ScenarioStep | undefined): string | u
  *  close one by renumbering (run 33988304641, LB03). `stepRouteKey` keeps the path
  *  as written because `statedDifference` asks the opposite question — whether two
  *  planned tests test the same thing — and there two spellings must stay two. */
-export declare function stateRouteKey(step: ScenarioStep | undefined): string | undefined;
+export declare function stateRouteKey(step: PlannedStep | undefined): string | undefined;

package/build/recommendation/subjectStep.js

@@ -6,38 +6,35 @@ export const HTTP_METHODS = new Set(HTTP_STEP_METHODS);
 export function hasUITestTypeLabel(rawTestType) {
     // Trimmed as well as lower-cased: without the trim `"ui "` was checked and
     // `"UI"` was not, so one trailing space decided which of three verifiers ran.
-    const testType = String(rawTestType ?? "").trim().toLowerCase();
+    const testType = String(rawTestType ?? "")
+        .trim()
+        .toLowerCase();
     return testType === "ui" || testType === "e2e";
 }
 /** Whether a step is an HTTP call: a real request method AND a path, since a verb
- *  with no path names no route. `interactionType` is deliberately not consulted —
- *  it labels what a step exercises, not how it reaches the app. Applied PER STEP. */
+ *  with no path names no route. Applied PER STEP. */
 export function isHTTPStep(step) {
-    const method = String(step?.method ?? "").trim().toUpperCase();
+    const method = String(step?.method ?? "")
+        .trim()
+        .toUpperCase();
     return HTTP_METHODS.has(method) && String(step?.path ?? "").trim().length > 0;
 }
 /** Whether a step calls the app rather than driving a screen: anything with a
  *  target whose method is not a page interaction, so an HTTP request and an
  *  `OPERATION` both count. The page interactions are the closed set. */
 export function isCallStep(step) {
-    return !isUiStepVerb(step?.method) && String(step?.path ?? "").trim().length > 0;
+    return (!isUiStepVerb(step?.method) && String(step?.path ?? "").trim().length > 0);
 }
 /** Whether a planned test is exempt from the route checks. A UI test's endpoints are
  *  attributions the agent wrote, not what it asserts. THE LABEL DECIDES: inferring
  *  from method names read a fixed list of HTTP verbs, so a GraphQL or Thrift call
  *  looked like a browser click. Every verifier reads this one function. */
 export function isUIPlannedTest(plannedTest) {
-    // A null entry in `plannedTests` reaches here on the second, unvalidated
-    // caller the schema does not cover. Without this guard `planned test.scenario`
-    // throws, and `runVerifier` turns that throw into an acknowledgeable
-    // "crashed" objection — which hides the real objection instead of raising it.
-    if (!plannedTest)
-        return false;
-    return hasUITestTypeLabel(plannedTest.scenario?.testType);
+    return hasUITestTypeLabel(plannedTest.scenario.testType);
 }
 /** Every step that calls the app rather than driving a screen. */
 export function callSteps(plannedTest) {
-    return (plannedTest?.scenario?.steps ?? []).filter((step) => isCallStep(step));
+    return plannedTest.scenario.steps.filter((step) => isCallStep(step));
 }
 /** The step a planned test's test is about: the one `stepUnderTest` names, or the only
  *  call the planned test makes. A planned test that makes several calls and names none
@@ -46,7 +43,7 @@ export function callSteps(plannedTest) {
  *  matching no call is undefined too: the declaration is wrong, not a hint. */
 export function subjectStep(plannedTest) {
     const calls = callSteps(plannedTest);
-    const declaredOrder = plannedTest?.declarations?.stepUnderTest;
+    const declaredOrder = plannedTest.declarations.stepUnderTest;
     if (typeof declaredOrder === "number")
         return calls.find((step) => (step.order ?? 0) === declaredOrder);
     return calls.length === 1 ? calls[0] : undefined;
@@ -59,7 +56,9 @@ export function stepRouteKey(step) {
     const path = String(step?.path ?? "").trim();
     if (!path)
         return undefined;
-    const method = String(step?.method ?? "ANY").trim().toUpperCase() || "ANY";
+    const method = String(step?.method ?? "ANY")
+        .trim()
+        .toUpperCase() || "ANY";
     return `${method} ${path}`;
 }
 /** A segment that identifies one record rather than naming part of the route: all
@@ -77,7 +76,9 @@ export function stateRouteKey(step) {
     const path = String(step?.path ?? "").trim();
     if (!path)
         return undefined;
-    const method = String(step?.method ?? "ANY").trim().toUpperCase() || "ANY";
+    const method = String(step?.method ?? "ANY")
+        .trim()
+        .toUpperCase() || "ANY";
     const folded = path
         .split("/")
         .map((segment) => (RECORD_ID_SEGMENT.test(segment) ? "{id}" : segment))

package/build/recommendation/types.d.ts

@@ -1,5 +1,42 @@
 import { ChangedFileName } from "../utils/branchDiff.js";
-import { PlanScenario } from "../types/RepositoryAnalysis.js";
+import { ScenarioCategory } from "../types/TestRecommendation.js";
+import { StepMethod } from "../types/StepMethod.js";
+import { TestbotSupportedTestType } from "./../types/TestTypes.js";
+/** The scenario half of a planned test: exactly what `buildRegistration` builds
+ *  from the schema, and nothing else. It used to be typed as the analysis's own
+ *  `PlanScenario`, which declares nine required fields where four were never set,
+ *  so every reader of `priority`, `chainingKeys`, `requiresAuth` or
+ *  `estimatedComplexity` would have read undefined against a type that promised a
+ *  value. `steps` is always an array: a ui planned test that names a screen instead
+ *  of steps carries an empty one, so readers test its length. */
+/** One step a planned test makes, as the plan schema takes it — NOT the
+ *  analysis's `ScenarioStep`, which requires a `description` and an
+ *  `expectedStatusCode` that the plan schema leaves optional, and an
+ *  `interactionType` the plan schema does not take at all. */
+export interface PlannedStep {
+    order: number;
+    /** An HTTP verb, one of `UI_STEP_VERBS` (`click`, `type`), or `OPERATION` for a
+     *  call with no verb. The same closed set `stepMethodSchema` emits. */
+    method: StepMethod;
+    /** The request path for an HTTP step, the interaction's target for a page step
+     *  (`checkout button`), the operation's name for an `OPERATION` step. So a step
+     *  is a route only when `isCallStep` says it is: that helper drops the page
+     *  verbs, and every route check reads it rather than this field. */
+    path: string;
+    description?: string;
+    requestBody?: unknown;
+    queryParams?: unknown;
+    omits?: string[];
+    expectedStatusCode?: number;
+}
+export interface PlannedScenario {
+    scenarioName: string;
+    description: string;
+    category: ScenarioCategory;
+    steps: PlannedStep[];
+    /** The schema accepts these four and no other. */
+    testType: TestbotSupportedTestType;
+}
 import type { BlueprintCaptureDigest } from "../types/BlueprintDigest.js";
 import type { RemovedUiElement } from "../utils/removedUiElements.js";
 /** One element a UI planned test targets. EVERY field is optional and three are
@@ -32,7 +69,7 @@ export interface PlanChange {
     /** The inputs that prove this change: what a route must accept and what it must
      *  reject. Exactly one of `value` and `absent` per entry. The coverage check reads
      *  it; nothing else on the server does. */
-    cases?: Array<{
+    testCases?: Array<{
         param: string;
         value?: string | number | boolean | null;
         absent?: true;
@@ -116,11 +153,12 @@ export interface PlannedTestDetails {
 }
 export interface PlannedTest {
     plannedTestId: string;
-    scenario: PlanScenario;
+    scenario: PlannedScenario;
     declarations: PlannedTestDetails;
     /** Deliberately NOT part of the planned test id: an id stays the same across
-     *  registrations, and a single-repo plan names no repository. */
-    repository?: string;
+     *  registrations. Every planned test names one, a single-repository run
+     *  included — the name is what joins the test to the diff it is checked against. */
+    repository: string;
 }
 export interface ObjectionAnswer {
     objectionId: string;
@@ -136,6 +174,9 @@ export interface ObjectionAnswer {
  *  tested by a file I am editing" — without it, `coverage:change:` is unanswerable
  *  for a correct maintenance decision, and it closes only with a `blocker`. */
 export interface PlanMaintenance {
+    /** The `owner/repo` holding the test. Two repositories of a run can hold the same
+     *  relative path, so the entry says which one it edited. */
+    repository: string;
     /** Repository-relative path of the existing test. Only its presence in the
      *  checkout is checked, the same rule `declarations.existingTests` follows. */
     file: string;
@@ -143,6 +184,9 @@ export interface PlanMaintenance {
     differsBy: string;
     /** The ids of the declared changes this maintenance covers. */
     changes: string[];
+    /** The declared defects this maintained test proves. Always stated, like
+     *  `changes`: an entry that proves none sends an empty list. */
+    defects: string[];
 }
 export interface PlanInput {
     /** The changes the diff makes. Each planned test cites the ones it tests. */
@@ -176,7 +220,8 @@ export interface Objection {
 /** Facts the verifiers check against. Gathered once per run by the caller. */
 export interface VerifyContext {
     /** Every repository this run analyzed, and the files its diff changed there.
-     *  NAMES ONLY, never contents. A single-repository run has one entry. */
+     *  NAMES ONLY, never contents. A single-repository run has one entry. Every
+     *  planned test names one of these keys; there is no wildcard. */
     changedFiles: Record<string, ChangedFileName[]>;
     /** Repositories with no branch diff. Softens objections RUN-WIDE, because a
      *  planned test that names no repository is checked against every one of them. */
@@ -199,16 +244,21 @@ export interface VerifyContext {
         title: string;
         description: string;
     };
-    /** Whether a cited path names a file in any of the run's repositories. Injected
-     *  to keep the verifiers filesystem-free. */
-    citedFileExists(relativePath: string): boolean;
+    /** Whether a cited path names a file in the run's repositories. Injected to keep
+     *  the verifiers filesystem-free. Named a repository it asks that one, and a name
+     *  this run does not know answers false. Omitted, it asks every one. */
+    citedFileExists(relativePath: string, repository?: string): boolean;
     /** The route patterns that mount a changed frontend file, as the framework
      *  spells them (`/secrets/$envSlug`, `/orders/:id`). Injected for the same
      *  reason as `citedFileExists`: the scan reads the repository, the verifier
-     *  does not. UNDEFINED means the resolver cannot speak for this file — an
-     *  unsupported framework, a route table it could not parse — and the check
-     *  stays silent. An EMPTY array is a statement: nothing mounts it. */
-    routesRenderingFile?(relativePath: string): string[] | undefined;
+     *  does not. ASKED OF ONE REPOSITORY, the one the planned test names: two
+     *  repositories can hold the same relative file, and answering from whichever
+     *  was scanned first objected to a test against another repository's routes.
+     *  UNDEFINED means the resolver cannot speak for this file — an unsupported
+     *  framework, a route table it could not parse, a repository this run does not
+     *  know — and the check stays silent. An EMPTY array is a statement: nothing
+     *  mounts it. */
+    routesRenderingFile(relativePath: string, repository: string): string[] | undefined;
 }
 /** Every changed file of the run, whatever repository it sits in. */
 export declare function allChangedFiles(ctx: VerifyContext): ChangedFileName[];
@@ -216,9 +266,13 @@ export interface Verifier {
     readonly name: string;
     run(registration: PlanInput, ctx: VerifyContext): Objection[];
 }
-/** The changed files a planned test is checked against: its own repository's when it
- *  names one this run analyzed, every repository's when it names none. UNDEFINED
- *  when it names a repository this run does not know, which the caller objects to. */
+/** The changed files a planned test is checked against: its own repository's.
+ *  UNDEFINED when it names a repository this run does not know, which the caller
+ *  objects to. Every planned test names one, so there is no names-none case: every
+ *  run keys its repositories by a real `owner/repo`.
+ *
+ *  The schema trims the name and holds it to the `owner/repo` shape before any
+ *  verifier runs, so the lookup takes the field as it stands. */
 export declare function changedFilesFor(ctx: VerifyContext, plannedTest: {
-    repository?: string;
+    repository: string;
 }): ChangedFileName[] | undefined;

package/build/recommendation/types.js

@@ -1,20 +1,14 @@
 /** Every changed file of the run, whatever repository it sits in. */
 export function allChangedFiles(ctx) {
-    return Object.values(ctx?.changedFiles ?? {}).flatMap((files) => files ?? []);
+    return Object.values(ctx.changedFiles).flatMap((files) => files ?? []);
 }
-/** The changed files a planned test is checked against: its own repository's when it
- *  names one this run analyzed, every repository's when it names none. UNDEFINED
- *  when it names a repository this run does not know, which the caller objects to. */
+/** The changed files a planned test is checked against: its own repository's.
+ *  UNDEFINED when it names a repository this run does not know, which the caller
+ *  objects to. Every planned test names one, so there is no names-none case: every
+ *  run keys its repositories by a real `owner/repo`.
+ *
+ *  The schema trims the name and holds it to the `owner/repo` shape before any
+ *  verifier runs, so the lookup takes the field as it stands. */
 export function changedFilesFor(ctx, plannedTest) {
-    const known = ctx?.changedFiles ?? {};
-    const repo = String(plannedTest?.repository ?? "").trim();
-    if (!repo)
-        return allChangedFiles(ctx);
-    const own = known[repo];
-    if (own)
-        return own;
-    // Only a MULTI-repository run reads an unmatched name as unknown: a single-repo
-    // run keys the primary as "the primary repository" when `metadata.repository` is
-    // absent, which no name the agent writes will ever match.
-    return Object.keys(known).length > 1 ? undefined : allChangedFiles(ctx);
+    return ctx.changedFiles[plannedTest.repository];
 }

package/build/recommendation/verifierContracts.d.ts

@@ -40,7 +40,7 @@ export declare const CHANGED_FILE_CONTRACT: {
         };
         readonly unknownRepository: {
             readonly message: "This planned test names a repository this run did not analyze.";
-            readonly suggestion: "Name one of the repositories listed in the evidence, or leave `repository` out on a single-repository run. A name nothing analyzed leaves the planned test with no diff to be checked against.";
+            readonly suggestion: "Name one of the repositories listed in the evidence, spelled as the evidence spells it. A name nothing analyzed leaves the planned test with no diff to be checked against.";
         };
         readonly screenEvidenceUnrelated: {
             readonly message: "The file this UI test cites for its screen is not one this pull request changed.";
@@ -176,7 +176,7 @@ export declare const COVERAGE_CONTRACT: {
             readonly message: "No test in this plan names the state the record is in when {route} mutates it.";
             readonly suggestion: "Plan one test that puts a record in a stated state — through the API, the UI, or data the app already holds; a record with no rows yet counts — then runs the mutation on it, and name that state as `startState`. If the route can meet a record that is not freshly created, use that state. Only a planned test closes this: there is no answer for it.";
         };
-        readonly cases: {
+        readonly testCases: {
             readonly message: "No test for this change sends the declared case {missing}.";
             readonly suggestion: "Add the missing values to a test that cites this change, or answer in one line why they need no test.";
         };
@@ -286,7 +286,7 @@ export declare const DEFECTS_CONTRACT: {
         };
         readonly untested: {
             readonly message: "This declared defect has no test in the plan.";
-            readonly 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.";
+            readonly 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 an existing test already proves 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 defect's id — maintenance is proof, and a duplicate spec beside the one you edited is the mistake. If something stopped this run from writing the test, answer it and set `blocker` to what stopped it.";
         };
         readonly expectedPass: {
             readonly message: "Every test that cites this defect expects to pass, and a test that passes today proves nothing about a defect.";
@@ -296,6 +296,10 @@ export declare const DEFECTS_CONTRACT: {
             readonly message: "A planned test cites a defect id that this plan does not declare.";
             readonly 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.";
         };
+        readonly maintainedUnknownDefect: {
+            readonly message: "A `maintains` entry cites a defect id that this plan does not declare.";
+            readonly 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.";
+        };
         readonly conflictWithoutDefect: {
             readonly message: "This test reports a requirement conflict and cites no defect.";
             readonly 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.";

package/build/recommendation/verifierContracts.js

@@ -22,7 +22,7 @@ export const CHANGED_FILE_CONTRACT = {
         },
         unknownRepository: {
             message: "This planned test names a repository this run did not analyze.",
-            suggestion: "Name one of the repositories listed in the evidence, or leave `repository` out on a single-repository run. A name nothing analyzed leaves the planned test with no diff to be checked against.",
+            suggestion: "Name one of the repositories listed in the evidence, spelled as the evidence spells it. A name nothing analyzed leaves the planned test with no diff to be checked against.",
         },
         screenEvidenceUnrelated: {
             message: "The file this UI test cites for its screen is not one this pull request changed.",
@@ -181,7 +181,7 @@ export const COVERAGE_CONTRACT = {
         // anyway. What a case IS stays the agent's judgment — the field takes any
         // parameter and any value, so nothing here has to know a kind of input in
         // advance.
-        cases: {
+        testCases: {
             message: "No test for this change sends the declared case {missing}.",
             suggestion: "Add the missing values to a test that cites this change, or answer in one line why they need no test.",
         },
@@ -347,7 +347,7 @@ export const DEFECTS_CONTRACT = {
         },
         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.",
+            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 an existing test already proves 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 defect's id — maintenance is proof, and a duplicate spec beside the one you edited is the mistake. 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.",
@@ -357,6 +357,10 @@ export const DEFECTS_CONTRACT = {
             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.",
         },
+        maintainedUnknownDefect: {
+            message: "A `maintains` entry 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.",
@@ -369,5 +373,5 @@ export const DEFECTS_CONTRACT = {
  *  than blanked, so a missed key shows up as `{knob}` instead of reading as a gap
  *  in an otherwise ordinary sentence. */
 export function fillPlaceholders(text, values) {
-    return text.replace(/\{(\w+)\}/g, (whole, key) => (key in values ? String(values[key]) : whole));
+    return text.replace(/\{(\w+)\}/g, (whole, key) => key in values ? String(values[key]) : whole);
 }

package/build/recommendation/verifiers/changedFile.js

@@ -1,6 +1,6 @@
-import { allChangedFiles, changedFilesFor } from "../types.js";
-import { CHANGED_FILE_CONTRACT } from "../verifierContracts.js";
-import { changedPathSet, normalizeCitedPath, whyNotAChangedFile } from "./citedPath.js";
+import { allChangedFiles, changedFilesFor, } from "../types.js";
+import { CHANGED_FILE_CONTRACT, } from "../verifierContracts.js";
+import { changedPathSet, normalizeCitedPath, whyNotAChangedFile, } from "./citedPath.js";
 /** Verifier 1. The files a planned test cites for the change it targets are files
  *  this pull request really changed. NAMES ONLY — no diff content is read, so an
  *  irrelevant file inside the diff cannot be caught. SILENT on a run with no
@@ -22,9 +22,9 @@ function describeType(value) {
 /** One objection, so every branch below reads the same way. */
 function raise(plannedTest, key, objection, evidence) {
     return {
-        objectionId: `changedFile:${key}:${plannedTest?.plannedTestId}`,
+        objectionId: `changedFile:${key}:${plannedTest.plannedTestId}`,
         verifier: "changedFile",
-        plannedTestId: plannedTest?.plannedTestId,
+        plannedTestId: plannedTest.plannedTestId,
         message: objection.message,
         evidence,
         suggestion: objection.suggestion,
@@ -44,7 +44,7 @@ export const changedFile = {
             // repository.
             const own = changedFilesFor(ctx, plannedTest);
             if (own === undefined) {
-                objections.push(raise(plannedTest, "unknownRepository", CHANGED_FILE_CONTRACT.objections.unknownRepository, `this run analyzed ${Object.keys(ctx.changedFiles ?? {}).join(", ") || "no repository"}, and this planned test names "${String(plannedTest?.repository ?? "").trim()}"`));
+                objections.push(raise(plannedTest, "unknownRepository", CHANGED_FILE_CONTRACT.objections.unknownRepository, `this run analyzed ${Object.keys(ctx.changedFiles).join(", ") || "no repository"}, and this planned test names "${plannedTest.repository}"`));
                 continue;
             }
             const surfaces = changedPathSet(own, true);
@@ -55,17 +55,15 @@ export const changedFile = {
             // `screenEvidence.file` has to be a file the diff changed. Independent of
             // the changed file's own result — a planned test can get both wrong, and each
             // names its own fix.
-            const citedScreen = String(plannedTest?.declarations?.screenEvidence?.file ?? "").trim();
+            const citedScreen = String(plannedTest.declarations.screenEvidence?.file ?? "").trim();
             if (citedScreen && !pages.has(normalizeCitedPath(citedScreen))) {
-                const page = String(plannedTest?.declarations?.elements?.pageUrl ?? "").trim();
+                const page = String(plannedTest.declarations.elements?.pageUrl ?? "").trim();
                 objections.push(raise(plannedTest, "screenEvidenceUnrelated", CHANGED_FILE_CONTRACT.objections.screenEvidenceUnrelated, `${pages.size} changed file(s) still in the tree. ${whyNotAChangedFile(citedScreen)}, for ${page ? `the test that opens ${page}` : "a test that names no page"}.`));
             }
-            // The declared type holds only on the schema-validated path. A crash here
-            // ends the run; an objection lets the agent fix the field.
-            const raw = plannedTest?.declarations?.changedFile;
-            const cited = typeof raw === "string" ? raw.trim() : "";
+            const declared = plannedTest.declarations.changedFile;
+            const cited = (declared ?? "").trim();
             if (!cited) {
-                objections.push(raise(plannedTest, "notStated", CHANGED_FILE_CONTRACT.objections.notStated, `changedFile is ${describeType(raw)}; ${surfaces.size} file(s) changed in this run and the plan does not say which one this test targets.`));
+                objections.push(raise(plannedTest, "notStated", CHANGED_FILE_CONTRACT.objections.notStated, `changedFile is ${describeType(declared)}; ${surfaces.size} file(s) changed in this run and the plan does not say which one this test targets.`));
                 continue;
             }
             if (!surfaces.has(normalizeCitedPath(cited))) {

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

@@ -1,4 +1,12 @@
 import { ChangedFileName } from "../../utils/branchDiff.js";
+import { PlanMaintenance, VerifyContext } from "../types.js";
+/** Whether a `maintains` entry names a file that stays inside the repository and is
+ *  present in the repository the entry names.
+ *
+ *  An entry credits its ids only when it is. `coverage:change:` and
+ *  `defects:untested:` close only with a blocker, so crediting a file nobody can
+ *  open would route around both. */
+export declare function maintainedFileIsInItsRepository(entry: PlanMaintenance, ctx: VerifyContext): boolean;
 /** A cited path reduced to the spelling `git diff --name-status` produces: `./`,
  *  backslashes, doubled and trailing slashes fold, and so do git's quoting of a
  *  non-ASCII path and both unicode compositions. Case does NOT fold, and a path

package/build/recommendation/verifiers/citedPath.js

@@ -1,5 +1,15 @@
 import { unquoteIfQuoted } from "../../utils/branchDiff.js";
 import { escapesRepo } from "./endpointGrounded.js";
+/** Whether a `maintains` entry names a file that stays inside the repository and is
+ *  present in the repository the entry names.
+ *
+ *  An entry credits its ids only when it is. `coverage:change:` and
+ *  `defects:untested:` close only with a blocker, so crediting a file nobody can
+ *  open would route around both. */
+export function maintainedFileIsInItsRepository(entry, ctx) {
+    const path = entry.file.trim();
+    return (!!path && !escapesRepo(path) && ctx.citedFileExists(path, entry.repository));
+}
 /** A cited path reduced to the spelling `git diff --name-status` produces: `./`,
  *  backslashes, doubled and trailing slashes fold, and so do git's quoting of a
  *  non-ASCII path and both unicode compositions. Case does NOT fold, and a path
@@ -7,10 +17,14 @@ import { escapesRepo } from "./endpointGrounded.js";
 export function normalizeCitedPath(raw) {
     if (typeof raw !== "string")
         return "";
-    const slashed = unquoteIfQuoted(raw.trim()).normalize("NFC").replace(/\\/g, "/");
+    const slashed = unquoteIfQuoted(raw.trim())
+        .normalize("NFC")
+        .replace(/\\/g, "/");
     if (!slashed || escapesRepo(slashed))
         return "";
-    const segments = slashed.split("/").filter((segment) => segment !== "" && segment !== ".");
+    const segments = slashed
+        .split("/")
+        .filter((segment) => segment !== "" && segment !== ".");
     return segments.join("/");
 }
 /** The changed paths a citation can name, in the same normalised spelling.

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

@@ -2,8 +2,8 @@ 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: {
+ *  two test cases on one parameter are two objections there too. */
+export declare function renderTestCase(declared: {
     param: string;
     value?: unknown;
     absent?: true;