@skyramp/mcp 0.4.1 → 0.4.2-rc.1

package/build/tools/test-management/resolveScreenTool.js

@@ -25,7 +25,7 @@ import { TOOL_RESOLVE_SCREEN } from "../../toolNames.js";
 import { logger } from "../../utils/logger.js";
 import { lastKnownBrowserUrl } from "../../playwright/blueprintDigestStore.js";
 import { readWorkspaceServices } from "../../prompts/prompt-utils.js";
-import { createScreenRouteLookup } from "../../utils/screenRoutes.js";
+import { createScreenRouteLookup, } from "../../utils/screenRoutes.js";
 // ── Route patterns ──────────────────────────────────────────────────────────
 /** A pattern segment, in the four spellings the frameworks this run meets use:
  *  TanStack `$id`, React/Vue `:id`, Next `[id]`, OpenAPI-ish `{id}`. Mirrors the
@@ -55,7 +55,9 @@ export function urlPath(raw) {
         return new URL(value).pathname.replace(/\/+$/, "") || "/";
     }
     catch {
-        return value.startsWith("/") ? value.split(/[?#]/)[0].replace(/\/+$/, "") || "/" : "";
+        return value.startsWith("/")
+            ? value.split(/[?#]/)[0].replace(/\/+$/, "") || "/"
+            : "";
     }
 }
 function origin(raw) {
@@ -112,7 +114,9 @@ export function bindFromLocation(location, patterns) {
         if (!best || literals > best.literals)
             best = { pattern, values, literals };
     }
-    return best ? { pattern: best.pattern, values: best.values, source: location.source } : undefined;
+    return best
+        ? { pattern: best.pattern, values: best.values, source: location.source }
+        : undefined;
 }
 /** The pattern with its bound parameters substituted, prefixed by the origin when
  *  one is known. An unbound parameter is left in its own spelling rather than
@@ -198,7 +202,13 @@ export function buildResolveScreenResult(input) {
             "and do not invent one — a plausible wrong id renders an empty page that looks real.");
     }
     lines.push("`mountChain` is the import path from the route file to the changed file: check it rather than trust it.");
-    return { status: "resolved", candidates: resolved, notOn, needs: [...needs], summary: lines.join(" ") };
+    return {
+        status: "resolved",
+        candidates: resolved,
+        notOn,
+        needs: [...needs],
+        summary: lines.join(" "),
+    };
 }
 // ── Workspace default for baseUrl ───────────────────────────────────────────
 /**
@@ -215,7 +225,11 @@ export async function workspaceUiBaseUrl(repositoryPath) {
         const services = (await readWorkspaceServices(repositoryPath));
         const withUrl = services.filter((service) => typeof service?.api?.baseUrl === "string" && service.api.baseUrl);
         const playwright = withUrl.filter((service) => service.framework === "playwright");
-        const chosen = playwright.length === 1 ? playwright[0] : withUrl.length === 1 ? withUrl[0] : undefined;
+        const chosen = playwright.length === 1
+            ? playwright[0]
+            : withUrl.length === 1
+                ? withUrl[0]
+                : undefined;
         return chosen ? origin(chosen.api?.baseUrl) : undefined;
     }
     catch {
@@ -224,7 +238,9 @@ export async function workspaceUiBaseUrl(repositoryPath) {
 }
 // ── Registration ────────────────────────────────────────────────────────────
 const inputSchema = {
-    repositoryPath: z.string().describe("Absolute path to the repository checkout that holds the frontend file."),
+    repositoryPath: z
+        .string()
+        .describe("Absolute path to the repository checkout that holds the frontend file."),
     changedFile: z
         .string()
         .describe("Repository-relative path of the frontend file the test is about — the file the diff changed, " +
@@ -244,14 +260,19 @@ const outputSchema = {
         .array(z.object({
         url: z.string(),
         routePattern: z.string(),
-        params: z.record(z.object({ value: z.string(), from: z.enum(["currentUrl", "blueprint", "unresolved"]) })),
+        params: z.record(z.object({
+            value: z.string(),
+            from: z.enum(["currentUrl", "blueprint", "unresolved"]),
+        })),
         mountChain: z.array(z.string()),
     }))
         .describe("Each route that renders the file, with the import chain from its route file down to the file."),
     notOn: z
         .array(z.string())
         .describe("The route the browser is currently on, when it is not one that renders the file."),
-    needs: z.array(z.string()).describe("Route parameters no known value fills. Read them off the app; never invent one."),
+    needs: z
+        .array(z.string())
+        .describe("Route parameters no known value fills. Read them off the app; never invent one."),
     summary: z.string().describe("The same answer in one paragraph."),
 };
 const DESCRIPTION = "Answer which page of the running app renders a changed frontend file, and give the url to open. " +
@@ -284,6 +305,9 @@ export function registerResolveScreenTool(server) {
             routes: result.candidates.length,
             needs: result.needs.length,
         });
-        return { structuredContent: { ...result }, content: [{ type: "text", text: result.summary }] };
+        return {
+            structuredContent: { ...result },
+            content: [{ type: "text", text: result.summary }],
+        };
     });
 }

package/build/tools/trace/startTraceCollectionTool.js

@@ -251,7 +251,9 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 prompt: params.prompt,
                 playwright: params.playwright.toString(),
             };
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => {
+                logger.warning("Analytics event failed", { error: String(err) });
+            });
         }
     });
 }

package/build/tools/trace/stopTraceCollectionTool.js

@@ -51,6 +51,10 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
             prompt: params.prompt,
         });
         const client = new SkyrampClient();
+        // Declared outside the try so the catch below can report a leftover window
+        // too: traceCollect can throw after the terminal close already failed, and
+        // the user is still the only one who can close it.
+        let terminalAppendix = "";
         try {
             const stopTraceOptions = {
                 output: params.traceOutputFile,
@@ -90,14 +94,44 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
             if (errList.content.length > 0) {
                 return errList;
             }
-            await closeProxyTerminal();
+            // Never throws: this sits inside the try that wraps traceCollect, so a
+            // throw here would lose the trace over a leftover window.
+            const terminalClose = await closeProxyTerminal();
+            // Built before traceCollect so the failure response below carries it
+            // too: an orphaned window outlives a failed trace just as it does a
+            // successful one, and the user is the only one who can close it.
+            //
+            // Named titles are the trigger, not `closed`. A stop that opened no
+            // terminal also reports closed: false, and telling the user to close a
+            // window that was never opened is worse than saying nothing.
+            const strandedTitles = [
+                ...(terminalClose.orphanedTitles ?? []),
+                ...(terminalClose.closed || !terminalClose.title
+                    ? []
+                    : [terminalClose.title]),
+            ];
+            if (strandedTitles.length) {
+                // Windows can name the exact windows, so it does.
+                terminalAppendix =
+                    `\n\nNote: ${strandedTitles.length === 1 ? "a trace collection terminal window" : `${strandedTitles.length} trace collection terminal windows`} could not be closed automatically and must be closed by hand: ` +
+                        strandedTitles.map((t) => `"${t}"`).join(", ") +
+                        `.${terminalClose.reason ? ` (${terminalClose.reason})` : ""}`;
+            }
+            else if (!terminalClose.closed) {
+                // macOS and Linux close by PID and have no title to quote, so the
+                // reason carries it. Without this arm a failed close on those
+                // platforms is invisible to the user, which is the whole bug.
+                terminalAppendix =
+                    `\n\nNote: the trace collection terminal could not be closed automatically and may still be open` +
+                        `${terminalClose.reason ? ` (${terminalClose.reason})` : ""}.`;
+            }
             const result = await client.traceCollect(stopTraceOptions);
             if (result.toLowerCase().includes("failed")) {
                 errorResult = {
                     content: [
                         {
                             type: "text",
-                            text: `Trace collection failed: ${result}`,
+                            text: `Trace collection failed: ${result}${terminalAppendix}`,
                         },
                     ],
                     isError: true,
@@ -117,7 +151,7 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                         text: `Trace collection is stopped: ${result}. Trace is generated to given output file
 
               **IMPORTANT: GO THROUGH THE TRACE AND LET THE USER KNOW THE ENDPOINT DOMAINS CAPTURED AND MAKE SURE USER WANTS TO INCLUDE THEN FOR INTEGRATION/E2E/LOAD TEST GENERATION.
-              UI TESTS CAN BE GENERATED USING PLAYWRIGHT FILES ONLY.**${sessionAppendix}`,
+              UI TESTS CAN BE GENERATED USING PLAYWRIGHT FILES ONLY.**${sessionAppendix}${terminalAppendix}`,
                     },
                 ],
             };
@@ -128,7 +162,7 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 content: [
                     {
                         type: "text",
-                        text: `Trace generation result: ${error.message}`,
+                        text: `Trace generation result: ${error.message}${terminalAppendix}`,
                     },
                 ],
                 isError: true,
@@ -140,7 +174,9 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 prompt: params.prompt,
                 playwright: params.playwrightEnabled.toString(),
             };
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => {
+                logger.warning("Analytics event failed", { error: String(err) });
+            });
         }
     });
 }

package/build/tools/verifyTestDependenciesTool.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const VERIFY_TEST_DEPENDENCIES_TOOL = "skyramp_verify_test_dependencies";
+export declare function registerVerifyTestDependenciesTool(server: McpServer): void;

package/build/tools/verifyTestDependenciesTool.js

@@ -0,0 +1,54 @@
+import * as path from "path";
+import { z } from "zod";
+import { AnalyticsService } from "../services/AnalyticsService.js";
+import { logger } from "../utils/logger.js";
+import { verifyTestDependencyChanges } from "../utils/testDependencyPolicy.js";
+import { toolError } from "../utils/utils.js";
+export const VERIFY_TEST_DEPENDENCIES_TOOL = "skyramp_verify_test_dependencies";
+const schema = z.object({
+    repositoryPath: z
+        .string()
+        .refine((value) => path.isAbsolute(value), "repositoryPath must be an absolute path")
+        .describe("Absolute path to the repository whose working-tree dependency changes should be verified."),
+});
+export function registerVerifyTestDependenciesTool(server) {
+    server.registerTool(VERIFY_TEST_DEPENDENCIES_TOOL, {
+        description: "Verify that dependency changes made while fixing tests use only approved testing packages and development/test-only manifest scopes.",
+        inputSchema: schema.shape,
+        _meta: {
+            keywords: [
+                "dependencies",
+                "devDependencies",
+                "test dependencies",
+                "verification",
+            ],
+        },
+    }, async (params) => {
+        let result;
+        try {
+            const verification = await verifyTestDependencyChanges(params.repositoryPath);
+            result = verification.ok
+                ? {
+                    content: [
+                        {
+                            type: "text",
+                            text: `VERIFICATION PASSED — ${verification.checkedFiles.length} dependency file${verification.checkedFiles.length === 1 ? "" : "s"} checked.`,
+                        },
+                    ],
+                    isError: false,
+                }
+                : toolError("VERIFICATION FAILED — dependency changes are outside the safe test-only policy:\n" +
+                    verification.violations
+                        .map((violation) => `- ${violation}`)
+                        .join("\n") +
+                    "\nMove approved packages to the required development/test scope, remove unapproved or unrelated manifest edits, then run this verifier again.");
+        }
+        catch (error) {
+            result = toolError(`Test dependency verification failed: ${error.message}`);
+        }
+        AnalyticsService.pushMCPToolEvent(VERIFY_TEST_DEPENDENCIES_TOOL, result, {
+            repositoryPath: params.repositoryPath,
+        }).catch((error) => logger.warning("Analytics event failed", { error: String(error) }));
+        return result;
+    });
+}

package/build/tools/workspace/initScanWorkspaceTool.js

@@ -29,13 +29,17 @@ const initScanWorkspaceSchema = z.object({
 });
 export function registerInitScanWorkspaceTool(server) {
     server.registerTool(TOOL_NAME, {
-        description: "PREREQUISITE for skyramp_init_workspace. " +
+        description: "Call this FIRST, before any other Skyramp tool (test generation, execution, analysis), whenever workspacePath is a git repository and .skyramp/workspace.yml does not exist at its root. " +
+            "PREREQUISITE for skyramp_init_workspace. " +
             "Scans a repository and returns instructions for discovering all services, along with a scanToken. " +
             "Follow the instructions to build the services array, then pass both to skyramp_init_workspace to create the workspace config.",
         inputSchema: initScanWorkspaceSchema.shape,
     }, async (params) => {
         let errorResult;
-        const recordParams = { workspacePath: params.workspacePath, force: String(params.force || false) };
+        const recordParams = {
+            workspacePath: params.workspacePath,
+            force: String(params.force || false),
+        };
         try {
             const manager = new WorkspaceConfigManager(params.workspacePath);
             if ((await manager.exists()) && !params.force) {
@@ -70,7 +74,9 @@ export function registerInitScanWorkspaceTool(server) {
             return errorResult;
         }
         finally {
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => {
+                logger.warning("Analytics event failed", { error: String(err) });
+            });
         }
     });
 }

package/build/tools/workspace/initializeWorkspaceTool.js

@@ -273,7 +273,9 @@ export function registerInitializeWorkspaceTool(server) {
             return errorResult;
         }
         finally {
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams).catch((err) => {
+                logger.warning("Analytics event failed", { error: String(err) });
+            });
         }
     });
 }

package/build/types/AssertionOutcome.d.ts

@@ -1,5 +1,5 @@
 import type { TestType } from "./TestTypes.js";
-import type { EnhanceType } from "../prompts/enhance-assertions/sharedAssertionRules.js";
+import type { EnhanceType } from "./EnhanceType.js";
 /**
  * Server-derived assertion-enhancement state. Lives in types/ (not beside
  * assertion-state.ts) because AnalysisStateManager embeds AssertionRecord in

package/build/types/EnhanceType.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The context an assertion enhancement runs in. Kept in its own leaf module so
+ * the run-state types, the verify layer, and the skill layer can all share the
+ * union without importing each other.
+ */
+export type EnhanceType = "generation" | "maintenance";

