@skyramp/mcp 0.2.7 → 0.2.8-rc.1

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

@@ -8,7 +8,7 @@ import { simpleGit } from "simple-git";
 import { logger } from "../../utils/logger.js";
 import { parseWorkspaceAuthType, getDefaultAuthHeader, WorkspaceAuthType, readWorkspaceConfigRaw } from "../../utils/workspaceAuth.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
-import { StateManager, registerSession, storeSessionData, setTestsRepoDir, } from "../../utils/AnalysisStateManager.js";
+import { StateManager, registerSession, storeSessionData, setTestsRepoDir, getActiveRunStatePath, setActiveRunStatePath, } from "../../utils/AnalysisStateManager.js";
 import { buildRecommendationPrompt } from "../../prompts/test-recommendation/test-recommendation-prompt.js";
 import { hasFlutterSdkDep, isFrontendFile, isTestFile } from "../../prompts/test-recommendation/scopeAssessment.js";
 import { enumerateCandidateUiPages } from "../../utils/uiPageEnumerator.js";
@@ -24,6 +24,32 @@ import { buildAnalysisOutputText } from "../../prompts/test-recommendation/analy
 import { parseTraceFile, discoverTraceFiles, discoverPlaywrightZips, } from "../../utils/trace-parser.js";
 import { TestSource } from "../../types/TestAnalysis.js";
 import { parsePRComments } from "../../utils/pr-comment-parser.js";
