@skyramp/mcp 0.4.4 → 0.5.0-rc.10

package/build/tools/submitReportTool.js

@@ -9,7 +9,7 @@ import { ProgrammingLanguage, TESTBOT_SUPPORTED_TEST_TYPES, TestType, } from "..
 import { STEP_METHOD_DESCRIPTION, stepMethodSchema, } from "../types/StepMethod.js";
 import { DriftAction } from "../types/TestAnalysis.js";
 import { isResult, TestExecutionStatus } from "../types/TestExecution.js";
-import { EnvironmentFamily, FailureCauseKind, IssueFoundCategory, } from "../types/TestbotReport.js";
+import { IssueFoundCategory } from "../types/TestbotReport.js";
 import { StateManager, runArtifactDir, getTestsRepoDir, resolveOwnRunStatePath, } from "../utils/AnalysisStateManager.js";
 import { toolError, testFileMatches } from "../utils/utils.js";
 import { isTestbotEnabled, isUtilsReuseEnabled, } from "../utils/featureFlags.js";
@@ -115,46 +115,17 @@ const repositoryField = z
     .trim()
     .min(1)
     .describe("The 'owner/repo' this item pertains to (e.g. 'letsramp/api-insight'). Set it on every item — the primary's owner/repo for primary-repo objections, or a related repo's owner/repo for objections derived from that repository's diff.");
-// One home for the family meanings: a `.describe()` on the base enum is replaced
-// by the `.optional().describe()` at each use site, so the meanings go there.
-const ENVIRONMENT_FAMILY_MEANINGS = "auth_token = an API token is missing or expired. " +
-    "secret = another secret or credential is missing. " +
-    "data_connection = the database or data store is not reachable. " +
-    "app_not_started = the app under test did not start or is not reachable. " +
-    "login = the sign-in step failed. " +
-    "external_dependency = an external service is not configured. " +
-    "recording_replay = recording or replay of the trace failed.";
-const environmentFamilyField = z.enum(EnvironmentFamily);
-// SKYR-4555. Why a Fail or Skipped row did not pass; the row-level refinement on
-// testResultSchema decides when it is required and which shapes are consistent.
-const failureCauseSchema = z
-    .object({
-    kind: z
-        .enum(FailureCauseKind)
-        .describe("application = the code under test misbehaved, or a test written to prove a defect failed as intended. " +
-        "environment = the test could not exercise the behaviour because of the test environment: a missing token or secret, no data connection, the app did not start, sign-in failed, an external service is not configured, or recording or replay failed. Name the gap in `family`. " +
-        "test_defect = the generated test itself is wrong, not the app: an ambiguous locator, a strict-mode clash, a bad assertion setup."),
-    family: environmentFamilyField
-        .optional()
-        .describe("The test-environment gap. Required when kind is 'environment'. Not allowed for the other kinds. " +
-        ENVIRONMENT_FAMILY_MEANINGS),
-})
-    .describe("Why this test did not pass. REQUIRED when status is 'Fail' or 'Skipped'. Not allowed when status is 'Pass'. " +
-    "It must agree with reachedBehavior: 'application' needs reachedBehavior true or omitted; 'environment' needs reachedBehavior false or omitted.");
 // videoPath is deliberately absent from this input contract: it is attached server-side
 // from the run's execution records (see attachVideoPath), and zod strips any the model
 // supplies anyway. SKYR-4156 is what happens when the agent owns that field instead.
