@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/recommendation/types.js

@@ -0,0 +1,20 @@
+/** Every changed file of the run, whatever repository it sits in. */
+export function allChangedFiles(ctx) {
+    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. */
+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);
+}

package/build/recommendation/verifierContracts.d.ts

@@ -0,0 +1,382 @@
+/** What each plan-time check SAYS to the agent: the objection it emits, and the
+ *  one-line question that closes it. Each suggestion also carries the judgment
+ *  the check itself cannot make — the agent reads it at the moment it matters,
+ *  when the objection arrives, and the skill does not repeat it. What to put in
+ *  a field, and what the check reads, is stated once in that field's own
+ *  `describe` in the plan tool's schema. A check compares a change the plan states
+ *  against something the server already holds, needs no new parser or threshold,
+ *  and can be answered by the agent. */
+/** One objection's rendered text, carried verbatim from the verifier that emits it. */
+export interface ContractObjection {
+    /** The objection. */
+    readonly message: string;
+    /** What the agent does about it. A `{placeholder}` is filled by the verifier:
+     *  a contract holds the shape of an interpolation, never the interpolation. */
+    readonly suggestion: string;
+}
+export interface VerifierContract {
+    /** The verifier's own `Verifier.name`. */
+    readonly id: string;
+    /** What the registered plan has to carry for the check to have anything to read. */
+    readonly declarationFields: readonly string[];
+    /** One entry per message the verifier can emit, keyed by the case. A key naming a
+     *  segment of the `objectionId` uses that segment's spelling. The keys are widened
+     *  here so every contract satisfies the interface, while each contract is `as
+     *  const`, so a reader naming a key its contract lacks fails `tsc`. */
+    readonly objections: Readonly<Record<string, ContractObjection>>;
+    /** The question the agent has to answer, in one sentence, for the schema and the
+     *  prompt. It never names an answer that closes the check: an agent uses the
+     *  phrase it was handed, and one check once handed out "no blueprint data". */
+    readonly suggestion: string;
+}
+export declare const CHANGED_FILE_CONTRACT: {
+    readonly id: "changedFile";
+    readonly declarationFields: readonly ["declarations.changedFile", "declarations.screenEvidence.file"];
+    readonly objections: {
+        readonly notStated: {
+            readonly message: "This test does not state which changed file it targets.";
+            readonly suggestion: "Name the repository-relative file this test is about in `changedFile`, spelled as the diff spells it.";
+        };
+        readonly unrelated: {
+            readonly message: "The file this test names as its changed file is not one this pull request changed.";
+            readonly suggestion: "Name a file from this PR's own diff in `changedFile`, repository-relative and spelled as the diff spells it — or say why this test belongs in the plan without one.";
+        };
+        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 screenEvidenceUnrelated: {
+            readonly message: "The file this UI test cites for its screen is not one this pull request changed.";
+            readonly suggestion: "Which changed file renders the screen this test opens — or which changed screen should it open instead? Name that file in `screenEvidence.file`, repository-relative, spelled as the diff spells it.";
+        };
+    };
+    readonly suggestion: "Which file that this pull request changed does this test target?";
+};
+export declare const SCREEN_ROUTE_CONTRACT: {
+    readonly id: "screenRoute";
+    readonly declarationFields: readonly ["declarations.elements.pageUrl", "declarations.screenEvidence.file", "declarations.changedFile"];
+    readonly objections: {
+        readonly mismatch: {
+            readonly message: "The page this UI test opens is not a page that renders the changed file it is about.";
+            readonly suggestion: "Open one of the routes in the evidence, or name the changed file that does render this page in `screenEvidence.file`. `skyramp_resolve_screen` gives the url to open, with the route parameters it can fill. A trace recorded on a screen the diff did not change proves nothing about the change.";
+        };
+        readonly unmounted: {
+            readonly message: "No route this run found renders the file this UI test is about.";
+            readonly suggestion: "If a route in this PR mounts it, name that route in `elements.pageUrl`. If nothing mounts it, the component is unintegrated: say so in one line and keep the planned test out of the browser.";
+        };
+    };
+    readonly suggestion: "Does the page this test opens render the changed file the test is about?";
+};
+export declare const ENDPOINT_GROUNDED_CONTRACT: {
+    readonly id: "endpointGrounded";
+    readonly declarationFields: readonly ["steps[]", "testType", "declarations.routes"];
+    readonly objections: {
+        readonly uncited: {
+            readonly message: "A call this test makes cites no file that declares it.";
+            readonly suggestion: "Add a `routes` entry naming the repository file that declares it — the route or operation need not appear verbatim in that file. A route the endpoint catalog missed is evidence of nothing: cite the file and keep the planned test.";
+        };
+        readonly disqualifiedCitation: {
+            readonly message: "The file this test cites for a call cannot be the file that declares it.";
+            readonly suggestion: "Cite the source file that declares it — not a test, not built output, not documentation. Any language or format is accepted, and the route or operation need not appear verbatim in the file.";
+        };
+        readonly uncitedAndDisqualified: {
+            readonly message: "This test has a call with no citation, and a call whose cited file cannot be the file that declares it.";
+            readonly suggestion: "Add `routes` for the call that has none, and point the other citation at the source file that declares its route or operation. Neither need appear verbatim in the file.";
+        };
+    };
+    readonly suggestion: "Which repository file declares this route or operation, and does an entry name that step's `order`?";
+};
+export declare const STATED_DIFFERENCE_CONTRACT: {
+    readonly id: "statedDifference";
+    readonly declarationFields: readonly ["steps[]", "testType", "scenarioName", "declarations.differsFrom"];
+    readonly objections: {
+        readonly unexplainedPair: {
+            readonly message: "Another planned test in this plan tests the same endpoint and neither says how they differ.";
+            readonly suggestion: "Two tests on one endpoint is a legitimate plan. This asks HOW they differ, not whether one should go. Add a `differsFrom` entry naming the other planned test and what this one asserts that it does not — or, if one really is redundant, drop it.";
+        };
+        readonly unknownPartner: {
+            readonly message: "A `differsFrom` entry names a partner that is not a planned test in this plan.";
+            readonly suggestion: "Spell the partner's `scenarioName` exactly as it appears in your own planned test list — the match is exact apart from surrounding space, so a difference in case names nothing.";
+        };
+        readonly subjectNotStated: {
+            readonly message: "This test makes more than one call and does not say which one it is about.";
+            readonly suggestion: "Set `declarations.stepUnderTest` to the `order` of the step under test. The other calls are setup, and nothing on the server ranks them for you.";
+        };
+    };
+    readonly suggestion: "Which call is this test about, and what does it assert that the other planned test on the same endpoint does not?";
+};
+export declare const EXISTING_COVERAGE_CONTRACT: {
+    readonly id: "existingCoverage";
+    readonly declarationFields: readonly ["declarations.existingTests"];
+    readonly objections: {
+        readonly citedTestMissing: {
+            readonly message: "This planned test names an existing test file that is not in the checkout.";
+            readonly suggestion: "Name the file repository-relative, spelled as the analysis lists it. Drop the entry if it names a test you did not read — naming none is an answer too.";
+        };
+    };
+    readonly suggestion: "Which existing tests did you read on this change, and how does this planned test differ from them?";
+};
+export declare const EXPECTED_OUTCOME_CONTRACT: {
+    readonly id: "expectedOutcome";
+    readonly declarationFields: readonly ["category", "declarations.expected.outcome", "declarations.expected.why"];
+    readonly objections: {
+        readonly passInShouldFailCategory: {
+            readonly message: "This planned test is categorised \"{category}\" but expects to pass on the app as it stands.";
+            readonly suggestion: "If it catches a defect, it should be red until the defect is fixed — say so. If it pins behaviour that is already correct, change the category.";
+        };
+        readonly executed: {
+            readonly message: "This test failed, but it did not reach the behavior it was written for — it fell over earlier. A failure like this is not a caught bug.";
+            readonly suggestion: "If the blocker is the test's own setup — sign-in, token, a wrong path — fix it and run the test again. If the blocker is the defect this run reports (a route that is not mounted, a server error before the behaviour), answer this objection naming that issue: the failure then stands as evidence of that issue, not as a caught bug.";
+        };
+    };
+    readonly suggestion: "Should this test fail until the defect is fixed, or is the category wrong for a test that pins behaviour the app already has?";
+};
+export declare const UI_ELEMENT_GROUNDED_CONTRACT: {
+    readonly id: "uiElementGrounded";
+    readonly declarationFields: readonly ["testType", "steps[]", "declarations.elements.items", "declarations.elements.pageUrl", "declarations.asserts", "scenarioName", "description", "declarations.expected.why"];
+    readonly objections: {
+        readonly nogrounding: {
+            readonly message: "This UI test names no `elements.items`, so nothing says the elements it targets are on the page.";
+            readonly suggestion: "Copy the elements this test targets out of the capture of the page it runs on into `elements.items`, and set `elements.pageUrl` to that page. If no captured page holds this test's elements — the changed component mounts nowhere the run reached, or the screen is behind a gate this run could not pass — answer this objection saying which, and leave `elements.items` null.";
+        };
+        readonly duplicate: {
+            readonly message: "`elements.items` names the same element more than once.";
+            readonly suggestion: "List each element once. Two entries that agree on role, name and identifiers describe one element, and the repeat states nothing the first entry did not.";
+        };
+        readonly pagecontext: {
+            readonly message: "This UI test names `elements.items` but no page they came from.";
+            readonly suggestion: "Set `elements.pageUrl` to the `url` of the capture the elements were lifted from. Without it there is no page to look them up on.";
+        };
+        readonly ungrounded: {
+            readonly message: "An element this UI test targets is in no blueprint captured for that page.";
+            readonly suggestion: "Cite what a capture shows you, never what the screen ought to have. A capture shows the page as it stood when it was taken, so an element behind a modal, a dropdown or an accordion is legitimately absent — answer this objection naming the action that reveals it. Otherwise copy the element from the capture as it is spelled there, or point `elements.pageUrl` at the page you actually captured.";
+        };
+    };
+    readonly suggestion: "Which capture of the page does each declared element come from, and for one that is in no capture, which action on that page reveals it?";
+};
+export declare const COVERAGE_CONTRACT: {
+    readonly id: "coverage";
+    readonly declarationFields: readonly ["changes", "declarations.changes", "declarations.changedFile", "declarations.routes", "declarations.screenEvidence.file", "declarations.startState", "changes[].cases", "changes[].surfaces"];
+    readonly objections: {
+        readonly change: {
+            readonly message: "This declared change has no test in the plan.";
+            readonly suggestion: "Plan a test that exercises it. If this run cannot write one, answer it and set `blocker` to what stopped the run — a service that is not running, a paired branch that no longer exists, the one credential the run holds. An answer with no blocker leaves this open: a change nothing prevented a test from reaching takes the test. Coverage per file is the basic minimum; coverage per change is what the plan is judged by, so a file covered by a shape test still leaves the change it makes untested.";
+        };
+        readonly noChanges: {
+            readonly message: "The plan declares no changes, so nothing says what the pull request must make different.";
+            readonly suggestion: "List the behaviours the pull request description promises, one sentence each, and cite them from the planned tests that test them — or answer in one line that it promises none, which a docs-only or cosmetic change legitimately does.";
+        };
+        readonly unknownChange: {
+            readonly message: "A planned test cites a change id that this plan does not declare.";
+            readonly suggestion: "Spell the change's `id` exactly as your own `changes` list gives it — the match is exact apart from surrounding space. Declare the change if it is missing.";
+        };
+        readonly file: {
+            readonly message: "This changed file has no test in the plan.";
+            readonly suggestion: "Add a planned test that cites it — as `changedFile`, as a `routes` file, or as `screenEvidence.file` — or answer in ONE line why it needs none: config only, covered by the test on the route it serves, or style-only and covered by the UI test on the page it belongs to. This check is a floor, never a cap: it never asks you to plan fewer tests.";
+        };
+        readonly stateTest: {
+            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 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.";
+        };
+        readonly reject: {
+            readonly message: "`{param}` accepts `{value}`, a record the plan creates, and no case rejects a record that is not there or belongs to another parent.";
+            readonly suggestion: "Add a reject case on `{param}` with a value that is not that record and a step that sends it, or answer why the route cannot refuse it.";
+        };
+        readonly surface: {
+            readonly message: "No {kind} test cites this change, which is on the {surface}.";
+            readonly suggestion: "Add a test on that surface that cites this change, or answer in one line why that surface needs no test.";
+        };
+    };
+    readonly suggestion: "Which planned test tests each behaviour this change promises and each file it touches, and for one nothing covers, why does it need none?";
+};
+export declare const REMOVED_ELEMENT_GUARDED_CONTRACT: {
+    readonly id: "removedElementGuarded";
+    readonly declarationFields: readonly ["declarations.elements.items", "declarations.asserts"];
+    readonly objections: {
+        readonly missing: {
+            readonly message: "The diff removes `{element}` and no planned test says it is gone.";
+            readonly suggestion: "Plan a UI test on the page that still renders, asserting this element is absent, and name it in that test's elements. Removing it is what this pull request ships, so the removal is what gets tested. If the diff shows it still rendering under a new identifier it is a rename, not a removal — say so as the answer.";
+        };
+    };
+    readonly suggestion: "Does every element this diff removes have a planned test that asserts it is gone?";
+};
+/** In the order of `PLAN_TIME_VERIFIERS`, which decides the order objections are
+ *  reported in and carries no priority. References, not copies: iterating this
+ *  array, or indexing it with a variable, widens the element to the union of them
+ *  all and then no `objections` key resolves. */
+export declare const VERIFIER_CONTRACTS: readonly [{
+    readonly id: "changedFile";
+    readonly declarationFields: readonly ["declarations.changedFile", "declarations.screenEvidence.file"];
+    readonly objections: {
+        readonly notStated: {
+            readonly message: "This test does not state which changed file it targets.";
+            readonly suggestion: "Name the repository-relative file this test is about in `changedFile`, spelled as the diff spells it.";
+        };
+        readonly unrelated: {
+            readonly message: "The file this test names as its changed file is not one this pull request changed.";
+            readonly suggestion: "Name a file from this PR's own diff in `changedFile`, repository-relative and spelled as the diff spells it — or say why this test belongs in the plan without one.";
+        };
+        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 screenEvidenceUnrelated: {
+            readonly message: "The file this UI test cites for its screen is not one this pull request changed.";
+            readonly suggestion: "Which changed file renders the screen this test opens — or which changed screen should it open instead? Name that file in `screenEvidence.file`, repository-relative, spelled as the diff spells it.";
+        };
+    };
+    readonly suggestion: "Which file that this pull request changed does this test target?";
+}, {
+    readonly id: "endpointGrounded";
+    readonly declarationFields: readonly ["steps[]", "testType", "declarations.routes"];
+    readonly objections: {
+        readonly uncited: {
+            readonly message: "A call this test makes cites no file that declares it.";
+            readonly suggestion: "Add a `routes` entry naming the repository file that declares it — the route or operation need not appear verbatim in that file. A route the endpoint catalog missed is evidence of nothing: cite the file and keep the planned test.";
+        };
+        readonly disqualifiedCitation: {
+            readonly message: "The file this test cites for a call cannot be the file that declares it.";
+            readonly suggestion: "Cite the source file that declares it — not a test, not built output, not documentation. Any language or format is accepted, and the route or operation need not appear verbatim in the file.";
+        };
+        readonly uncitedAndDisqualified: {
+            readonly message: "This test has a call with no citation, and a call whose cited file cannot be the file that declares it.";
+            readonly suggestion: "Add `routes` for the call that has none, and point the other citation at the source file that declares its route or operation. Neither need appear verbatim in the file.";
+        };
+    };
+    readonly suggestion: "Which repository file declares this route or operation, and does an entry name that step's `order`?";
+}, {
+    readonly id: "statedDifference";
+    readonly declarationFields: readonly ["steps[]", "testType", "scenarioName", "declarations.differsFrom"];
+    readonly objections: {
+        readonly unexplainedPair: {
+            readonly message: "Another planned test in this plan tests the same endpoint and neither says how they differ.";
+            readonly suggestion: "Two tests on one endpoint is a legitimate plan. This asks HOW they differ, not whether one should go. Add a `differsFrom` entry naming the other planned test and what this one asserts that it does not — or, if one really is redundant, drop it.";
+        };
+        readonly unknownPartner: {
+            readonly message: "A `differsFrom` entry names a partner that is not a planned test in this plan.";
+            readonly suggestion: "Spell the partner's `scenarioName` exactly as it appears in your own planned test list — the match is exact apart from surrounding space, so a difference in case names nothing.";
+        };
+        readonly subjectNotStated: {
+            readonly message: "This test makes more than one call and does not say which one it is about.";
+            readonly suggestion: "Set `declarations.stepUnderTest` to the `order` of the step under test. The other calls are setup, and nothing on the server ranks them for you.";
+        };
+    };
+    readonly suggestion: "Which call is this test about, and what does it assert that the other planned test on the same endpoint does not?";
+}, {
+    readonly id: "existingCoverage";
+    readonly declarationFields: readonly ["declarations.existingTests"];
+    readonly objections: {
+        readonly citedTestMissing: {
+            readonly message: "This planned test names an existing test file that is not in the checkout.";
+            readonly suggestion: "Name the file repository-relative, spelled as the analysis lists it. Drop the entry if it names a test you did not read — naming none is an answer too.";
+        };
+    };
+    readonly suggestion: "Which existing tests did you read on this change, and how does this planned test differ from them?";
+}, {
+    readonly id: "expectedOutcome";
+    readonly declarationFields: readonly ["category", "declarations.expected.outcome", "declarations.expected.why"];
+    readonly objections: {
+        readonly passInShouldFailCategory: {
+            readonly message: "This planned test is categorised \"{category}\" but expects to pass on the app as it stands.";
+            readonly suggestion: "If it catches a defect, it should be red until the defect is fixed — say so. If it pins behaviour that is already correct, change the category.";
+        };
+        readonly executed: {
+            readonly message: "This test failed, but it did not reach the behavior it was written for — it fell over earlier. A failure like this is not a caught bug.";
+            readonly suggestion: "If the blocker is the test's own setup — sign-in, token, a wrong path — fix it and run the test again. If the blocker is the defect this run reports (a route that is not mounted, a server error before the behaviour), answer this objection naming that issue: the failure then stands as evidence of that issue, not as a caught bug.";
+        };
+    };
+    readonly suggestion: "Should this test fail until the defect is fixed, or is the category wrong for a test that pins behaviour the app already has?";
+}, {
+    readonly id: "uiElementGrounded";
+    readonly declarationFields: readonly ["testType", "steps[]", "declarations.elements.items", "declarations.elements.pageUrl", "declarations.asserts", "scenarioName", "description", "declarations.expected.why"];
+    readonly objections: {
+        readonly nogrounding: {
+            readonly message: "This UI test names no `elements.items`, so nothing says the elements it targets are on the page.";
+            readonly suggestion: "Copy the elements this test targets out of the capture of the page it runs on into `elements.items`, and set `elements.pageUrl` to that page. If no captured page holds this test's elements — the changed component mounts nowhere the run reached, or the screen is behind a gate this run could not pass — answer this objection saying which, and leave `elements.items` null.";
+        };
+        readonly duplicate: {
+            readonly message: "`elements.items` names the same element more than once.";
+            readonly suggestion: "List each element once. Two entries that agree on role, name and identifiers describe one element, and the repeat states nothing the first entry did not.";
+        };
+        readonly pagecontext: {
+            readonly message: "This UI test names `elements.items` but no page they came from.";
+            readonly suggestion: "Set `elements.pageUrl` to the `url` of the capture the elements were lifted from. Without it there is no page to look them up on.";
+        };
+        readonly ungrounded: {
+            readonly message: "An element this UI test targets is in no blueprint captured for that page.";
+            readonly suggestion: "Cite what a capture shows you, never what the screen ought to have. A capture shows the page as it stood when it was taken, so an element behind a modal, a dropdown or an accordion is legitimately absent — answer this objection naming the action that reveals it. Otherwise copy the element from the capture as it is spelled there, or point `elements.pageUrl` at the page you actually captured.";
+        };
+    };
+    readonly suggestion: "Which capture of the page does each declared element come from, and for one that is in no capture, which action on that page reveals it?";
+}, {
+    readonly id: "screenRoute";
+    readonly declarationFields: readonly ["declarations.elements.pageUrl", "declarations.screenEvidence.file", "declarations.changedFile"];
+    readonly objections: {
+        readonly mismatch: {
+            readonly message: "The page this UI test opens is not a page that renders the changed file it is about.";
+            readonly suggestion: "Open one of the routes in the evidence, or name the changed file that does render this page in `screenEvidence.file`. `skyramp_resolve_screen` gives the url to open, with the route parameters it can fill. A trace recorded on a screen the diff did not change proves nothing about the change.";
+        };
+        readonly unmounted: {
+            readonly message: "No route this run found renders the file this UI test is about.";
+            readonly suggestion: "If a route in this PR mounts it, name that route in `elements.pageUrl`. If nothing mounts it, the component is unintegrated: say so in one line and keep the planned test out of the browser.";
+        };
+    };
+    readonly suggestion: "Does the page this test opens render the changed file the test is about?";
+}, {
+    readonly id: "coverage";
+    readonly declarationFields: readonly ["changes", "declarations.changes", "declarations.changedFile", "declarations.routes", "declarations.screenEvidence.file", "declarations.startState", "changes[].cases", "changes[].surfaces"];
+    readonly objections: {
+        readonly change: {
+            readonly message: "This declared change has no test in the plan.";
+            readonly suggestion: "Plan a test that exercises it. If this run cannot write one, answer it and set `blocker` to what stopped the run — a service that is not running, a paired branch that no longer exists, the one credential the run holds. An answer with no blocker leaves this open: a change nothing prevented a test from reaching takes the test. Coverage per file is the basic minimum; coverage per change is what the plan is judged by, so a file covered by a shape test still leaves the change it makes untested.";
+        };
+        readonly noChanges: {
+            readonly message: "The plan declares no changes, so nothing says what the pull request must make different.";
+            readonly suggestion: "List the behaviours the pull request description promises, one sentence each, and cite them from the planned tests that test them — or answer in one line that it promises none, which a docs-only or cosmetic change legitimately does.";
+        };
+        readonly unknownChange: {
+            readonly message: "A planned test cites a change id that this plan does not declare.";
+            readonly suggestion: "Spell the change's `id` exactly as your own `changes` list gives it — the match is exact apart from surrounding space. Declare the change if it is missing.";
+        };
+        readonly file: {
+            readonly message: "This changed file has no test in the plan.";
+            readonly suggestion: "Add a planned test that cites it — as `changedFile`, as a `routes` file, or as `screenEvidence.file` — or answer in ONE line why it needs none: config only, covered by the test on the route it serves, or style-only and covered by the UI test on the page it belongs to. This check is a floor, never a cap: it never asks you to plan fewer tests.";
+        };
+        readonly stateTest: {
+            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 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.";
+        };
+        readonly reject: {
+            readonly message: "`{param}` accepts `{value}`, a record the plan creates, and no case rejects a record that is not there or belongs to another parent.";
+            readonly suggestion: "Add a reject case on `{param}` with a value that is not that record and a step that sends it, or answer why the route cannot refuse it.";
+        };
+        readonly surface: {
+            readonly message: "No {kind} test cites this change, which is on the {surface}.";
+            readonly suggestion: "Add a test on that surface that cites this change, or answer in one line why that surface needs no test.";
+        };
+    };
+    readonly suggestion: "Which planned test tests each behaviour this change promises and each file it touches, and for one nothing covers, why does it need none?";
+}, {
+    readonly id: "removedElementGuarded";
+    readonly declarationFields: readonly ["declarations.elements.items", "declarations.asserts"];
+    readonly objections: {
+        readonly missing: {
+            readonly message: "The diff removes `{element}` and no planned test says it is gone.";
+            readonly suggestion: "Plan a UI test on the page that still renders, asserting this element is absent, and name it in that test's elements. Removing it is what this pull request ships, so the removal is what gets tested. If the diff shows it still rendering under a new identifier it is a rename, not a removal — say so as the answer.";
+        };
+    };
+    readonly suggestion: "Does every element this diff removes have a planned test that asserts it is gone?";
+}];
+/** 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
+ *  in an otherwise ordinary sentence. */
+export declare function fillPlaceholders(text: string, values: Record<string, string | number>): string;