package/build/types/EnhanceType.js

@@ -0,0 +1 @@
+export {};

package/build/types/ExternalTestExecution.d.ts

@@ -62,6 +62,6 @@ export interface ExternalTestRunRecord extends ParsedExternalRun {
     mode: "confirm" | "verify";
     /** ISO timestamp when the run completed. */
     ranAt: string;
-    /** owner/repo this run targeted (multi-repo runs); absent → primary. */
-    repository?: string;
+    /** owner/repo this run targeted. */
+    repository: string;
 }

package/build/types/RepositoryAnalysis.d.ts

@@ -1,6 +1,4 @@
 import { z } from "zod";
-import { ScenarioCategory } from "./TestRecommendation.js";
-import { TestType } from "./TestTypes.js";
 import type { ProjectType, DeploymentPattern } from "../utils/projectMetadata.js";
 /**
  * Repository Analysis Types
@@ -98,44 +96,6 @@ export declare enum ScenarioSource {
     Documentation = "documentation",
     AgentEnriched = "agent-enriched"
 }
-export interface PlanScenario {
-    scenarioName: string;
-    description: string;
-    category: ScenarioCategory;
-    priority: "high" | "medium" | "low";
-    steps: ScenarioStep[];
-    chainingKeys: string[];
-    requiresAuth: boolean;
-    estimatedComplexity: "simple" | "moderate" | "complex";
-    source?: ScenarioSource;
-    /** Only integration, contract, e2e, and ui are valid for drafted scenarios. */
-    testType?: TestType;
-    /** Internal marker for destructive sibling auth-boundary scenarios. */
-    isAttackSurfaceSecurityBoundary?: boolean;
-    /**
-     * The specific bug or formula this test is designed to catch.
-     * Written during scenario drafting when source code is read.
-     * Examples:
-     *   "discount formula: total_amount = subtotal * (1 - discount_value / 100)"
-     *   "items not recalculated after PATCH — total_amount stays at old value"
-     *   "missing 404 guard on non-existent order_id"
-     * Used by the testbot to compute exact assertion values instead of null-checks.
-     */
-    bugCatchingTarget?: string;
-    /**
-     * The endpoints this test is about, resolved one time by
-     * `resolveSubjectEndpoints` where the PR diff is available. Every dedup
-     * reader keys off this list rather than deriving a subject again from
-     * `steps[]` — SKYR-4214: two stages derived different subjects for one
-     * candidate, so whether a candidate deduped depended on whether the model
-     * happened to append a cleanup step.
-     *
-     * Absent on a scenario from an older state file; readers then fall back to
-     * the last-mutating-step rule. An EMPTY list means "no information" and must
-     * never be read as "covered".
-     */
-    subjectEndpoints?: SubjectEndpoint[];
-}
 export interface BranchDiffContext {
     currentBranch: string;
     baseBranch: string;

package/build/types/ReuseOutcome.d.ts

@@ -17,6 +17,22 @@ import type { UtilsViolationKind } from "../utils/utils-verify/allow.js";
  * The internal record that run state keeps between the verify pass and the report
  * step (`ReuseRecord`) deliberately stays private to the derivation module — it is
  * not part of this contract and must never reach a report.
+ *
+ * ABSENCE MEANS NOT MEASURED — the one invariant every member here obeys, and the
+ * one a producer is most likely to break. An optional member is omitted when this
+ * run did not establish its value, NEVER to mean `false`, `0` or "no": a `boolean?`
+ * left off says the check did not run, not that it failed, and a count left off says
+ * nothing was counted, not that the count was zero. So a producer that cannot
+ * measure something omits it rather than defaulting it, and a consumer renders an
+ * absent member as unknown rather than as a negative result.
+ *
+ * It is what lets a field be added without re-reading every row ever written, and
+ * what keeps a row from asserting more than the run established — the failure this
+ * whole shape exists to prevent, and the one that has recurred: a `reuse` of `null`
+ * over a test that demonstrably reused was read as "did not reuse" for four cohorts
+ * (see {@link ReuseOutcome.notDerived}). Where the distinction has to be visible in
+ * the report rather than inferred, the shape says so explicitly instead of relying
+ * on an omission.
  */
 /** Which gate declined a POM member. */
 export declare enum ReuseDeclinedBy {
@@ -158,8 +174,17 @@ export interface HelperReuseOutcome {
      *  row ships with this field set, so the fault is disclosed rather than delivered
      *  in silence — or not delivered at all. */
     verificationFailures?: ReuseVerificationFailure[];
-    /** Pre-existing generated tests this spec's reuse pass rewired onto the utils
-     *  file, each with its recorded execution. Omitted when none. */
+    /** Pre-existing generated tests rewired onto the utils file by this run, each with
+     *  its recorded execution. Omitted when none.
+     *
+     *  Normally these are the siblings THIS spec's reuse pass reached. A row may also
+     *  name its OWN file: where two specs on one module were each edited by their own
+     *  chain, each claimed the other as its retrofit, and a claim that cannot be true
+     *  in both directions is reported against neither. The rewiring is still disclosed,
+     *  on the row for the file it happened to.
+     *
+     *  Across the rows of one report every file appears at most once, so the lists stay
+     *  disjoint and summable. */
     retrofits?: RetrofitOutcome[];
     /** Whether the delivered test plus the helpers it imports and calls still hold at
      *  least as many assertions as when modularization was handed out. A measured
@@ -172,10 +197,58 @@ export interface HelperReuseOutcome {
     /** Whether the `page.on('pageerror', …)` guard present at the modularization
      *  hand-out is still registered, in the test or in a shared helper it imports and
      *  calls. `true` when the hand-out had no guard to lose. Present whenever the
-     *  baseline exists, absent otherwise — like every optional member here, absent
-     *  means "not measured", never "false". */
+     *  baseline exists, absent otherwise — by the absence rule in this file's header. */
     pageErrorGuardPreserved?: boolean;
 }
+/** One of the repository's own helpers, and the module it lives in. */
+export interface InHouseHelperRef {
+    /** REPOSITORY-RELATIVE PATH (posix) of the customer's module. */
+    module: string;
+    helper: string;
+}
+/** A helper the run read in an in-house module and did not use. DECLARED by the
+ *  agent — recorded, never measured. */
+export interface InHouseDeclinedEntry {
+    file: string;
+    helper: string;
+    reason: string;
+}
+/**
+ * Reuse of the repository's OWN helper modules — files the customer wrote — by a
+ * browser test. Two kinds of field, and the report must label them apart:
+ *
+ * - MEASURED, re-derived from the delivered files at report time: which of the
+ *   customer's modules the spec imports, which helpers resolve, what this run added
+ *   to or widened in those modules (against HEAD), whether the additive gate ran.
+ * - DECLARED by the agent, recorded as testimony: the files its search read, and
+ *   the helpers it read and declined with the reason. A file list the agent produced
+ *   is not evidence the agent read everything, and the report says so.
+ *
+ * Absent when the spec imports no in-house module.
+ */
+export interface InHouseReuseOutcome {
+    /** MEASURED. Repository-relative paths of the customer's modules the spec imports. */
+    modules: string[];
+    /** MEASURED. Helpers the spec imports from those modules that resolve there. */
+    helpersUsed: string[];
+    /** MEASURED. Helpers this run added to a customer's module. */
+    helpersAdded: InHouseHelperRef[];
+    /** MEASURED. Existing helpers this run gave a defaulted parameter, and nothing else. */
+    helpersWidened: InHouseHelperRef[];
+    /** MEASURED. Whether every module was compared against HEAD. `false` is a gate
+     *  that could not run, never one that found nothing. */
+    additiveGateRan: boolean;
+    /** DECLARED. The files the agent's search read. Omitted when nothing was declared. */
+    filesRead?: string[];
+    /** DECLARED. Helpers the agent read and did not use, with its reason for each. */
+    declined?: InHouseDeclinedEntry[];
+    /** The in-house verdict, present only when no `helpers` row carries one — a spec
+     *  calling only in-house helpers has no Skyramp utils file, and "no utils file"
+     *  must not read as "nothing verified". */
+    verification?: HelperVerificationOutcome;
+    /** See {@link HelperReuseOutcome.verificationFailures}; present only on `failed`. */
+    verificationFailures?: ReuseVerificationFailure[];
+}
 /**
  * What lands in a report's `reuse` field for a generated test. Every member is
  * optional: consumers must render from whatever subset is present, and omit the
@@ -231,6 +304,25 @@ export interface ReuseOutcome {
     skipped?: ReuseSkippedEntry[];
     /** Shared-helper (SkyrampUtils) reuse. See {@link HelperReuseOutcome}. */
     helpers?: HelperReuseOutcome;
+    /** Reuse of the repository's own helper modules. See {@link InHouseReuseOutcome}. */
+    inHouse?: InHouseReuseOutcome;
+    /** Why no reuse record could be derived for this row, in a reader's words.
+     *
+     *  Present only when nothing else here is: no `helpers`, no `inHouse`, no POM
+     *  fields. It exists because their absence alone is ambiguous — a row with no
+     *  reuse summary reads identically to a row whose test reused nothing, and
+     *  consumers and reviewers have read it as the latter. A stated reason ("the
+     *  delivered file could not be read", "no shared helper module was located for
+     *  this test") separates the two.
+     *
+     *  The one place the absence rule above is not enough, and so the one member that
+     *  states what an omission cannot: every other member is absent when unmeasured,
+     *  and this says WHY the whole row is.
+     *
+     *  Never a verdict and never a fault: a run that legitimately had nothing to reuse
+     *  says so here. Additive and optional like every other member, so a consumer that
+     *  does not know it renders exactly what it rendered before. */
+    notDerived?: string;
     /** Present — and only ever `true` — when generation handed off a modularize→reuse
      *  step for this test and no reuse pass was recorded for it. Since the execution
      *  checkpoint refuses to run such a test until reuse is called, this can only

package/build/types/ReuseOutcome.js

@@ -15,6 +15,22 @@
  * The internal record that run state keeps between the verify pass and the report
  * step (`ReuseRecord`) deliberately stays private to the derivation module — it is
  * not part of this contract and must never reach a report.
+ *
+ * ABSENCE MEANS NOT MEASURED — the one invariant every member here obeys, and the
+ * one a producer is most likely to break. An optional member is omitted when this
+ * run did not establish its value, NEVER to mean `false`, `0` or "no": a `boolean?`
+ * left off says the check did not run, not that it failed, and a count left off says
+ * nothing was counted, not that the count was zero. So a producer that cannot
+ * measure something omits it rather than defaulting it, and a consumer renders an
+ * absent member as unknown rather than as a negative result.
+ *
+ * It is what lets a field be added without re-reading every row ever written, and
+ * what keeps a row from asserting more than the run established — the failure this
+ * whole shape exists to prevent, and the one that has recurred: a `reuse` of `null`
+ * over a test that demonstrably reused was read as "did not reuse" for four cohorts
+ * (see {@link ReuseOutcome.notDerived}). Where the distinction has to be visible in
+ * the report rather than inferred, the shape says so explicitly instead of relying
+ * on an omission.
  */
 /** Which gate declined a POM member. */
 export var ReuseDeclinedBy;

package/build/types/StepMethod.js

@@ -37,7 +37,11 @@ export const UI_STEP_VERBS = [
 /** A call to something with no HTTP verb — a GraphQL operation, a Thrift or gRPC
  *  method. The operation's own name goes in `path`, and in `routes.operation`. */
 export const OPERATION_STEP_METHOD = "OPERATION";
-export const STEP_METHODS = [...HTTP_STEP_METHODS, ...UI_STEP_VERBS, OPERATION_STEP_METHOD];
+export const STEP_METHODS = [
+    ...HTTP_STEP_METHODS,
+    ...UI_STEP_VERBS,
+    OPERATION_STEP_METHOD,
+];
 const HTTP_BY_SPELLING = new Map(HTTP_STEP_METHODS.map((m) => [m.toLowerCase(), m]));
 const UI_BY_SPELLING = new Map(UI_STEP_VERBS.map((v) => [v, v]));
 /** One spelling of a method reduced to the canonical one, or `undefined` when it is
@@ -45,21 +49,27 @@ const UI_BY_SPELLING = new Map(UI_STEP_VERBS.map((v) => [v, v]));
  *  fixed on store, so `" post"` and `"Click"` are the same step as `POST` and
  *  `click`. Without the trim, one trailing space decided which checks ran. */
 export function normalizeStepMethod(raw) {
-    const spelling = String(raw ?? "").trim().toLowerCase();
+    const spelling = String(raw ?? "")
+        .trim()
+        .toLowerCase();
     if (!spelling)
         return undefined;
-    return HTTP_BY_SPELLING.get(spelling) ?? UI_BY_SPELLING.get(spelling) ?? (spelling === "operation" ? OPERATION_STEP_METHOD : undefined);
+    return (HTTP_BY_SPELLING.get(spelling) ??
+        UI_BY_SPELLING.get(spelling) ??
+        (spelling === "operation" ? OPERATION_STEP_METHOD : undefined));
 }
 /** Whether a method names a page interaction. Read off the canonical spelling,
  *  so a step that never went through the schema is judged the same way. */
 export function isUiStepVerb(raw) {
     const method = normalizeStepMethod(raw);
-    return method !== undefined && UI_STEP_VERBS.includes(method);
+    return (method !== undefined &&
+        UI_STEP_VERBS.includes(method));
 }
 /** Whether a method names an HTTP request. */
 export function isHttpStepMethod(raw) {
     const method = normalizeStepMethod(raw);
-    return method !== undefined && HTTP_STEP_METHODS.includes(method);
+    return (method !== undefined &&
+        HTTP_STEP_METHODS.includes(method));
 }
 const STEP_METHOD_HELP = `must be an HTTP method (${HTTP_STEP_METHODS.join(", ")}), a page interaction ` +
     `(${UI_STEP_VERBS.join(", ")}), or "${OPERATION_STEP_METHOD}" for a call with no HTTP verb — ` +
@@ -74,4 +84,8 @@ export const STEP_METHOD_DESCRIPTION = "What this step does to the system: an HT
  * The field itself: normalised first, then checked, so a rejection is about the
  * verb and never about its capitalisation.
  */
-export const stepMethodSchema = z.preprocess((value) => (typeof value === "string" ? (normalizeStepMethod(value) ?? value.trim()) : value), z.enum(STEP_METHODS, { errorMap: () => ({ message: `method ${STEP_METHOD_HELP}` }) }));
+export const stepMethodSchema = z.preprocess((value) => typeof value === "string"
+    ? (normalizeStepMethod(value) ?? value.trim())
+    : value, z.enum(STEP_METHODS, {
+    errorMap: () => ({ message: `method ${STEP_METHOD_HELP}` }),
+}));

package/build/types/TestAnalysis.d.ts

@@ -59,6 +59,13 @@ export interface MaintenanceActionCore {
      *  without this a downstream stage cannot tell a regeneration that rewrote a file from
      *  one that only advised it — and maintenance coverage would credit the advice. */
     reportOnly?: boolean;
+    /** Computed during instruction building — the path this UPDATE renames the spec TO,
+     *  when the endpoint rename implies one. Part of the core shape because the report
+     *  stage needs it: the rename lands before the test is executed, so the run is
+     *  recorded under THIS path while `testFilePath` still holds the old name, and a
+     *  stage that joins runs to files by `testFilePath` alone looks for a file that is
+     *  no longer there. */
+    _suggestedNewFile?: string;
 }
 /** Normalized internal recommendation built from LLM-supplied args.recommendations. */
 export interface DriftRecommendation extends MaintenanceActionCore {
@@ -78,8 +85,9 @@ export interface DriftRecommendation extends MaintenanceActionCore {
         anchor: string;
         change?: string;
     }>;
-    /** Computed during instruction building — suggested renamed file path if applicable. */
-    _suggestedNewFile?: string;
+    /** Computed during instruction building — the modularize → reuse steps this UPDATE's
+     *  file owes, when its language and test type are a modularize-first target. */
+    _postEditSteps?: string;
     /** REGENERATE/DELETE on an external (user-authored) test is report-only: the verdict is
      *  recorded and rendered in the report so the developer sees the recommendation, but the
      *  file is never touched (the apply loops skip reportOnly entries). Lets the report keep