+// Generic module names that appear as imports in virtually every router file.
+// Matching against these would extract ALL prefix= tokens from mount files,
+// flooding changedResources with unrelated resources.
+const GENERIC_MODULE_NAMES = new Set([
+    "models", "utils", "helpers", "schemas", "types", "constants",
+    "config", "settings", "exceptions", "errors", "base", "common",
+    "app", "main", "index", "server", "init", "deps", "dependencies",
+]);
+function resolveMountPrefixTokens(mountFileContents, changedFiles) {
+    const tokens = changedFiles.flatMap((file) => {
+        const mod = path.basename(file).replace(/\.[^.]+$/, "").toLowerCase();
+        if (GENERIC_MODULE_NAMES.has(mod))
+            return [];
+        const modRe = new RegExp(`\\b${mod.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+        return mountFileContents.flatMap((content) => {
+            if (!modRe.test(content.toLowerCase()))
+                return [];
+            const matches = [...content.matchAll(/prefix\s*=\s*["'](\/?[^"']+)/g)];
+            return matches.flatMap((m) => {
+                const token = extractResourceFromPath(m[1]);
+                return token !== "unknown" ? [token] : [];
+            });
+        });
+    });
+    return [...new Set(tokens)];
+}
 /** Exported for testing: maps a parsed trace result to a TraceFile. */
 export function buildTraceFileEntry(tracePath, result) {
     return {
@@ -339,11 +365,10 @@ export const analyzeChangesInputSchema = {
         .number()
         .optional()
         .describe("GitHub PR number. When provided, fetches previous TestBot comments on this PR and skips re-recommending tests already suggested in earlier commits — reduces duplicate recommendations across multiple pushes to the same PR."),
-    stateOutputFile: z
+    repository: z
         .string()
-        .refine((v) => path.isAbsolute(v), { message: "stateOutputFile must be an absolute path" })
         .optional()
-        .describe("Absolute path where the state file should be written. When provided, overrides the default auto-generated temp path so the caller can locate it without log parsing."),
+        .describe("The owner/repo this call analyzes (e.g. 'letsramp/api-insight'). In a multi-repo run, ALWAYS set it — for the primary AND every related repo. All calls in one Testbot run share ONE state file automatically (you do NOT pass a file path); each repo's analysis is stored as its own section within it. The primary's analysis is kept at the root and tagged with its owner/repo; related repos are stored as keyed sections. Omit only for a single-repo run."),
     testsRepoDir: z
         .string()
         .refine((v) => path.isAbsolute(v), { message: "testsRepoDir must be an absolute path" })
@@ -568,6 +593,30 @@ export function registerAnalyzeChangesTool(server) {
             // testsRepoDir is a cross-repo path override — honour it when set.
             // Otherwise always scan the full repo root.
             const testDir = params.testsRepoDir ?? undefined;
+            const routerMountContext = grepRouterMountingContext(params.repositoryPath);
+            // Read contents once — used for token extraction and LLM prompt injection.
+            const ROUTER_INLINE_LIMIT = 4096;
+            const routerMountContextContents = routerMountContext.map((f) => {
+                try {
+                    const abs = path.isAbsolute(f) ? f : path.join(params.repositoryPath, f);
+                    if (fs.statSync(abs).size > ROUTER_INLINE_LIMIT * 10)
+                        return ""; // skip very large files
+                    return fs.readFileSync(abs, "utf-8");
+                }
+                catch {
+                    return "";
+                }
+            });
+            // Size-capped subset for LLM prompt injection.
+            const ROUTER_INLINE_MAX_FILES = 3;
+            const routerFileContents = routerMountContext
+                .slice(0, ROUTER_INLINE_MAX_FILES)
+                .flatMap((f, i) => {
+                const content = routerMountContextContents[i] ?? "";
+                if (!content || content.length > ROUTER_INLINE_LIMIT)
+                    return [];
+                return [{ file: f, content: content.trimEnd() }];
+            });
             // Compute changedResources from classified endpoints for test discovery filtering.
             // undefined    → full-repo mode (no diff context)
             // []           → PR mode, no endpoints found → skip external tests
@@ -596,14 +645,22 @@ export function registerAnalyzeChangesTool(server) {
                     }
                     else {
                         // All endpoints resolved to "unknown" (e.g. NestJS relative paths) —
-                        // extract resource names from changed file paths instead.
-                        const candidateFiles = classifiedEndpoints.unmatchedFiles.length > 0
-                            ? classifiedEndpoints.unmatchedFiles
-                            : classifiedEndpoints.changedFiles ?? [];
-                        const fromFiles = candidateFiles
-                            .map((f) => extractResourceFromPath(f.replace(/\.[^./]+$/, "").replace(FRAMEWORK_SUFFIX_RE, "")))
-                            .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
-                        changedResources = fromFiles.length > 0 ? fromFiles : ["unknown"];
+                        // first try to extract resource names from router mount prefixes.
+                        const changedSourceFiles = classifiedEndpoints.changedFiles ?? [];
+                        const mountedResources = resolveMountPrefixTokens(routerMountContextContents, changedSourceFiles);
+                        if (mountedResources.length > 0) {
+                            changedResources = mountedResources;
+                        }
+                        else {
+                            // Fall back to extracting resource names from changed file paths.
+                            const candidateFiles = classifiedEndpoints.unmatchedFiles.length > 0
+                                ? classifiedEndpoints.unmatchedFiles
+                                : classifiedEndpoints.changedFiles ?? [];
+                            const fromFiles = candidateFiles
+                                .map((f) => extractResourceFromPath(f.replace(/\.[^./]+$/, "").replace(FRAMEWORK_SUFFIX_RE, "")))
+                                .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
+                            changedResources = fromFiles.length > 0 ? fromFiles : ["unknown"];
+                        }
                     }
                 }
                 else if (classifiedEndpoints.unmatchedFiles.length > 0) {
@@ -622,7 +679,15 @@ export function registerAnalyzeChangesTool(server) {
                     changedResources = fromFiles.length > 0 ? fromFiles : ["unknown"];
                 }
                 else {
-                    changedResources = [];
+                    // No endpoints and no unmatched files — the diff touches only non-route
+                    // files (e.g. schema, model, DTO). Extract resource tokens from the
+                    // changed file paths so tests that import the changed symbol are still
+                    // surfaced for drift assessment. Fall back to [] only if extraction
+                    // yields nothing (e.g. a file with a non-resource name like utils.py).
+                    const fromChangedFiles = (classifiedEndpoints.changedFiles ?? [])
+                        .map((f) => extractResourceFromPath(f.replace(/\.[^./]+$/, "").replace(FRAMEWORK_SUFFIX_RE, "")))
+                        .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
+                    changedResources = fromChangedFiles.length > 0 ? fromChangedFiles : [];
                 }
             }
             let existingTests = [];
@@ -903,10 +968,15 @@ export function registerAnalyzeChangesTool(server) {
                         sourceFile: m.sourceFile ?? "",
                     })))
                     : [];
+            const removedEndpointsForDrafting = classifiedEndpoints?.removedEndpoints.flatMap((ep) => ep.methods.map((m) => ({
+                method: m,
+                path: ep.path,
+                sourceFile: ep.sourceFile,
+            }))) ?? [];
             const codeInferredScenarios = draftScenariosFromEndpoints(skeletonEndpoints, scenarioDraftSeed, wsAuthType, {
                 changedEndpoints: changedEndpointsForSecurityExpansion,
                 securityRelevantDiff,
-            });
+            }, removedEndpointsForDrafting);
             let allDraftedScenarios = codeInferredScenarios;
             if (traceResult && traceResult.userFlows.length > 0) {
                 const traceScenarios = traceResult.userFlows
@@ -1109,7 +1179,6 @@ export function registerAnalyzeChangesTool(server) {
             // can be persisted to the state file for downstream tools (health, drift).
             // Without them, analyzeTestHealth would work only off the static catalog
             // which has wrong paths for nested resources and unsupported frameworks.
-            const routerMountContext = grepRouterMountingContext(params.repositoryPath);
             const routeLikeUnmatchedFiles = [];
             for (const file of classifiedEndpoints?.unmatchedFiles ?? []) {
                 const routeLike = SOURCE_EXTS.test(file) &&
@@ -1138,25 +1207,6 @@ export function registerAnalyzeChangesTool(server) {
                 diffFilePath = path.join(os.tmpdir(), `skyramp-diff-${sessionId}.diff`);
                 await fs.promises.writeFile(diffFilePath, diffData.diffContent, { encoding: "utf-8", mode: 0o600 });
             }
-            // Read router mount files server-side (size-capped) so the LLM has them
-            // inline and doesn't need an extra read step when no spec is available.
-            const ROUTER_INLINE_LIMIT = 4096; // bytes — skip files larger than ~4 KB
-            const ROUTER_INLINE_MAX_FILES = 3;
-            const routerFileContents = routerMountContext
-                .slice(0, ROUTER_INLINE_MAX_FILES)
-                .flatMap((f) => {
-                try {
-                    const absPath = path.isAbsolute(f) ? f : path.join(params.repositoryPath, f);
-                    const stat = fs.statSync(absPath);
-                    if (stat.size > ROUTER_INLINE_LIMIT)
-                        return [];
-                    const content = fs.readFileSync(absPath, "utf-8").trimEnd();
-                    return [{ file: f, content }];
-                }
-                catch {
-                    return [];
-                }
-            });
             // Compute UI context from the diff's changed files using the shared
             // `isFrontendFile` classifier. Persisting this in the stateFile lets
             // skyramp_analyze_test_health and the recommendation prompt consume the
@@ -1252,22 +1302,37 @@ export function registerAnalyzeChangesTool(server) {
                     relevantExternalTestPaths,
                 },
             };
-            // Clean up old state files (>24 hours) before creating new one
-            const stateDir = params.stateOutputFile
-                ? path.dirname(path.resolve(params.stateOutputFile))
-                : undefined;
+            // Clean up old state files (>24 hours) before creating new one.
             try {
-                await StateManager.cleanupOldFiles(24, stateDir);
+                await StateManager.cleanupOldFiles(24);
             }
             catch (error) {
                 logger.warning(`Failed to cleanup old state files: ${error.message}`);
             }
-            const stateManager = new StateManager("analysis", sessionId, undefined, params.stateOutputFile);
-            await stateManager.writeData(unifiedState, {
+            // Resolve the state file. Multi-repo (`repository` set): all calls in one
+            // Testbot run share ONE state file — the first call creates it and records
+            // the run anchor; later related-repo calls reuse it (no agent-provided path,
+            // which previously caused filename hallucinations). Single-repo (`repository`
+            // absent): always a fresh per-call file — byte-identical to prior behavior.
+            const activeRunPath = params.repository
+                ? getActiveRunStatePath()
+                : undefined;
+            const stateManager = activeRunPath
+                ? StateManager.fromStatePath(activeRunPath)
+                : new StateManager("analysis", sessionId);
+            // `repository` identifies which repo this analysis belongs to. The primary
+            // (first write of the run, or matching the root's recorded repository) is
+            // stored at the root; a related repo is stored as a keyed section within the
+            // same run-scoped stateFile.
+            await stateManager.writeRepoData(unifiedState, {
+                repo: params.repository,
                 repositoryPath: params.repositoryPath,
                 step: "analyze_changes",
             });
             const stateFile = stateManager.getStatePath();
+            // Anchor the run's state file so subsequent related-repo calls reuse it.
+            if (params.repository)
+                setActiveRunStatePath(stateFile);
             registerSession(sessionId, stateFile);
             try {
                 await server.server.sendResourceListChanged();

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

@@ -49,14 +49,24 @@ jest.unstable_mockModule("../../utils/trace-parser.js", () => ({
 jest.unstable_mockModule("../../utils/pr-comment-parser.js", () => ({
     parsePRComments: jest.fn(),
 }));
-jest.unstable_mockModule("../../utils/AnalysisStateManager.js", () => ({
-    StateManager: jest.fn().mockImplementation(() => ({
+jest.unstable_mockModule("../../utils/AnalysisStateManager.js", () => {
+    const makeInstance = () => ({
         writeData: jest.fn(),
-    })),
-    registerSession: jest.fn(),
-    storeSessionData: jest.fn(),
-    setTestsRepoDir: jest.fn(),
-}));
+        writeRepoData: jest.fn(),
+        getStatePath: jest.fn().mockReturnValue("/tmp/skyramp/analysis-state.json"),
+    });
+    const StateManager = jest.fn().mockImplementation(makeInstance);
+    StateManager.fromStatePath = jest.fn().mockImplementation(makeInstance);
+    return {
+        StateManager,
+        registerSession: jest.fn(),
+        storeSessionData: jest.fn(),
+        setTestsRepoDir: jest.fn(),
+        getActiveRunStatePath: jest.fn(),
+        setActiveRunStatePath: jest.fn(),
+        clearActiveRunStatePath: jest.fn(),
+    };
+});
 // Keep every real workspaceAuth export the subject's import graph needs
 // (readWorkspaceConfigRaw, getDefaultAuthHeader, WorkspaceAuthType, …) and
 // override only parseWorkspaceAuthType. requireActual can't load ESM
@@ -99,28 +109,6 @@ describe("isSecurityRelevantDiff", () => {
         expect(isSecurityRelevantDiff("move compression middleware to server setup")).toBe(false);
     });
 });
-describe("analyzeChangesInputSchema — stateOutputFile validation", () => {
-    it("accepts a valid absolute path", () => {
-        const result = schema.safeParse({
-            repositoryPath: "/repo",
-            stateOutputFile: "/tmp/analyze-changes-state.json",
-        });
-        expect(result.success).toBe(true);
-    });
-    it("rejects a relative path for stateOutputFile", () => {
-        // stateOutputFile must be absolute so the caller can guarantee the file location.
-        // Relative paths are silently ambiguous and should be rejected.
-        const result = schema.safeParse({
-            repositoryPath: "/repo",
-            stateOutputFile: "relative/path/state.json",
-        });
-        expect(result.success).toBe(false);
-    });
-    it("accepts absence of stateOutputFile (optional field)", () => {
-        const result = schema.safeParse({ repositoryPath: "/repo" });
-        expect(result.success).toBe(true);
-    });
-});
 describe("automatic old files cleanup", () => {
     let cleanupOldFilesSpy;
     beforeEach(() => {
@@ -128,31 +116,23 @@ describe("automatic old files cleanup", () => {
         cleanupOldFilesSpy = jest.fn().mockResolvedValue(0);
         StateManager.cleanupOldFiles = cleanupOldFilesSpy;
     });
-    it("calls cleanupOldFiles with default temp dir when no stateOutputFile provided", async () => {
-        // This test verifies the cleanup call is made without stateDir when using default location
+    it("calls cleanupOldFiles with default temp dir", async () => {
         expect(StateManager.cleanupOldFiles).toBeDefined();
         await StateManager.cleanupOldFiles(24, undefined);
         expect(cleanupOldFilesSpy).toHaveBeenCalledWith(24, undefined);
     });
-    it("calls cleanupOldFiles with custom dir when stateOutputFile is provided", async () => {
-        // This test verifies the cleanup call is made with the directory of stateOutputFile
+    it("calls cleanupOldFiles with custom dir", async () => {
         const customPath = "/custom/dir";
         await StateManager.cleanupOldFiles(24, customPath);
         expect(cleanupOldFilesSpy).toHaveBeenCalledWith(24, customPath);
     });
-    it("calls cleanupOldFiles with empty stateTypes to restrict to diff files only", async () => {
-        // analyzeTestHealthTool passes [] so state files (skyramp-analysis-*, skyramp-recommendation-*)
-        // are never deleted — the caller still needs args.stateFile for skyramp_actions.
+    it("calls cleanupOldFiles with empty stateTypes", async () => {
         await StateManager.cleanupOldFiles(24, undefined, []);
         expect(cleanupOldFilesSpy).toHaveBeenCalledWith(24, undefined, []);
     });
     it("continues execution if cleanup fails", async () => {
-        // Cleanup failures should not crash the analyze flow
         cleanupOldFilesSpy.mockRejectedValue(new Error("permission denied"));
-        await expect(StateManager.cleanupOldFiles(24).catch(() => {
-            // In the real code, this is caught and logged as a warning
-            return Promise.resolve();
-        })).resolves.toBeUndefined();
+        await expect(StateManager.cleanupOldFiles(24).catch(() => Promise.resolve())).resolves.toBeUndefined();
     });
 });
 // ─────────────────────────────────────────────────────────────────────────────

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

@@ -15,11 +15,15 @@ export function registerAnalyzeTestHealthTool(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: `Generate drift assessment instructions for existing tests — second step of the unified Test Health Analysis Flow. Optionally execute tests with skyramp_execute_test before calling skyramp_actions to capture beforeStatus.`,
+        description: `Generate drift assessment instructions for existing tests — second step of the unified Test Health Analysis Flow.`,
         inputSchema: {
             stateFile: z
                 .string()
-                .describe("Path to state file from skyramp_analyze_changes. Assessment results exist only in the LLM's reasoning context — this tool does not write back to the stateFile."),
+                .describe("Path to the analyze-changes-state.json file returned by skyramp_analyze_changes (the stateFile field in its output). Do NOT pass summaryOutputFile or testbot-result.txt here."),
+            repository: z
+                .string()
+                .optional()
+                .describe("The owner/repo whose analysis section to assess (e.g. 'letsramp/api-insight'). In a multi-repo run, ALWAYS set it — the primary's owner/repo for the primary repo, or a related repo's owner/repo for that repo's section within the run-scoped stateFile. Omit only for a single-repo run."),
         },
         outputSchema: {
             prompt: z.string().describe("LLM drift analysis prompt and assessment instructions."),
@@ -27,17 +31,20 @@ export function registerAnalyzeTestHealthTool(server) {
     }, async (args) => {
         let errorResult;
         try {
-            logger.info(`Analyzing test health from state file: ${args.stateFile}`);
-            // Load UnifiedAnalysisState from state file
+            logger.info(`Analyzing test health from state file: ${args.stateFile}${args.repository ? ` (repository: ${args.repository})` : ""}`);
+            // Load UnifiedAnalysisState for the requested repo section (primary when
+            // repository omitted/matches the root) from the run-scoped state file.
             const stateManager = StateManager.fromStatePath(args.stateFile);
-            const stateData = await stateManager.readData();
-            const fullState = await stateManager.readFullState();
-            const repositoryPath = fullState?.metadata.repositoryPath || "";
+            const stateData = await stateManager.readRepoData(args.repository);
+            const repositoryPath = (await stateManager.getRepoRepositoryPath(args.repository)) || "";
             if (!stateData) {
-                return toolError(`State file is empty or invalid: ${args.stateFile}. Call skyramp_analyze_changes first to generate a valid state file.`);
+                return toolError(`State file is empty or invalid: ${args.stateFile}${args.repository ? ` (no section for repository ${args.repository})` : ""}. Call skyramp_analyze_changes first to generate a valid state file.`);
             }
             if (!repositoryPath || typeof repositoryPath !== "string") {
-                return toolError(`repositoryPath not found in state file metadata. The state file was likely created by an older version — re-run skyramp_analyze_changes to regenerate it.`);
+                return toolError(`repositoryPath not found in state file metadata. The stateFile parameter must be the analyze-changes-state.json path returned by skyramp_analyze_changes — not summaryOutputFile or testbot-result.txt. Re-run skyramp_analyze_changes to regenerate it.`);
+            }
+            if (!Array.isArray(stateData.existingTests)) {
+                return toolError(`stateFile does not contain test discovery data (existingTests missing). The stateFile parameter must be the analyze-changes-state.json path returned by skyramp_analyze_changes — not summaryOutputFile or testbot-result.txt.`);
             }
             // Skyramp tests: full drift analysis + all actions permitted.
             // Relevant external tests (user-written, relevant to this PR's endpoints): drift analysis

package/build/tools/workspace/initializeWorkspaceTool.js

@@ -7,6 +7,7 @@ import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { SKYRAMP_IMAGE_VERSION } from "../../utils/versions.js";
 import { validateAndConsumeScanToken } from "./initScanWorkspaceTool.js";
+import { upsertServicesByRepo } from "./serviceUpsert.js";
 const require = createRequire(import.meta.url);
 const MCP_VERSION = require("../../../package.json").version || "";
 function getExecutorVersion() {
@@ -16,8 +17,8 @@ const TOOL_NAME = "skyramp_init_workspace";
 // writeWorkspaceConfig() writes the YAML directly (rather than via
 // WorkspaceConfigManager.addService) so all services are written in a single
 // pass without N+1 reads. The workspace serviceSchema accepts the full authType
-// set (incl. cookie/session/token), so input services are validated against it
-// directly — no local schema extension needed.
+// set (incl. cookie/session/token) and the multi-repo `repository` field, so input
+// services are validated against it directly — no local schema extension needed.
 const initializeWorkspaceSchema = z.object({
     workspacePath: z
         .string()
@@ -32,6 +33,10 @@ const initializeWorkspaceSchema = z.object({
         .boolean()
         .default(false)
         .describe("Set to true to overwrite an existing workspace file. Use when the user explicitly requests it, or when recovering from a workspace validation failure (schema mismatch, unknown fields). Default is false."),
+    merge: z
+        .boolean()
+        .default(false)
+        .describe("Set to true to MERGE the provided services into an existing workspace.yml instead of overwriting it. The primary use is registering a related repository's services into one unified workspace file (each service carrying its `repository`), but it applies whenever you want to add services without discarding existing ones. Services are upserted by the composite (repository, serviceName), so same-named services in different repos coexist. Ignored on first init (no existing file). Default is false."),
 });
 /**
  * Write a YAML workspace config to disk, bypassing the library's restricted
@@ -72,13 +77,17 @@ export function registerInitializeWorkspaceTool(server) {
         try {
             const workspacePath = params.workspacePath;
             const manager = new WorkspaceConfigManager(workspacePath);
-            // Check if already initialized
-            if ((await manager.exists()) && !params.force) {
+            const alreadyExists = await manager.exists();
+            // Check if already initialized. In merge mode we proceed (read the
+            // existing file and upsert into it) instead of refusing — this is how a
+            // multi-repo run registers each additional repo's services into one
+            // unified workspace.yml without a per-repo file.
+            if (alreadyExists && !params.force && !params.merge) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `Workspace already initialized at ${manager.getConfigPath()}. Set force: true to overwrite.`,
+                            text: `Workspace already initialized at ${manager.getConfigPath()}. Set force: true to overwrite, or merge: true to add services to it.`,
                         },
                     ],
                     isError: false,
@@ -107,24 +116,30 @@ export function registerInitializeWorkspaceTool(server) {
                     isError: true,
                 };
             }
-            // Initialize workspace
-            let config = await manager.initialize();
-            config = await manager.updateMetadata({
-                mcpVersion: MCP_VERSION,
-                executorVersion: getExecutorVersion(),
-            });
-            // Batch all service upserts: update in memory, write once (direct YAML
-            // write avoids N+1 reads and a mid-loop validation error).
-            const services = config.services ?? [];
-            for (const svc of params.services) {
-                const idx = services.findIndex((s) => s.serviceName === svc.serviceName);
-                if (idx >= 0) {
-                    services[idx] = svc;
-                }
-                else {
-                    services.push(svc);
-                }
+            // Initialize (fresh) or read (merge into existing). Merge mode preserves
+            // the existing primary repo identity + previously-registered services;
+            // initialize() would reset both, dropping other repos' services.
+            let config;
+            if (params.merge && alreadyExists) {
+                config = await manager.read();
+                config = await manager.updateMetadata({
+                    mcpVersion: MCP_VERSION,
+                    executorVersion: getExecutorVersion(),
+                });
+            }
+            else {
+                config = await manager.initialize();
+                config = await manager.updateMetadata({
+                    mcpVersion: MCP_VERSION,
+                    executorVersion: getExecutorVersion(),
+                });
             }
+            // Batch all service upserts: update in memory, write once (direct YAML
+            // write avoids N+1 reads and a mid-loop validation error). Upsert is keyed
+            // on the composite (repo, serviceName) — see upsertServicesByRepo — so a
+            // same-named service from an additional repo is a distinct entry, not an
+            // overwrite of the primary's.
+            const services = upsertServicesByRepo(config.services ?? [], params.services);
             config.services = services;
             if (config.metadata) {
                 config.metadata.updatedAt = new Date().toISOString();
@@ -142,6 +157,8 @@ export function registerInitializeWorkspaceTool(server) {
                 lines.push(`\nServices (${config.services.length}):`);
                 for (const svc of config.services) {
                     const parts = [svc.serviceName];
+                    if (svc.repository)
+                        parts.push(svc.repository);
                     if (svc.language)
                         parts.push(svc.language);
                     if (svc.framework)

package/build/tools/workspace/serviceUpsert.d.ts

@@ -0,0 +1,12 @@
+import type { Service } from "../../workspace/workspace.js";
+/**
+ * Upsert `incoming` services into `existing`, keyed on the composite
+ * (repository, serviceName). A service's `repository` (absent → primary,
+ * normalized to "") is part of its identity, so a same-named service from a
+ * different repo is a distinct entry rather than an overwrite. Mutates and
+ * returns `existing`.
+ *
+ * Lives in its own module (no `import.meta`) so it can be unit-tested under
+ * ts-jest's CommonJS transform without loading the tool's ESM-only deps.
+ */
+export declare function upsertServicesByRepo(existing: Service[], incoming: Service[]): Service[];

package/build/tools/workspace/serviceUpsert.js

@@ -0,0 +1,23 @@
+/**
+ * Upsert `incoming` services into `existing`, keyed on the composite
+ * (repository, serviceName). A service's `repository` (absent → primary,
+ * normalized to "") is part of its identity, so a same-named service from a
+ * different repo is a distinct entry rather than an overwrite. Mutates and
+ * returns `existing`.
+ *
+ * Lives in its own module (no `import.meta`) so it can be unit-tested under
+ * ts-jest's CommonJS transform without loading the tool's ESM-only deps.
+ */
+export function upsertServicesByRepo(existing, incoming) {
+    for (const svc of incoming) {
+        const repoKey = svc.repository || "";
+        const idx = existing.findIndex((s) => (s.repository || "") === repoKey && s.serviceName === svc.serviceName);
+        if (idx >= 0) {
+            existing[idx] = svc;
+        }
+        else {
+            existing.push(svc);
+        }
+    }
+    return existing;
+}

package/build/tools/workspace/serviceUpsert.test.d.ts

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

package/build/tools/workspace/serviceUpsert.test.js

@@ -0,0 +1,50 @@
+import { upsertServicesByRepo } from "./serviceUpsert.js";
+// upsertServicesByRepo is the merge=true core: it upserts incoming services into
+// the existing list keyed on the composite (repository, serviceName), so a
+// same-named service from a different repo is a distinct entry rather than an
+// overwrite. This is what makes the unified multi-repo workspace.yml correct.
+describe("upsertServicesByRepo", () => {
+    const svc = (serviceName, repository, testDirectory) => ({ serviceName, repository, testDirectory });
+    it("keeps same-named services from different repos as distinct entries", () => {
+        const existing = [svc("api", undefined, "tests/primary")];
+        const result = upsertServicesByRepo(existing, [
+            svc("api", "letsramp/api-insight", "tests/py"),
+        ]);
+        expect(result).toHaveLength(2);
+        expect(result.find((s) => !s.repository)?.testDirectory).toBe("tests/primary");
+        expect(result.find((s) => s.repository === "letsramp/api-insight")?.testDirectory).toBe("tests/py");
+    });
+    it("updates only the matching (repository, serviceName) entry in place", () => {
+        const existing = [
+            svc("api", undefined, "tests/primary"),
+            svc("api", "letsramp/api-insight", "tests/py"),
+        ];
+        // Re-register the related repo's service with a new testDirectory.
+        const result = upsertServicesByRepo(existing, [
+            svc("api", "letsramp/api-insight", "tests/py-v2"),
+        ]);
+        expect(result).toHaveLength(2);
+        // Primary untouched.
+        expect(result.find((s) => !s.repository)?.testDirectory).toBe("tests/primary");
+        // Related repo's entry updated in place (not duplicated).
+        const related = result.filter((s) => s.repository === "letsramp/api-insight");
+        expect(related).toHaveLength(1);
+        expect(related[0].testDirectory).toBe("tests/py-v2");
+    });
+    it("treats an absent repository as the primary (normalized to '')", () => {
+        const existing = [svc("api", undefined, "tests/primary")];
+        // A second primary write (no repository) upserts the SAME entry.
+        const result = upsertServicesByRepo(existing, [svc("api", undefined, "tests/primary-v2")]);
+        expect(result).toHaveLength(1);
+        expect(result[0].testDirectory).toBe("tests/primary-v2");
+    });
+    it("appends brand-new services from multiple repos", () => {
+        const result = upsertServicesByRepo([], [
+            svc("web", "letsramp/frontend", "tests/web"),
+            svc("api", "letsramp/backend", "tests/api"),
+            svc("api", undefined, "tests/primary"),
+        ]);
+        expect(result).toHaveLength(3);
+        expect(new Set(result.map((s) => `${s.repository ?? ""}|${s.serviceName}`))).toEqual(new Set(["letsramp/frontend|web", "letsramp/backend|api", "|api"]));
+    });
+});

package/build/types/TestAnalysis.d.ts

@@ -92,5 +92,6 @@ export interface TestAnalysisResult {
         changes: DriftChange[];
         affectedFiles: AffectedFiles;
     };
-    execution?: TestExecutionResult;
+    executionBefore?: TestExecutionResult;
+    executionAfter?: TestExecutionResult;
 }

package/build/types/TestExecution.d.ts

@@ -3,18 +3,28 @@
  *
  * These types define the structure for test execution results
  */
+/** Execution outcome for a test run recorded in the maintenance report. */
+export declare enum TestExecutionStatus {
+    Pass = "Pass",
+    Fail = "Fail",
+    Error = "Error",
+    /** Deliberately not executed — VERIFY/IGNORE actions or DELETE (file removed). */
+    Skipped = "Skipped",
+    /** Execution was expected (UPDATE/REGENERATE) but no result was recorded. */
+    Unknown = "Unknown"
+}
 export interface TestExecutionData {
-    passed: boolean;
+    status: TestExecutionStatus;
     executedAt: string;
     duration: number;
     errors: string[];
     warnings: string[];
-    crashed: boolean;
     output?: string;
     exitCode?: number;
 }
 export interface TestExecutionResult extends TestExecutionData {
     testFile: string;
+    videoPath?: string;
 }
 export interface BatchExecutionResult {
     totalTests: number;

package/build/types/TestExecution.js

@@ -3,4 +3,14 @@
  *
  * These types define the structure for test execution results
  */
-export {};
+/** Execution outcome for a test run recorded in the maintenance report. */
+export var TestExecutionStatus;
+(function (TestExecutionStatus) {
+    TestExecutionStatus["Pass"] = "Pass";
+    TestExecutionStatus["Fail"] = "Fail";
+    TestExecutionStatus["Error"] = "Error";
+    /** Deliberately not executed — VERIFY/IGNORE actions or DELETE (file removed). */
+    TestExecutionStatus["Skipped"] = "Skipped";
+    /** Execution was expected (UPDATE/REGENERATE) but no result was recorded. */
+    TestExecutionStatus["Unknown"] = "Unknown";
+})(TestExecutionStatus || (TestExecutionStatus = {}));