@skyramp/mcp 0.4.1 → 0.4.2-rc.2

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

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { logger } from "../../utils/logger.js";
 import { StateManager, } from "../../utils/AnalysisStateManager.js";
-import { TestSource, DriftAction, RecommendationPriority, EstimatedWork } from "../../types/TestAnalysis.js";
+import { TestSource, DriftAction, RecommendationPriority, EstimatedWork, } from "../../types/TestAnalysis.js";
 import { TestExecutionStatus } from "../../types/TestExecution.js";
 import { TestType } from "../../types/TestTypes.js";
 import * as fs from "fs";
@@ -9,8 +9,13 @@ import * as path from "path";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { dualChannelResult, toolError } from "../../utils/utils.js";
 import { isTestFile } from "../../utils/testFileClassification.js";
-import { REBASELINE_SNAPSHOT_NAME_RE, looksLikeOnDiskBaselineName } from "../../utils/rebaselineSnapshots.js";
+import { REBASELINE_SNAPSHOT_NAME_RE, looksLikeOnDiskBaselineName, } from "../../utils/rebaselineSnapshots.js";
 import { buildRenameStrategy, buildFileRenameStrategy, buildUpdateStrategy, buildRebaselineStrategy, buildRegenerateStrategy, buildDeleteStrategy, buildUpdateFileInstruction, buildRegenerateFileInstruction, } from "../../prompts/test-maintenance/actionsInstructions.js";
+import { buildModularizeFirstNextSteps, isMaintenanceRegenerable, isModularizeFirstHandOffTarget, regenerateCodeReuse, } from "../../prompts/reuse-hand-off.js";
+import { recordReuseHandOff } from "../code-refactor/reuse-state.js";
+import { isPlanOnlyMode } from "../../utils/planOnlyMode.js";
+import { runTestCall } from "../../skills/runTestSkill.js";
+import { formatOwedFiles, testsOwedBeforeRun } from "./testsOwedBeforeRun.js";
 /**
  * Compute a suggested new filename when an endpoint is renamed.
  */