-const testResultSchema = z
-    .object({
+const testResultSchema = z.object({
     testType: z
         .enum(TestType)
         .describe("Type of test. Do not include priority or other metadata in this field."),
     endpoint: z
         .string()
         .describe("For contract and integration tests, the HTTP verb and path, e.g. 'GET /api/v1/products'. For ui and e2e tests, the page path the test opens, e.g. '/notifications'."),
-    status: z
-        .enum(["Pass", "Fail", "Skipped"])
-        .describe("Test execution result"),
+    status: z.enum(["Pass", "Fail", "Skipped"]).describe("Test execution result"),
     details: z
         .string()
         .describe("One sentence — no embedded newlines, no markdown. e.g. '10.8s, products_contract_test.py' or 'failed: <one-line error summary>, products_contract_test.py'"),
@@ -174,76 +145,7 @@ const testResultSchema = z
         .describe("For a failing test only. `true` when the request that carries the behaviour under test was sent and answered by the code under test, and the assertion that failed is about that behaviour. " +
         "`false` when the failure came earlier: a 404, 401, 403 or 5xx on a route the change adds; an expired token or a sign-in page; a control or setup step that failed; a generator or SDK error. " +
         "If your own `details` text says the request was not sent or an earlier step tripped, this is `false`. Omit only if you cannot tell."),
-    failureCause: failureCauseSchema.optional(),
     repository: repositoryField,
-})
-    .superRefine((row, ctx) => {
-    // SKYR-4555: the business-user report sorts failures by cause, so every row
-    // that did not pass must name one and a passing row must not. The kind must
-    // agree with reachedBehavior where the agent set it: the two answer the same
-    // question — did the test reach the behaviour under test — from two sides.
-    const cause = row.failureCause;
-    if (row.status === "Pass") {
-        if (cause === undefined)
-            return;
-        ctx.addIssue({
-            code: "custom",
-            path: ["failureCause"],
-            message: `failureCause is not allowed when status is 'Pass'. A passing test has no failure cause. ` +
-                `Remove failureCause from this row.`,
-        });
-        return;
-    }
-    if (cause === undefined) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["failureCause"],
-            message: `failureCause is required when status is '${row.status}'. Set failureCause.kind to one of: ` +
-                `'application' (the code under test misbehaved, or a test written to prove a defect failed as intended); ` +
-                `'environment' (the test environment stopped the test before it reached the behaviour — also set failureCause.family); ` +
-                `'test_defect' (the generated test itself is wrong, not the app).`,
-        });
-        return;
-    }
-    if (cause.kind === FailureCauseKind.Environment) {
-        if (cause.family === undefined) {
-            ctx.addIssue({
-                code: "custom",
-                path: ["failureCause", "family"],
-                message: `failureCause.family is required when failureCause.kind is 'environment'. ` +
-                    `Set it to the gap that stopped the test: ${Object.values(EnvironmentFamily).join(", ")}.`,
-            });
-        }
-    }
-    else if (cause.family !== undefined) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["failureCause", "family"],
-            message: `failureCause.family is allowed only when failureCause.kind is 'environment'. ` +
-                `Remove failureCause.family, or set kind to 'environment' if the test environment stopped the test.`,
-        });
-    }
-    if (cause.kind === FailureCauseKind.Application) {
-        if (row.reachedBehavior === false) {
-            ctx.addIssue({
-                code: "custom",
-                path: ["failureCause", "kind"],
-                message: `failureCause.kind 'application' contradicts reachedBehavior false. 'application' means the test reached the behaviour under test and the code misbehaved. ` +
-                    `If the failure came earlier, set kind to 'environment' or 'test_defect'. If the test did reach the behaviour, set reachedBehavior to true.`,
-            });
-        }
-    }
-    else if (cause.kind === FailureCauseKind.Environment &&
-        row.reachedBehavior === true) {
-        // test_defect is not checked: a wrong assertion can fail after the test
-        // reached the behaviour, or a bad setup step can fail before it.
-        ctx.addIssue({
-            code: "custom",
-            path: ["failureCause", "kind"],
-            message: `failureCause.kind 'environment' contradicts reachedBehavior true. reachedBehavior true means the test reached the behaviour under test, so the environment did not stop it. ` +
-                `Set kind to 'application' or 'test_defect', or set reachedBehavior to false if the failure came earlier.`,
-        });
-    }
 });
 // Structured grounding for UI recommendations. Lifted verbatim from a
 // `browser_blueprint` element captured during this run. Source of truth for
@@ -486,25 +388,8 @@ const issueFoundSchema = z
         .describe("1-based line number in sourceFile. Optional and advisory. " +
         "Give the line of the offending statement itself, not the line of the enclosing function's signature — review views place the objection on exactly this line. " +
         "The tool does not check that the line still holds the cited code, because line numbers drift."),
