chore: sync public mirror from internal

Author: haasonsaas

src/agent/swarm/executor.ts

@@ -81,6 +81,7 @@ import type {
 	SwarmTeammate,
 	TeammateStatus,
 } from "./types.js";
+import { buildSwarmValidationDirective } from "./validation-directive.js";
 
 const logger = createLogger("agent:swarm:executor");
 
@@ -1290,8 +1291,7 @@ export class SwarmExecutor {
 			evidence: task.files?.length
 				? task.files.map((file) => `Relevant file: ${file}`)
 				: [],
-			validation:
-				"Make the requested changes directly, add or update focused tests when behavior changes, and run the relevant verification before finishing.",
+			validation: buildSwarmValidationDirective(task.mocksAllowed),
 			stoppingCondition:
 				"Stop when the assigned task is complete and report what changed, what you verified, and any blockers. Do not broaden into unrelated tasks.",
 		};

src/agent/swarm/types.ts

@@ -41,6 +41,12 @@ export interface SwarmTask {
 	a2aSkillId?: string;
 	/** Optional durable specialist profile to prepend to the teammate prompt. */
 	specialistProfile?: string;
+	/**
+	 * Explicit opt-out of the end-to-end validation default. When true, the
+	 * teammate may use mocks/stubs for unavailable integrations; otherwise the
+	 * worker must validate against real integrations before reporting done.
+	 */
+	mocksAllowed?: boolean;
 	/** Priority (higher = earlier execution when no dependencies) */
 	priority?: number;
 }

src/agent/swarm/validation-directive.ts

@@ -0,0 +1,29 @@
+/**
+ * Swarm validation directive
+ *
+ * Builds the "## Validation" section handed to every swarm teammate. The
+ * default posture is end-to-end validation against real integrations: a worker
+ * may not declare a task done on the strength of a mocked path. Mocks/stubs are
+ * an explicit per-task opt-out (`SwarmTask.mocksAllowed`), not the baseline.
+ *
+ * This mirrors the orchestrator discipline that high-end coding agents apply at
+ * the mission level, pushed down to the per-worker delegation prompt so the
+ * default holds even for a single delegated task.
+ */
+
+const REAL_INTEGRATION_DIRECTIVE =
+	"Validate end-to-end against real integrations. The default is that every change is exercised through its real execution path — real services, real data, real auth — before you finish. Do not introduce mocks or stubs to make a check pass. Add or update focused tests when behavior changes, and run the relevant verification (build, lint, the touched tests, and the real end-to-end path) before reporting completion. If an integration genuinely cannot be exercised in this environment, stop and report it as a blocker rather than claiming success — never report that something works on the strength of a mocked path alone.";
+
+const MOCKS_ALLOWED_DIRECTIVE =
+	"This task is explicitly approved to use mocks or stubs where a real integration is unavailable. Prefer the real execution path wherever it exists; where you fall back to a mock, say so explicitly and name exactly what was not exercised for real. Add or update focused tests when behavior changes, and run the relevant verification before reporting completion.";
+
+/**
+ * Returns the validation directive for a swarm task.
+ *
+ * @param mocksAllowed When true, the task has explicitly opted out of the
+ *   real-integration default and may use mocks/stubs for unavailable
+ *   dependencies.
+ */
+export function buildSwarmValidationDirective(mocksAllowed?: boolean): string {
+	return mocksAllowed ? MOCKS_ALLOWED_DIRECTIVE : REAL_INTEGRATION_DIRECTIVE;
+}

test/agent/swarm-executor.test.ts

@@ -315,7 +315,10 @@ describe("SwarmExecutor", () => {
 		expect(prompt).toContain("## Context\nYou are teammate");
 		expect(prompt).toContain("## Task\nUpdate the implementation");
 		expect(prompt).toContain(
-			"## Validation\nMake the requested changes directly",
+			"## Validation\nValidate end-to-end against real integrations",
+		);
+		expect(prompt).toContain(
+			"never report that something works on the strength of a mocked path alone",
 		);
 		expect(prompt).toContain(
 			"## Stopping Condition\nStop when the assigned task is complete",
@@ -341,6 +344,24 @@ describe("SwarmExecutor", () => {
 		expect(recordSubagentDispatchMock).not.toHaveBeenCalled();
 	});
 
+	it("passes the mocks-allowed validation directive into spawned teammate prompts", async () => {
+		let prompt = "";
+		spawnMock.mockImplementation((_command: string, args: string[]) => {
+			prompt = readFileSync(args.at(-1)!, "utf-8");
+			return createMockChildProcess("done");
+		});
+
+		const executor = new SwarmExecutor(createConfig({ mocksAllowed: true }));
+		void executor.execute();
+		await waitForSpawn();
+
+		expect(prompt).toContain(
+			"## Validation\nThis task is explicitly approved to use mocks or stubs",
+		);
+		expect(prompt).toContain("name exactly what was not exercised for real");
+		expect(prompt).not.toContain("Do not introduce mocks or stubs");
+	});
+
 	it("marks spawned teammates as mission workers", async () => {
 		spawnMock.mockImplementation(() => createMockChildProcess("done"));
 		vi.stubEnv("MAESTRO_MISSION_ROLE", "orchestrator");

test/agent/swarm-validation-directive.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { buildSwarmValidationDirective } from "../../src/agent/swarm/validation-directive.js";
+
+describe("buildSwarmValidationDirective", () => {
+	it("defaults to end-to-end validation against real integrations", () => {
+		const directive = buildSwarmValidationDirective();
+		expect(directive).toContain(
+			"Validate end-to-end against real integrations",
+		);
+		expect(directive).toContain("Do not introduce mocks or stubs");
+		expect(directive).toContain("report it as a blocker");
+		expect(directive).not.toContain("explicitly approved to use mocks");
+	});
+
+	it("treats an undefined flag the same as the strict default", () => {
+		expect(buildSwarmValidationDirective(undefined)).toBe(
+			buildSwarmValidationDirective(false),
+		);
+	});
+
+	it("relaxes to a mocks-allowed directive only on explicit opt-out", () => {
+		const directive = buildSwarmValidationDirective(true);
+		expect(directive).toContain("explicitly approved to use mocks");
+		expect(directive).toContain("name exactly what was not exercised for real");
+		expect(directive).not.toContain("Do not introduce mocks or stubs");
+	});
+});