@@ -51,12 +56,16 @@ export function computeRenamedTestFile(testFile, renames) {
 const recommendationSchema = z.object({
     testFilePath: z
         .string()
-        .refine((p) => path.isAbsolute(p), { message: "testFilePath must be an absolute path" })
+        .refine((p) => path.isAbsolute(p), {
+        message: "testFilePath must be an absolute path",
+    })
         .describe("Absolute path to the test spec file — use the path as reported by skyramp_analyze_changes or skyramp_analyze_test_health. For POM-based tests, this is the spec file (shown in the report); set pomFile to the page object path to edit."),
     pomFile: z
         .string()
         .optional()
-        .refine((p) => p === undefined || path.isAbsolute(p), { message: "pomFile must be an absolute path" })
+        .refine((p) => p === undefined || path.isAbsolute(p), {
+        message: "pomFile must be an absolute path",
+    })
         .describe("Absolute path to the page object (POM) file to edit, when the spec delegates selectors to a page object. When set, skyramp_actions edits this file instead of testFilePath. testFilePath (the spec) is still used for catalog validation and the maintenance report."),
     action: z
         .nativeEnum(DriftAction)
@@ -94,12 +103,19 @@ const recommendationSchema = z.object({
         "Test hits GET /products — assert stock_count is present and non-negative.'"),
     editSites: z
         .array(z.object({
-        line: z.number().int().min(1).describe("1-based line number of the edit site in the current file."),
+        line: z
+            .number()
+            .int()
+            .min(1)
+            .describe("1-based line number of the edit site in the current file."),
         anchor: z
             .string()
             .min(1)
             .describe("A short verbatim snippet from that line (copied exactly from the file you read) so the edit can be located without re-scanning."),
-        change: z.string().optional().describe("What to change at this site (e.g. 'add work_pool_name to this payload')."),
+        change: z
+            .string()
+            .optional()
+            .describe("What to change at this site (e.g. 'add work_pool_name to this payload')."),
     }))
         .optional()
         .describe("For a large UPDATE file, the concrete per-site edits you already located while reading it — one entry per place that must change, with a verbatim anchor. " +
@@ -110,7 +126,7 @@ const recommendationSchema = z.object({
         // are dropped and surfaced in the response.
         .array(z.string())
         .optional()
-        .describe("UPDATE only — the toHaveScreenshot() baseline filenames (e.g. [\"page-001.png\"]) whose captured page/element/region the diff visibly changed, so the committed PNG is stale (SKYR-4298). " +
+        .describe('UPDATE only — the toHaveScreenshot() baseline filenames (e.g. ["page-001.png"]) whose captured page/element/region the diff visibly changed, so the committed PNG is stale (SKYR-4298). ' +
         "List only the baselines the change reaches; leave unaffected ones out. These are refreshed at the final skyramp_execute_test run via its rebaselineSnapshots parameter, never by editing the assertion, its maxDiffPixelRatio, or the PNG. " +
         "Omit when the diff does not explain a screenshot mismatch — that failure stays red."),
     renamedEndpoints: z
@@ -125,12 +141,15 @@ const recommendationSchema = z.object({
 const actionsSchema = {
     stateFile: z
         .string()
-        .refine((p) => path.isAbsolute(p), { message: "stateFile must be an absolute path" })
+        .refine((p) => path.isAbsolute(p), {
+        message: "stateFile must be an absolute path",
+    })
         .describe("Path to state file from skyramp_analyze_changes"),
     repository: z
         .string()
-        .optional()
-        .describe("The owner/repo whose analysis section to act on (e.g. 'letsramp/api-insight'). In a multi-repo run, ALWAYS set it — the primary's owner/repo for the primary repo's tests, or a related repo's owner/repo for that repo's section — within the run-scoped stateFile. Omit only for a single-repo run."),
+        .trim()
+        .min(1)
+        .describe("The owner/repo whose analysis section to act on (e.g. 'letsramp/api-insight'). Set it on every call — the primary's owner/repo for the primary repo's tests, or a related repo's owner/repo for that repo's section — within the run-scoped stateFile."),
     recommendations: z
         .array(recommendationSchema)
         .default([])
@@ -180,7 +199,7 @@ export function registerActionsTool(server) {
             // Allowlist: Skyramp-generated tests + relevant external tests.
             // Using an allowlist (not a blocklist) catches hallucinated paths the LLM
             // may supply that are not in the scanned catalog at all.
-            const testAnalysisResults = (stateData.existingTests || []);
+            const testAnalysisResults = stateData.existingTests || [];
             const skyrampTestFiles = new Set(testAnalysisResults
                 .filter((t) => t.source !== TestSource.External)
                 .map((t) => t.testFile));
@@ -209,9 +228,14 @@ export function registerActionsTool(server) {
                 // Exception: files already in the scanned test catalog (externalTestFiles / skyrampTestFiles)
                 // may legitimately live in a separate testsRepoDir outside repositoryPath — catalog
                 // membership is a sufficient provenance check for those paths.
-                const isInCatalog = skyrampTestFiles.has(resolvedFile) || skyrampTestFiles.has(rec.testFilePath)
-                    || externalTestFiles.has(resolvedFile) || externalTestFiles.has(rec.testFilePath);
-                if (repoRoot && !isInCatalog && !resolvedFile.startsWith(repoRoot + path.sep) && resolvedFile !== repoRoot) {
+                const isInCatalog = skyrampTestFiles.has(resolvedFile) ||
+                    skyrampTestFiles.has(rec.testFilePath) ||
+                    externalTestFiles.has(resolvedFile) ||
+                    externalTestFiles.has(rec.testFilePath);
+                if (repoRoot &&
+                    !isInCatalog &&
+                    !resolvedFile.startsWith(repoRoot + path.sep) &&
+                    resolvedFile !== repoRoot) {
                     logger.warning(`Skipping recommendation for path outside repo root: ${rec.testFilePath}`);
                     return;
                 }
@@ -219,9 +243,11 @@ export function registerActionsTool(server) {
                 // recommendation. Hallucinated paths (not in either set) are rejected for
                 // all actions, including VERIFY and IGNORE, to keep the report consistent
                 // with what was actually discovered.
-                const isSkyramp = skyrampTestFiles.has(resolvedFile) || skyrampTestFiles.has(rec.testFilePath);
+                const isSkyramp = skyrampTestFiles.has(resolvedFile) ||
+                    skyrampTestFiles.has(rec.testFilePath);
                 // Catalog membership is the safety boundary — prevents editing non-test files.
-                const isRelevantExternal = (externalTestFiles.has(resolvedFile) || externalTestFiles.has(rec.testFilePath));
+                const isRelevantExternal = externalTestFiles.has(resolvedFile) ||
+                    externalTestFiles.has(rec.testFilePath);
                 const isInAnyKnownCatalog = isSkyramp || isRelevantExternal;
                 // Discovery is relevance-scoped, not exhaustive — it can miss a real test file the
                 // agent correctly identifies from the diff (e.g. an e2e Playwright spec/POM under a
@@ -234,7 +260,9 @@ export function registerActionsTool(server) {
                 // this preserves the anti-hallucination guarantee (an invented path fails existsSync).
                 const isRealUncatalogedTest = !isInAnyKnownCatalog &&
                     isTestFile(resolvedFile) &&
-                    (!repoRoot || resolvedFile.startsWith(repoRoot + path.sep) || resolvedFile === repoRoot) &&
+                    (!repoRoot ||
+                        resolvedFile.startsWith(repoRoot + path.sep) ||
+                        resolvedFile === repoRoot) &&
                     fs.existsSync(resolvedFile);
                 if (!isInAnyKnownCatalog && !isRealUncatalogedTest) {
                     logger.warning(`Skipping ${rec.action} for unknown test (not in scanned catalog, not a real test file): ${rec.testFilePath}`);
@@ -243,7 +271,11 @@ export function registerActionsTool(server) {
                 if (isRealUncatalogedTest) {
                     logger.info(`Accepting uncataloged but real test file discovery missed: ${rec.testFilePath}`);
                 }
-                const isActionable = [DriftAction.Update, DriftAction.Regenerate, DriftAction.Delete].includes(rec.action);
+                const isActionable = [
+                    DriftAction.Update,
+                    DriftAction.Regenerate,
+                    DriftAction.Delete,
+                ].includes(rec.action);
                 // No write access to a related repo's checkout — convert any edit-requiring
                 // action to VERIFY so the finding still surfaces without attempting a write that
                 // would fail (or land in a checkout that shouldn't be touched at all).
@@ -261,7 +293,10 @@ export function registerActionsTool(server) {
                     });
                     return;
                 }
-                if (isActionable && !isSkyramp && !isRelevantExternal && !isRealUncatalogedTest) {
+                if (isActionable &&
+                    !isSkyramp &&
+                    !isRelevantExternal &&
+                    !isRealUncatalogedTest) {
                     logger.warning(`Skipping ${rec.action} for irrelevant external test: ${rec.testFilePath}`);
                     return;
                 }
@@ -272,8 +307,10 @@ export function registerActionsTool(server) {
                 // report renders it as a deletion/regeneration RECOMMENDATION the developer applies
                 // manually. `reportOnly: true` makes the apply loops below skip it (B2 — a flattened
                 // VERIFY read to the D2 judge as "uncertain", hiding a correct DELETE call).
-                if (isExternalTarget && !isSkyramp &&
-                    (rec.action === DriftAction.Regenerate || rec.action === DriftAction.Delete)) {
+                if (isExternalTarget &&
+                    !isSkyramp &&
+                    (rec.action === DriftAction.Regenerate ||
+                        rec.action === DriftAction.Delete)) {
                     recommendations.push({
                         testFilePath: resolvedFile,
                         action: rec.action,
@@ -306,7 +343,8 @@ export function registerActionsTool(server) {
                         resolvedPomFile = undefined;
                     }
                 }
-                if (rec.action !== DriftAction.Update && rec.rebaselineSnapshots?.length) {
+                if (rec.action !== DriftAction.Update &&
+                    rec.rebaselineSnapshots?.length) {
                     droppedRebaselineNotes.push(`${rec.testFilePath}: rebaselineSnapshots [${rec.rebaselineSnapshots.join(", ")}] ignored on ${rec.action} — a baseline refresh is only meaningful on UPDATE.`);
                 }
                 // Per-entry validation (the schema is deliberately loose, see above).
@@ -350,7 +388,12 @@ export function registerActionsTool(server) {
                     testFilePath: resolvedFile,
                     pomFile: resolvedPomFile,
                     action: actionForVerdict,
-                    testType: rec.testType,
+                    // The catalog's type wins over the caller's claim, and it wins ONCE, here:
+                    // the verdict the report row is built from, the reuse hand-off, the steps
+                    // and the regenerate context all read this one value. Letting the row keep
+                    // a mislabeled type while the hand-off carried the cataloged one made the
+                    // report drop the row's reuse on the mismatch.
+                    testType: catalogByFile.get(resolvedFile)?.testType ?? rec.testType,
                     endpoint: rec.endpoint,
                     priority: rec.priority ?? RecommendationPriority.Medium,
                     rationale: rationaleForVerdict,
@@ -384,6 +427,52 @@ export function registerActionsTool(server) {
             // `maintenanceVerdicts` (the validated recommendations), persisted below at
             // decision-time — that persistence is what prevents a decided-upon entry from silently
             // vanishing at report time; the ignored set is a complete, accurate record for free.
+            // The renamed path has to be known BEFORE the verdicts are persisted.
+            // The rename itself happens further down, and the report looks for the
+            // file's run under the name the file ends up with; persisted with the
+            // old name, a moved spec is not found on disk and drops out of
+            // execution coverage without a word.
+            //
+            // Always derived from the spec (testFilePath), never the POM
+            // (editTarget): fileRenames keys off testFilePath, so the spec is what
+            // moves, and deriving from editTarget when pomFile is set would produce
+            // a name built from the page-object path.
+            for (const r of recommendations) {
+                if (!r.renamedEndpoints?.length)
+                    continue;
+                const renamed = computeRenamedTestFile(r.testFilePath, r.renamedEndpoints) ??
+                    undefined;
+                if (renamed)
+                    r._suggestedNewFile = renamed;
+            }
+            // ── Before-run gate on the tests this call will edit ──────────────
+            // Drift on the repository's own test must rest on a run, not on a
+            // reading of its source: without the pre-edit result the report cannot
+            // say what the edit changed, and the test lands at afterStatus=Unknown.
+            // The subject is what this call edits, and nothing wider: the gate used
+            // to sit in skyramp_analyze_test_health and demand a run for every
+            // external test in state, which is the first hundred files discovery
+            // found in glob order.
+            //
+            // A DELETE or a REGENERATE on an external test is report-only (the run
+            // edits nothing), and a related repo's entry is already a VERIFY by
+            // here, so neither owes a run.
+            const { owed, exemptLanguage } = testsOwedBeforeRun(recommendations, catalogByFile);
+            if (exemptLanguage > 0) {
+                logger.info(`Before-run gate: ${exemptLanguage} recommended external test(s) owe no run — skyramp_execute_test cannot run their language.`);
+            }
+            // A plan-only run has no application to run the tests against.
+            if (owed.length > 0 && !isPlanOnlyMode()) {
+                const filesList = formatOwedFiles(owed);
+                errorResult = toolError(`${owed.length} test${owed.length === 1 ? "" : "s"} you recommend editing ${owed.length === 1 ? "has" : "have"} no phase: "before" result recorded — never run, or a run was started and recorded no result: ${filesList}. ` +
+                    `Run each file through skyramp_execute_test with phase: "before", stateFile: "${args.stateFile}"${args.repository ? `, repository: "${args.repository}"` : ""}: ${runTestCall()}. Then call ${TOOL_NAME} again. Nothing was recorded by this call.`);
+                return errorResult;
+            }
+            else if (owed.length > 0) {
+                // planOnlyMode is process-global and captured at prompt-render time, so
+                // a skip must be visible: no run means no evidence behind these edits.
+                logger.warning(`Before-run gate skipped in a plan-only run: ${owed.length} test(s) you recommend editing have no phase: "before" result recorded.`);
+            }
             const recommendedPaths = new Set(recommendations.map((r) => r.testFilePath));
             const ignoredTestFiles = testAnalysisResults
                 .map((t) => t.testFile)
@@ -392,7 +481,7 @@ export function registerActionsTool(server) {
             // Must fail loud — edits below apply regardless, so a swallowed failure here
             // would let edits ship with no testMaintenance in the final report.
             try {
-                await stateManager.writeRepoData({
+                await stateManager.updateRepoData({
                     ...stateData,
                     ignoredTestFiles,
                     maintenanceVerdicts: recommendations.map((r) => ({
@@ -408,13 +497,22 @@ export function registerActionsTool(server) {
                         // Persisted so the report-time working-tree check knows this UPDATE's
                         // change is the refreshed PNG, not the spec (SKYR-4298).
                         ...(r.rebaselineSnapshots?.length
-                            ? { rebaselineSnapshots: r.rebaselineSnapshots, rebaselineOnly: r.rebaselineOnly === true }
+                            ? {
+                                rebaselineSnapshots: r.rebaselineSnapshots,
+                                rebaselineOnly: r.rebaselineOnly === true,
+                            }
                             : {}),
                         // Persisted so maintenance coverage can tell a REGENERATE that rewrote a
                         // file from one that only advised the developer to: an external test's
                         // REGENERATE/DELETE keeps its real action and touches nothing, so without
                         // this the report credits a `maintains` claim no edit backs.
                         ...(r.reportOnly ? { reportOnly: true } : {}),
+                        // Persisted so the report stage can find the renamed file's run: the
+                        // rename lands before execution, so the run is recorded under this
+                        // path while testFilePath still holds the name it had before.
+                        ...(r._suggestedNewFile
+                            ? { _suggestedNewFile: r._suggestedNewFile }
+                            : {}),
                     })),
                 }, { repo: args.repository, repositoryPath, step: "actions" });
             }
@@ -445,13 +543,15 @@ export function registerActionsTool(server) {
                     continue;
                 if (rec.action === DriftAction.Delete) {
                     const existing = deleteByFile.get(rec.testFilePath);
-                    if (!existing || priorityRank[rec.priority] > priorityRank[existing.priority]) {
+                    if (!existing ||
+                        priorityRank[rec.priority] > priorityRank[existing.priority]) {
                         deleteByFile.set(rec.testFilePath, rec);
                     }
                 }
                 else if (rec.action === DriftAction.Regenerate) {
                     const existing = regenerateByFile.get(rec.testFilePath);
-                    if (!existing || priorityRank[rec.priority] > priorityRank[existing.priority]) {
+                    if (!existing ||
+                        priorityRank[rec.priority] > priorityRank[existing.priority]) {
                         regenerateByFile.set(rec.testFilePath, rec);
                     }
                 }
@@ -460,7 +560,8 @@ export function registerActionsTool(server) {
                     if (!regenerateByFile.has(rec.testFilePath)) {
                         const key = `${rec.testFilePath}::${rec.pomFile ?? ""}`;
                         const existing = updateByKey.get(key);
-                        if (!existing || priorityRank[rec.priority] > priorityRank[existing.priority]) {
+                        if (!existing ||
+                            priorityRank[rec.priority] > priorityRank[existing.priority]) {
                             updateByKey.set(key, rec);
                         }
                     }
@@ -489,6 +590,36 @@ export function registerActionsTool(server) {
             const testFilesToDelete = deleteRecommendations.map((rec) => rec.testFilePath);
             const fileInstructions = [];
             const testFilesToUpdate = [];
+            // A Skyramp test rewritten in place — updated or regenerated — owes the same
+            // modularize → reuse pair a generated one does, under the same predicate. The
+            // hand-off is recorded here, at the site that emits the instruction, as a
+            // maintenance hand-off: the file is at HEAD by definition, so the chain gate
+            // must not read that as "not this run's". An external test is the customer's
+            // code and is never modularized into the shared module. Returns the
+            // next-steps block for the file, or undefined when nothing was armed.
+            const armReuseChain = async (rec) => {
+                if (!skyrampTestFiles.has(rec.testFilePath))
+                    return undefined;
+                const cataloged = catalogByFile.get(rec.testFilePath);
+                const language = cataloged?.language;
+                // Already the cataloged type — normalized once where the recommendation
+                // was built, so the verdict, the hand-off and the steps cannot disagree.
+                const testType = rec.testType;
+                if (!language) {
+                    logger.info(`No language cataloged for ${rec.testFilePath} — not arming the modularize → reuse chain for this ${rec.action}`);
+                    return undefined;
+                }
+                if (!isModularizeFirstHandOffTarget(testType, language))
+                    return undefined;
+                const framework = cataloged?.framework ?? "";
+                await recordReuseHandOff([rec.testFilePath], testType, language, framework, args.stateFile, "maintenance");
+                return buildModularizeFirstNextSteps({
+                    testType,
+                    language,
+                    framework,
+                    enhanceFirst: false,
+                });
+            };
             // ── UPDATE: emit targeted edit instructions ──
             for (const rec of updateRecommendations) {
                 if (!rec.testFilePath) {
@@ -508,16 +639,33 @@ export function registerActionsTool(server) {
                     continue;
                 }
                 const renames = rec.renamedEndpoints || [];
-                const isRenameUpdate = renames.length > 0;
-                // Always derive the rename suggestion from the spec (testFilePath), not the
-                // POM (editTarget). fileRenames keys off rec.testFilePath so the spec is
-                // what gets renamed; computing from editTarget when pomFile is set
-                // would produce a name derived from the page-object path instead.
-                const suggestedNewFile = isRenameUpdate
-                    ? computeRenamedTestFile(rec.testFilePath, renames) ?? undefined
-                    : undefined;
-                if (suggestedNewFile)
-                    rec._suggestedNewFile = suggestedNewFile;
+                // Computed above, before the verdicts were persisted.
+                const suggestedNewFile = rec._suggestedNewFile;
+                // Armed only when this UPDATE rewrites the SPEC BODY, because that is the
+                // only edit the modularize → reuse pair has anything to act on.
+                //
+                // `pomFile` set means the edit lands somewhere the spec delegates its
+                // selectors to, and the spec body is left alone. That is a page object in
+                // the case the field was named for, but agents also use it for the SHARED
+                // MODULE when a stale selector lives in a helper — observed twice on the
+                // repo20-SR02 fixture, and correct by the field's own description. Either
+                // way the spec is not rewritten, so it owes nothing. Consequence worth
+                // knowing: a fixture cannot assume a maintained spec gets armed, since the
+                // agent may route the whole edit through this field (SKYR-4412).
+                //
+                // A rename UPDATE is a URL-path substitution and moves the file; the hand-off
+                // is keyed by the path the file has now, so after the move the gate and the
+                // report would look there and find nothing — a debt recorded where no one
+                // reads it. A rebaseline-only UPDATE edits no spec at all; its maintenance is
+                // the PNG refresh. A rationale-only UPDATE (no updateInstructions) has no
+                // update_context entry to carry post_edit_steps, so the structured plan could
+                // not pay the debt.
+                if (!rec.pomFile &&
+                    !suggestedNewFile &&
+                    !rec.rebaselineOnly &&
+                    rec.updateInstructions) {
+                    rec._postEditSteps = await armReuseChain(rec);
+                }
                 fileInstructions.push(buildUpdateFileInstruction({
                     testFile: editTarget,
                     renames,
@@ -525,6 +673,7 @@ export function registerActionsTool(server) {
                     updateInstructions: rec.updateInstructions,
                     rationale: rec.rationale,
                     rebaselineSnapshots: rec.rebaselineSnapshots,
+                    postEditSteps: rec._postEditSteps,
                 }));
             }
             // ── REGENERATE: emit overwrite instructions ──
@@ -536,11 +685,21 @@ export function registerActionsTool(server) {
                     continue;
                 }
                 testFilesToRegenerate.push(rec.testFilePath);
+                const cataloged = catalogByFile.get(rec.testFilePath);
+                // The generation call the instruction prescribes records its own hand-off for
+                // the file it writes; this maintenance mark is what that hand-off inherits its
+                // origin from, so the rewrite of a file at HEAD still owes the chain. Only for
+                // a type this step can actually regenerate (see isMaintenanceRegenerable).
+                if (isMaintenanceRegenerable(rec.testType)) {
+                    await armReuseChain(rec);
+                }
                 regenerateInstructions.push(buildRegenerateFileInstruction({
                     testFile: rec.testFilePath,
                     updateInstructions: rec.updateInstructions,
                     outputDir: path.dirname(rec.testFilePath),
                     outputFile: path.basename(rec.testFilePath),
+                    testType: rec.testType,
+                    language: cataloged?.language,
                 }));
             }
             // ── Build response text ──
@@ -556,7 +715,9 @@ export function registerActionsTool(server) {
             }
             if (regenerateRecommendations.length > 0) {
                 sections.push(`## Tests Requiring Regeneration (${regenerateRecommendations.length})\n\n` +
-                    testFilesToRegenerate.map((f, i) => `${i + 1}. \`${f}\``).join("\n") +
+                    testFilesToRegenerate
+                        .map((f, i) => `${i + 1}. \`${f}\``)
+                        .join("\n") +
                     `\n\n---\n` +
                     regenerateInstructions.join("\n---\n"));
             }
@@ -564,12 +725,16 @@ export function registerActionsTool(server) {
                 sections.push(`## Tests To Delete (${deleteRecommendations.length})\n\n` +
                     testFilesToDelete.map((f, i) => `${i + 1}. \`${f}\``).join("\n") +
                     `\n\n---\n` +
-                    deleteRecommendations.map((rec) => `- **${rec.testFilePath}**${rec.rationale ? ` — ${rec.rationale}` : ""}`).join("\n"));
+                    deleteRecommendations
+                        .map((rec) => `- **${rec.testFilePath}**${rec.rationale ? ` — ${rec.rationale}` : ""}`)
+                        .join("\n"));
             }
             if (otherRecs.length > 0) {
                 sections.push(`## Other Findings (${otherRecs.length})\n\n` +
-                    otherRecs.map((rec) => `- **${rec.testFilePath}** — Action: ${rec.action}, Priority: ${rec.priority}` +
-                        (rec.rationale ? ` — ${rec.rationale}` : "")).join("\n"));
+                    otherRecs
+                        .map((rec) => `- **${rec.testFilePath}** — Action: ${rec.action}, Priority: ${rec.priority}` +
+                        (rec.rationale ? ` — ${rec.rationale}` : ""))
+                        .join("\n"));
             }
             else if (updateRecommendations.length === 0 &&
                 regenerateRecommendations.length === 0 &&
@@ -585,7 +750,9 @@ export function registerActionsTool(server) {
             // ── Build LLM instructions ──
             const uniqueRenames = updateRecommendations
                 .flatMap((rec) => rec.renamedEndpoints ?? [])
-                .filter((r, i, arr) => arr.findIndex((x) => x.oldPath === r.oldPath && x.newPath === r.newPath && x.method === r.method) === i);
+                .filter((r, i, arr) => arr.findIndex((x) => x.oldPath === r.oldPath &&
+                x.newPath === r.newPath &&
+                x.method === r.method) === i);
             const llmInstructionsObj = {
                 workflow: "test_maintenance",
                 action: "execute_updates",
@@ -603,7 +770,10 @@ export function registerActionsTool(server) {
                 const fileRenames = [];
                 for (const rec of updateRecommendations) {
                     if (rec._suggestedNewFile) {
-                        fileRenames.push({ from: rec.testFilePath, to: rec._suggestedNewFile });
+                        fileRenames.push({
+                            from: rec.testFilePath,
+                            to: rec._suggestedNewFile,
+                        });
                     }
                 }
                 if (fileRenames.length > 0) {
@@ -624,19 +794,29 @@ export function registerActionsTool(server) {
                     // explicit edit_required: false so the strategy's "make the changes
                     // described in context" cannot apply to it (rationale is always set,
                     // so it must not stand in for edit instructions here).
-                    ...(hasEdit ? { context: rec.updateInstructions } : { edit_required: false }),
+                    ...(hasEdit
+                        ? { context: rec.updateInstructions }
+                        : { edit_required: false }),
                     ...(rec.editSites?.length ? { edit_sites: rec.editSites } : {}),
                     // The baselines to pass as skyramp_execute_test's rebaselineSnapshots for
                     // the SPEC (testFilePath, which is what runs) — never `file`, which is
                     // the page object for a POM-backed UPDATE.
                     ...(rec.rebaselineSnapshots?.length
-                        ? { spec_file: rec.testFilePath, rebaseline_snapshots: rec.rebaselineSnapshots }
+                        ? {
+                            spec_file: rec.testFilePath,
+                            rebaseline_snapshots: rec.rebaselineSnapshots,
+                        }
+                        : {}),
+                    // The modularize → reuse steps the file owes, on the entry the agent
+                    // follows (the summary block above is the same text for a reader).
+                    ...(rec._postEditSteps
+                        ? { post_edit_steps: rec._postEditSteps }
                         : {}),
                 };
             });
             if (updateContext.length > 0) {
                 llmInstructionsObj.update_context = updateContext;
-                llmInstructionsObj.update_strategy = buildUpdateStrategy();
+                llmInstructionsObj.update_strategy = buildUpdateStrategy(updateContext.some((u) => "post_edit_steps" in u));
                 if (updateContext.some((u) => "rebaseline_snapshots" in u)) {
                     llmInstructionsObj.rebaseline_strategy = buildRebaselineStrategy();
                 }
@@ -649,6 +829,7 @@ export function registerActionsTool(server) {
                     // replicate the file. Those come from the discovery catalog, so the file
                     // text is not needed to carry them.
                     const cataloged = catalogByFile.get(rec.testFilePath);
+                    const generationArgs = regenerateCodeReuse(rec.testType, cataloged?.language)?.args;
                     return {
                         file: rec.testFilePath,
                         rationale: rec.updateInstructions || rec.rationale,
@@ -656,13 +837,17 @@ export function registerActionsTool(server) {
                         // use them instead of reading the file, so an absent one leaves the generation
                         // call without a target. The catalog's apiEndpoint is optional and can be an
                         // empty string; both fields are required on the recommendation itself.
-                        test_type: cataloged?.testType ?? rec.testType,
+                        test_type: rec.testType,
                         endpoint: cataloged?.apiEndpoint || rec.endpoint,
                         ...(cataloged?.language && { language: cataloged.language }),
                         ...(cataloged?.framework && { framework: cataloged.framework }),
+                        // The codeReuse options the per-file instruction asks for, on the entry
+                        // the agent follows, so a client that reads only the structured plan
+                        // still arms the chain the maintenance hand-off recorded.
+                        ...(generationArgs && { generation_args: generationArgs }),
                     };
                 });
-                llmInstructionsObj.regenerate_strategy = buildRegenerateStrategy();
+                llmInstructionsObj.regenerate_strategy = buildRegenerateStrategy(llmInstructionsObj.regenerate_context.some((e) => !!e.generation_args));
             }
             if (deleteRecommendations.length > 0) {
                 llmInstructionsObj.delete_strategy = buildDeleteStrategy();
@@ -671,7 +856,10 @@ export function registerActionsTool(server) {
             // The two payloads were previously separate content[] blocks annotated
             // audience: ["user"] and ["assistant"]. Nothing in this repo read those
             // annotations, and the field names carry the same distinction.
-            return dualChannelResult({ summary: responseText, instructions: llmInstructions });
+            return dualChannelResult({
+                summary: responseText,
+                instructions: llmInstructions,
+            });
         }
         catch (error) {
             logger.error(`Actions tool failed: ${error.message}`, error);
@@ -689,7 +877,9 @@ export function registerActionsTool(server) {
             }
             AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
                 repositoryPath,
-            }).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            }).catch((err) => {
+                logger.warning("Analytics event failed", { error: String(err) });
+            });
         }
     });
 }

package/build/tools/test-management/analyzeChangesTool.d.ts

@@ -11,12 +11,11 @@ export declare function buildTraceFileEntry(tracePath: string, result: TracePars
 export declare function isGraphQLFile(filePath: string, repositoryPath: string): Promise<boolean>;
 export declare const analyzeChangesInputSchema: {
     repositoryPath: z.ZodString;
+    repository: z.ZodString;
     scope: z.ZodOptional<z.ZodDefault<z.ZodEnum<["full_repo", "branch_diff"]>>>;
     baseBranch: z.ZodOptional<z.ZodString>;
     testDirectory: z.ZodOptional<z.ZodString>;
     prNumber: z.ZodOptional<z.ZodNumber>;
-    repository: z.ZodOptional<z.ZodString>;
-    primaryRepository: z.ZodOptional<z.ZodString>;
     testsRepoDir: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     includeUncommitted: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 };
@@ -31,8 +30,8 @@ export interface AnalyzeChangesData {
     stateFile?: string;
     repositoryPath: string;
     repositoryName: string;
-    /** owner/repo, when the caller supplied it. */
-    repository?: string;
+    /** owner/repo of the analyzed repository. Always supplied. */
+    repository: string;
     /** Other repositories already analyzed into this run's state file. */
     relatedRepositories?: string[];
     analysisScope: string;
@@ -86,7 +85,7 @@ export declare const analyzeChangesOutputSchema: {
     stateFile: z.ZodOptional<z.ZodString>;
     repositoryPath: z.ZodString;
     repositoryName: z.ZodString;
-    repository: z.ZodOptional<z.ZodString>;
+    repository: z.ZodString;
     relatedRepositories: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     analysisScope: z.ZodString;
     planOnly: z.ZodBoolean;
@@ -132,8 +131,8 @@ export declare const analyzeChangesOutputSchema: {
             analysedWorkspaceFile: z.ZodString;
         }, "strip", z.ZodTypeAny, {
             message: string;
-            kind: "workspace-disagreement";
             serviceName: string;
+            kind: "workspace-disagreement";
             field: "authHeader" | "authScheme" | "authType";
             primaryWorkspaceFile: string;
             analysedWorkspaceFile: string;
@@ -141,8 +140,8 @@ export declare const analyzeChangesOutputSchema: {
             analysed: string;
         }, {
             message: string;
-            kind: "workspace-disagreement";
             serviceName: string;
+            kind: "workspace-disagreement";
             field: "authHeader" | "authScheme" | "authType";
             primaryWorkspaceFile: string;
             analysedWorkspaceFile: string;
@@ -157,8 +156,8 @@ export declare const analyzeChangesOutputSchema: {
         openApiSpecPath?: string | undefined;
         authFindings?: {
             message: string;
-            kind: "workspace-disagreement";
             serviceName: string;
+            kind: "workspace-disagreement";
             field: "authHeader" | "authScheme" | "authType";
             primaryWorkspaceFile: string;
             analysedWorkspaceFile: string;
@@ -173,8 +172,8 @@ export declare const analyzeChangesOutputSchema: {
         openApiSpecPath?: string | undefined;
         authFindings?: {
             message: string;
-            kind: "workspace-disagreement";
             serviceName: string;
+            kind: "workspace-disagreement";
             field: "authHeader" | "authScheme" | "authType";
             primaryWorkspaceFile: string;
             analysedWorkspaceFile: string;