-    environmentFamily: environmentFamilyField
-        .optional()
-        .describe("Only for category 'config'. Not allowed for the other categories. " +
-        "When this config issue is a test-environment gap, name the gap. Omit it for a config issue that is not a test-environment gap. " +
-        ENVIRONMENT_FAMILY_MEANINGS),
 })
     .superRefine((issue, ctx) => {
-    // SKYR-4555: the family names a test-environment gap, which only a config
-    // entry reports. On a bug, lint or type entry it would put the issue in two
-    // places at once.
-    if (issue.environmentFamily !== undefined &&
-        issue.category !== IssueFoundCategory.Config) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["environmentFamily"],
-            message: `environmentFamily is allowed only when category is 'config'. It names the test-environment gap behind a config issue. ` +
-                `Remove environmentFamily from this '${issue.category}' entry, or set category to 'config' if the issue is a test-environment gap.`,
-        });
-    }
     // A `bug` entry asserts that product code is wrong, so it has to name the code:
     // without a file the entry is prose a reviewer cannot act on, and nothing
     // downstream can place it in the diff. Only the file is required — a config file
@@ -2865,10 +2750,7 @@ export function registerSubmitReportTool(server) {
             // these objects and don't expect it).
             testResults: params.testResults.map((row) => {
                 const { testFilePath: _tfp, ...wire } = attachVideoPath(row, stateData.executionVideos);
-                // SKYR-4555: the basename is the join key to newTestsCreated and
-                // testMaintenance (consumers compare it with the basename of their
-                // fileName, which may be a relative path); the path stays internal.
-                return { ...wire, fileName: path.basename(row.testFilePath) };
+                return wire;
             }),
             issuesFound,
             executionCoverage,

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

@@ -6,6 +6,7 @@ import { logger } from "../../utils/logger.js";
 import { canonicalJson, isPlainObject } from "../../utils/canonicalJson.js";
 import { StateManager, resolveOwnRunStatePath, } from "../../utils/AnalysisStateManager.js";
 import { toolError } from "../../utils/utils.js";
+import { AZURE_REPOSITORY_SLUG, isRepositorySlug, } from "../../utils/repositorySlug.js";
 import { TESTBOT_SUPPORTED_TEST_TYPES } from "../../types/TestTypes.js";
 import { changedFileNames, computeBranchDiff, } from "../../utils/branchDiff.js";
 import { collectChangedRuns } from "../../utils/changedRuns.js";
@@ -95,16 +96,27 @@ const registerStepSchema = z
         });
     }
 });
-/** The `owner/repo` a plan entry names. The SHAPE is checked, not just "not blank":
- *  a run keys each repository by the slug read off its origin remote. */
+/** An `org/project/repo` slug is right only on a run whose own repository is one:
+ *  on a GitHub run it is a typo, which the shape alone cannot tell. */
+function threePartSlugOffRun(params, runRepository) {
+    if (runRepository && AZURE_REPOSITORY_SLUG.test(runRepository)) {
+        return undefined;
+    }
+    return [...(params.plannedTests ?? []), ...(params.maintains ?? [])]
+        .map((entry) => entry?.repository)
+        .find((repository) => typeof repository === "string" && repository.split("/").length === 3);
+}
+/** The `owner/repo` (or Azure DevOps `org/project/repo`) a plan entry names. The
+ *  SHAPE is checked, not just "not blank": a run keys each repository by the slug
+ *  read off its origin remote. */
 function repositorySlugField(subject, purpose) {
     return z
         .string()
         .trim()
-        .regex(/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/, {
-        message: `${subject}'s repository must be an \`owner/repo\` slug`,
+        .refine(isRepositorySlug, {
+        message: `${subject}'s repository must be an \`owner/repo\` slug, or \`org/project/repo\` on Azure DevOps`,
     })
-        .describe(`The github repository slug, \`owner/repo\`, ${purpose}.`);
+        .describe(`The repository slug, \`owner/repo\` (\`org/project/repo\` on Azure DevOps), ${purpose}.`);
 }
 /** The `changes` and `defects` id lists a plan entry cites, written once. The two
  *  copies drifted whenever either was edited. */
@@ -902,7 +914,7 @@ export function registerRegisterTestPlanTool(server) {
         },
         description: "Register your complete test plan for this run, with the changes that make each planned test checkable. " +
             "The planning procedure in your prompt says how to decide and declare the plan. " +
-            "Every registration the schema accepts is stored, and no check ever refuses one. " +
+            "Every registration the schema accepts is stored, and no check ever refuses one, except an Azure DevOps `org/project/repo` on a run that is not on Azure DevOps. " +
             "The schema refuses the whole call, and names the field and the rule that refused it. " +
             "An undeclared key is refused by name on a planned test and on `declarations`, so a declaration written one level too high is corrected rather than dropped in silence. " +
             "Checks run against the stored plan and return objections. Fix one and register it again as often as you like, or answer it by id through `answers`. " +
@@ -926,6 +938,10 @@ export function registerRegisterTestPlanTool(server) {
                 if (!fullState) {
                     return toolError(`State file is empty or invalid: ${stateFile}. Call skyramp_analyze_changes first to generate a valid state file.`);
                 }
+                const offRun = threePartSlugOffRun(params, fullState.metadata?.repository);
+                if (offRun) {
+                    return toolError(`\`${offRun}\`: this run's repository must be an \`owner/repo\` slug; \`org/project/repo\` names an Azure DevOps repository, and this run is not on Azure DevOps.`);
+                }
                 const registrationNumber = (fullState.registrationCount ?? 0) + 1;
                 const registration = buildRegistration(params, registrationNumber);
                 // The previous registration's answers are already on the stored plan, which

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

@@ -1,4 +1,14 @@
 import { McpServer } from "@modelcontextprotocol/server";
-export declare function issueScanToken(): string;
+import { type ScanRelatedRepository } from "../../prompts/initialize-workspace/initializeWorkspacePrompt.js";
+/** What a scan token was issued for: when it expires, and the related
+ *  repositories its scan named, which skyramp_init_workspace verifies the
+ *  services against. */
+export interface ScanGrant {
+    expiry: number;
+    relatedRepositories: ScanRelatedRepository[];
+}
+export declare function issueScanToken(relatedRepositories?: ScanRelatedRepository[]): string;
+/** The grant of a valid, unexpired token, without consuming it. */
+export declare function scanTokenGrant(token: string): ScanGrant | undefined;
 export declare function validateAndConsumeScanToken(token: string): boolean;
 export declare function registerInitScanWorkspaceTool(server: McpServer): void;

package/build/tools/workspace/initScanWorkspaceTool.js

@@ -1,24 +1,33 @@
 import { z } from "zod";
 import { randomUUID } from "crypto";
+import fs from "fs";
 import { WorkspaceConfigManager } from "../../workspace/workspace.js";
+import { AZURE_REPOSITORY_SLUG, resolveRealPath, tryRepositorySlug, } from "../../utils/repositorySlug.js";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
-import { INIT_WORKSPACE_INSTRUCTIONS } from "../../prompts/initialize-workspace/initializeWorkspacePrompt.js";
+import { buildInitWorkspaceInstructions, } from "../../prompts/initialize-workspace/initializeWorkspacePrompt.js";
 const TOOL_NAME = "skyramp_init_scan";
-// Token store: token -> expiry timestamp (ms)
 const scanTokens = new Map();
 const TOKEN_TTL_MS = 10 * 60 * 1000; // 10 minutes
-export function issueScanToken() {
+export function issueScanToken(relatedRepositories = []) {
     const token = randomUUID();
-    scanTokens.set(token, Date.now() + TOKEN_TTL_MS);
+    scanTokens.set(token, {
+        expiry: Date.now() + TOKEN_TTL_MS,
+        relatedRepositories,
+    });
     return token;
 }
+/** The grant of a valid, unexpired token, without consuming it. */
+export function scanTokenGrant(token) {
+    const grant = scanTokens.get(token);
+    return grant && Date.now() < grant.expiry ? grant : undefined;
+}
 export function validateAndConsumeScanToken(token) {
-    const expiry = scanTokens.get(token);
-    if (!expiry)
+    const grant = scanTokens.get(token);
+    if (!grant)
         return false;
     scanTokens.delete(token);
-    return Date.now() < expiry;
+    return Date.now() < grant.expiry;
 }
 const initScanWorkspaceSchema = z.object({
     workspacePath: z.string().describe("Path to the workspace/repository root"),
@@ -26,12 +35,77 @@ const initScanWorkspaceSchema = z.object({
         .boolean()
         .default(false)
         .describe("Set to true to force a re-scan even if .skyramp/workspace.yml already exists. Default is false."),
+    relatedRepositories: z
+        .array(z.object({
+        repositoryPath: z
+            .string()
+            .describe("Path to the related repository's checkout"),
+        repository: z
+            .string()
+            .optional()
+            .describe("The related repository's owner/repo, or org/project/repo when workspacePath is on Azure DevOps. Defaults to the one its checkout's origin remote names."),
+    }))
+        .optional()
+        .describe("The other repositories of a multi-repository Target. Each is scanned into the one workspace.yml at workspacePath, its services carrying its owner/repo (org/project/repo on Azure DevOps) as `repository`; none gets a workspace.yml of its own. Omit for a single repository."),
+    testRepositoryPath: z
+        .string()
+        .optional()
+        .describe("Path to the separate test repository generated tests are delivered into, when there is one. Each service's testDirectory is then read from, and relative to, that checkout."),
 });
+const OWNER_REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+/** `owner/repo`, or `org/project/repo` when the workspace itself is on Azure
+ *  DevOps: on any other workspace a three-part name is a typo. */
+function isRelatedRepositorySlug(repository, workspaceRepository) {
+    if (OWNER_REPO.test(repository))
+        return true;
+    return (!!workspaceRepository &&
+        AZURE_REPOSITORY_SLUG.test(workspaceRepository) &&
+        AZURE_REPOSITORY_SLUG.test(repository));
+}
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Each related repository with its owner/repo, or the first problem with them:
+ * a checkout that is not a directory, is the workspace itself, or names no
+ * owner/repo, and a repository listed twice. Paths compare with symlinks
+ * resolved, and owner/repo case-insensitively, as GitHub does.
+ */
+async function resolveRelatedRepositories(workspacePath, entries) {
+    const repos = [];
+    const workspaceReal = await resolveRealPath(workspacePath);
+    const workspaceRepository = await tryRepositorySlug(workspacePath);
+    for (const entry of entries) {
+        const at = entry.repositoryPath;
+        if (!isDirectory(at))
+            return { error: `relatedRepositories: ${at} is not a directory` };
+        if ((await resolveRealPath(at)) === workspaceReal)
+            return {
+                error: `relatedRepositories: ${at} is workspacePath itself; list only the other repositories`,
+            };
+        const repository = entry.repository?.trim() || (await tryRepositorySlug(at));
+        if (!repository ||
+            !isRelatedRepositorySlug(repository, workspaceRepository))
+            return {
+                error: `relatedRepositories: no owner/repo for ${at}${repository ? ` ("${repository}" is not owner/repo, or org/project/repo on an Azure DevOps workspace)` : " (its checkout has no origin remote)"}; pass its repository`,
+            };
+        if (repos.some((r) => r.repository.toLowerCase() === repository.toLowerCase()))
+            return { error: `relatedRepositories: ${repository} is listed twice` };
+        repos.push({ repository, repositoryPath: at });
+    }
+    return { repos };
+}
 export function registerInitScanWorkspaceTool(server) {
     server.registerTool(TOOL_NAME, {
         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. " +
+            "For a Target spanning several repositories, call it ONCE with the others in relatedRepositories, so all their services go into one workspace.yml. " +
             "Follow the instructions to build the services array, then pass both to skyramp_init_workspace to create the workspace config.",
         inputSchema: initScanWorkspaceSchema,
     }, async (params) => {
@@ -39,6 +113,8 @@ export function registerInitScanWorkspaceTool(server) {
         const recordParams = {
             workspacePath: params.workspacePath,
             force: String(params.force || false),
+            relatedRepositories: String(params.relatedRepositories?.length ?? 0),
+            testRepository: String(Boolean(params.testRepositoryPath)),
         };
         try {
             const manager = new WorkspaceConfigManager(params.workspacePath);
@@ -53,12 +129,38 @@ export function registerInitScanWorkspaceTool(server) {
                     isError: false,
                 };
             }
-            const token = issueScanToken();
+            const related = await resolveRelatedRepositories(params.workspacePath, params.relatedRepositories ?? []);
+            if ("error" in related) {
+                errorResult = {
+                    content: [{ type: "text", text: related.error }],
+                    isError: true,
+                };
+                return errorResult;
+            }
+            if (params.testRepositoryPath &&
+                !isDirectory(params.testRepositoryPath)) {
+                errorResult = {
+                    content: [
+                        {
+                            type: "text",
+                            text: `testRepositoryPath: ${params.testRepositoryPath} is not a directory`,
+                        },
+                    ],
+                    isError: true,
+                };
+                return errorResult;
+            }
+            const token = issueScanToken(related.repos);
+            const instructions = buildInitWorkspaceInstructions({
+                workspacePath: params.workspacePath,
+                relatedRepositories: related.repos,
+                testRepositoryPath: params.testRepositoryPath,
+            });
             return {
                 content: [
                     {
                         type: "text",
-                        text: `SCAN TOKEN: ${token}\n\nSave this token — you MUST pass it as scanToken when calling skyramp_init_workspace.\n\n${INIT_WORKSPACE_INSTRUCTIONS}`,
+                        text: `SCAN TOKEN: ${token}\n\nSave this token — you MUST pass it as scanToken when calling skyramp_init_workspace.\n\n${instructions}`,
                     },
                 ],
                 isError: false,

package/build/tools/workspace/initializeWorkspaceTool.js

@@ -7,7 +7,8 @@ import yaml from "js-yaml";
 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 { scanTokenGrant, validateAndConsumeScanToken, } from "./initScanWorkspaceTool.js";
+import { verifyWorkspaceServices } from "../../workspace/workspaceVerifier.js";
 import { upsertServicesByRepo } from "./serviceUpsert.js";
 import { isInsideDir } from "../../utils/gitStaging.js";
 import { EXECUTOR_VIDEOS_DIR, EXECUTOR_WORK_DIR, isInsideExecutorWorkDir, } from "../../utils/executorWorkDir.js";
@@ -110,7 +111,7 @@ export function registerInitializeWorkspaceTool(server) {
             "1. Fresh init: PREREQUISITE: Call skyramp_init_scan first to get a scanToken and discover services. " +
             "Then call this tool to write .skyramp/workspace.yml with the discovered services and scanToken. " +
             "2. Edit existing workspace.yml: omit scanToken, set force: true, and pass the FULL updated services array (overwrite, not merge — fields not in the array are dropped). " +
-            "The services schema is strict: any field not in the schema (e.g. inventing `serverStopCommand` on `runtimeDetails`) fails validation and the call is rejected.",
+            "The services schema is strict: any field not in the schema (e.g. inventing `healthUrl` on `runtimeDetails`) fails validation and the call is rejected.",
         inputSchema: initializeWorkspaceSchema,
         _meta: {
             keywords: [
@@ -182,11 +183,46 @@ export function registerInitializeWorkspaceTool(server) {
                 if (badMerged)
                     return badTestDirectoryResult(badMerged);
             }
+            // The verifier, before the token is spent: a refusal asks for a
+            // corrected retry, which must be able to reuse the same token. Only the
+            // incoming services: a merge must not be blocked by an older entry.
+            const grant = params.scanToken
+                ? scanTokenGrant(params.scanToken)
+                : undefined;
+            const issues = verifyWorkspaceServices(params.services, {
+                workspacePath,
+                relatedRepositories: grant?.relatedRepositories,
+            });
+            if (issues.length > 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${manager.getConfigPath()} was not written: ${issues.length} problem(s) with the services.\n${issues.map((i) => `- ${i}`).join("\n")}\nFix each one and call skyramp_init_workspace again with the full corrected services array${grant ? " and the same scanToken, which is still valid" : ""}.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
             // scanToken is required for fresh init; for edits (force:true on an
             // existing workspace.yml) the caller supplies the full services array
-            // directly and we skip the token check.
+            // directly and no token is needed. A token passed with an edit is still
+            // validated and spent, so a successful write never leaves it reusable.
             const isEdit = alreadyExists && params.force;
-            if (!isEdit) {
+            if (isEdit && params.scanToken) {
+                if (!validateAndConsumeScanToken(params.scanToken)) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "Invalid or expired scanToken. An edit of an existing workspace.yml needs none: call again with force: true and no scanToken.",
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+            else if (!isEdit) {
                 if (!params.scanToken) {
                     return {
                         content: [

package/build/types/AssertionOutcome.d.ts

@@ -45,6 +45,9 @@ export interface AssertionRecord {
     baselineCount?: number;
     baselineStrength?: number;
     baselineFingerprints?: string[];
+    /** Integration-teardown `tracker.track_for_cleanup(` lines at hand-out — must survive
+     *  enhancement verbatim (verify hard-fails otherwise). */
+    baselineCreatedAddLines?: string[];
     issuedAt?: string;
     /** Verdict of the last verify pass; absent until one runs. */
     verification?: AssertionVerdict;

package/build/types/TestbotReport.d.ts

@@ -13,26 +13,6 @@ export declare enum IssueFoundCategory {
     Type = "type",
     Config = "config"
 }
-/** Why a Fail or Skipped testResults row did not pass. Application is the code
- *  under test (or a test written to prove a defect, failing as intended);
- *  Environment is the test environment stopping the test before it reached the
- *  behaviour; TestDefect is the generated test itself being wrong. */
-export declare enum FailureCauseKind {
-    Application = "application",
-    Environment = "environment",
-    TestDefect = "test_defect"
-}
-/** Which test-environment gap stopped a test: the `family` of an Environment
- *  failureCause, and the `environmentFamily` of a config issuesFound entry. */
-export declare enum EnvironmentFamily {
-    AuthToken = "auth_token",
-    Secret = "secret",
-    DataConnection = "data_connection",
-    AppNotStarted = "app_not_started",
-    Login = "login",
-    ExternalDependency = "external_dependency",
-    RecordingReplay = "recording_replay"
-}
 /**
  * Shape of the JSON report written by skyramp_submit_report and read by testbot
  * for rendering as Markdown. All fields mirror the corresponding Zod schemas in
@@ -124,19 +104,6 @@ export interface TestbotReport {
         endpoint: string;
         status: "Pass" | "Fail" | "Skipped";
         details: string;
-        /** Server-derived: the basename of the `testFilePath` the agent submitted,
-         *  which never reaches the report. The join key to `newTestsCreated` and
-         *  `testMaintenance`: match it against the basename of their `fileName`
-         *  (a `newTestsCreated` row may carry a repository-relative path), plus
-         *  `repository`. */
-        fileName: string;
-        /** Why a Fail or Skipped row did not pass. The submit schema requires it on
-         *  those rows and refuses it on a Pass row; `family` is set exactly when
-         *  `kind` is Environment. Absent in reports from MCP versions predating it. */
-        failureCause?: {
-            kind: FailureCauseKind;
-            family?: EnvironmentFamily;
-        };
         videoPath?: string;
         /** See newTestsCreated[].repository. */
         repository: string;
@@ -191,10 +158,6 @@ export interface TestbotReport {
         sourceFile?: string;
         sourceSymbol?: string;
         sourceLine?: number;
-        /** On a `config` entry that is a test-environment gap, which gap. The submit
-         *  schema refuses it on any other category. Optional: a config entry need
-         *  not be an environment gap, and older MCP versions never set it. */
-        environmentFamily?: EnvironmentFamily;
         /** See newTestsCreated[].repository. */
         repository: string;
     }[];

package/build/types/TestbotReport.js

@@ -8,25 +8,3 @@ export var IssueFoundCategory;
     IssueFoundCategory["Type"] = "type";
     IssueFoundCategory["Config"] = "config";
 })(IssueFoundCategory || (IssueFoundCategory = {}));
-/** Why a Fail or Skipped testResults row did not pass. Application is the code
- *  under test (or a test written to prove a defect, failing as intended);
- *  Environment is the test environment stopping the test before it reached the
- *  behaviour; TestDefect is the generated test itself being wrong. */
-export var FailureCauseKind;
-(function (FailureCauseKind) {
-    FailureCauseKind["Application"] = "application";
-    FailureCauseKind["Environment"] = "environment";
-    FailureCauseKind["TestDefect"] = "test_defect";
-})(FailureCauseKind || (FailureCauseKind = {}));
-/** Which test-environment gap stopped a test: the `family` of an Environment
- *  failureCause, and the `environmentFamily` of a config issuesFound entry. */
-export var EnvironmentFamily;
-(function (EnvironmentFamily) {
-    EnvironmentFamily["AuthToken"] = "auth_token";
-    EnvironmentFamily["Secret"] = "secret";
-    EnvironmentFamily["DataConnection"] = "data_connection";
-    EnvironmentFamily["AppNotStarted"] = "app_not_started";
-    EnvironmentFamily["Login"] = "login";
-    EnvironmentFamily["ExternalDependency"] = "external_dependency";
-    EnvironmentFamily["RecordingReplay"] = "recording_replay";
-})(EnvironmentFamily || (EnvironmentFamily = {}));

package/build/types/index.d.ts

@@ -2,7 +2,7 @@ export { TestExecutionStatus } from "./TestExecution.js";
 export { DriftAction } from "./TestAnalysis.js";
 export { TestType, HttpMethod } from "./TestTypes.js";
 export type { TestbotReport } from "./TestbotReport.js";
-export { IssueFoundCategory, FailureCauseKind, EnvironmentFamily, } from "./TestbotReport.js";
+export { IssueFoundCategory } from "./TestbotReport.js";
 export { ReuseDeclinedBy, ReuseVerificationOutcome, HelperVerificationOutcome, } from "./ReuseOutcome.js";
 export type { ReuseOutcome, ReuseSkippedEntry, ReuseMissedEntry, HelperReuseOutcome, RetrofitOutcome, ChangedHelperEntry, ChangedHelperCaller, OrphanedHelper, } from "./ReuseOutcome.js";
 export type { RelatedRepository, TestbotPromptOptions, } from "./TestbotPromptOptions.js";

package/build/types/index.js

@@ -1,5 +1,5 @@
 export { TestExecutionStatus } from "./TestExecution.js";
 export { DriftAction } from "./TestAnalysis.js";
 export { TestType, HttpMethod } from "./TestTypes.js";
-export { IssueFoundCategory, FailureCauseKind, EnvironmentFamily, } from "./TestbotReport.js";
+export { IssueFoundCategory } from "./TestbotReport.js";
 export { ReuseDeclinedBy, ReuseVerificationOutcome, HelperVerificationOutcome, } from "./ReuseOutcome.js";

package/build/utils/assertion-verify/created-add-guard.d.ts

@@ -0,0 +1,12 @@
+import type { LintFinding } from "./lint-types.js";
+/** Each whole `tracker.track_for_cleanup(...)` / `tracker.trackForCleanup(...)`
+ *  call of a file, in order — the baseline the enhanced file is compared
+ *  against. */
+export declare function collectCreatedAddLines(content: string): string[];
+/**
+ * Hard findings when the enhanced file's registration lines differ from the
+ * baseline's (sequence must match exactly: same lines, same count, same order)
+ * or when anything but blank or comment lines sits between an id capture and
+ * its registration. With no baseline only the adjacency check runs.
+ */
+export declare function lintCreatedAddLines(content: string, baselineLines?: string[]): LintFinding[];