opencode-swarm-plugin 0.29.0 → 0.30.2

package/src/swarm-orchestrate.ts

@@ -21,6 +21,7 @@
 
 import { tool } from "@opencode-ai/plugin";
 import { z } from "zod";
+import { minimatch } from "minimatch";
 import {
   type AgentProgress,
   AgentProgressSchema,
@@ -32,6 +33,10 @@ import {
   type SwarmStatus,
   SwarmStatusSchema,
 } from "./schemas";
+import {
+  type WorkerHandoff,
+  WorkerHandoffSchema,
+} from "./schemas/worker-handoff";
 import {
   getSwarmInbox,
   releaseSwarmFiles,
@@ -82,6 +87,182 @@ import {
 // Helper Functions
 // ============================================================================
 
+/**
+ * Generate a WorkerHandoff object from subtask parameters
+ *
+ * Creates a machine-readable contract that replaces prose instructions in SUBTASK_PROMPT_V2.
+ * Workers receive typed handoffs with explicit files, criteria, and escalation paths.
+ *
+ * @param params - Subtask parameters
+ * @returns WorkerHandoff object validated against schema
+ */
+export function generateWorkerHandoff(params: {
+  task_id: string;
+  files_owned: string[];
+  files_readonly?: string[];
+  dependencies_completed?: string[];
+  success_criteria?: string[];
+  epic_summary: string;
+  your_role: string;
+  what_others_did?: string;
+  what_comes_next?: string;
+}): WorkerHandoff {
+  const handoff: WorkerHandoff = {
+    contract: {
+      task_id: params.task_id,
+      files_owned: params.files_owned,
+      files_readonly: params.files_readonly || [],
+      dependencies_completed: params.dependencies_completed || [],
+      success_criteria: params.success_criteria || [
+        "All files compile without errors",
+        "Tests pass for modified code",
+        "Code follows project patterns",
+      ],
+    },
+    context: {
+      epic_summary: params.epic_summary,
+      your_role: params.your_role,
+      what_others_did: params.what_others_did || "",
+      what_comes_next: params.what_comes_next || "",
+    },
+    escalation: {
+      blocked_contact: "coordinator",
+      scope_change_protocol:
+        "Send swarmmail_send(to=['coordinator'], subject='Scope change request: <task_id>', importance='high') and wait for approval before expanding beyond files_owned",
+    },
+  };
+
+  // Validate against schema
+  return WorkerHandoffSchema.parse(handoff);
+}
+
+/**
+ * Validate that files_touched is a subset of files_owned (supports globs)
+ *
+ * Checks contract compliance - workers should only modify files they own.
+ * Glob patterns in files_owned are matched against files_touched paths.
+ *
+ * @param files_touched - Actual files modified by the worker
+ * @param files_owned - Files the worker is allowed to modify (may include globs)
+ * @returns Validation result with violations list
+ *
+ * @example
+ * ```typescript
+ * // Exact match - passes
+ * validateContract(["src/a.ts"], ["src/a.ts", "src/b.ts"])
+ * // => { valid: true, violations: [] }
+ *
+ * // Glob match - passes
+ * validateContract(["src/auth/service.ts"], ["src/auth/**"])
+ * // => { valid: true, violations: [] }
+ *
+ * // Violation - fails
+ * validateContract(["src/other.ts"], ["src/auth/**"])
+ * // => { valid: false, violations: ["src/other.ts"] }
+ * ```
+ */
+export function validateContract(
+  files_touched: string[],
+  files_owned: string[]
+): { valid: boolean; violations: string[] } {
+  // Empty files_touched is valid (read-only work)
+  if (files_touched.length === 0) {
+    return { valid: true, violations: [] };
+  }
+
+  const violations: string[] = [];
+
+  for (const touchedFile of files_touched) {
+    let matched = false;
+
+    for (const ownedPattern of files_owned) {
+      // Check if pattern is a glob or exact match
+      if (ownedPattern.includes("*") || ownedPattern.includes("?")) {
+        // Glob pattern - use minimatch
+        if (minimatch(touchedFile, ownedPattern)) {
+          matched = true;
+          break;
+        }
+      } else {
+        // Exact match
+        if (touchedFile === ownedPattern) {
+          matched = true;
+          break;
+        }
+      }
+    }
+
+    if (!matched) {
+      violations.push(touchedFile);
+    }
+  }
+
+  return {
+    valid: violations.length === 0,
+    violations,
+  };
+}
+
+/**
+ * Get files_owned for a subtask from DecompositionGeneratedEvent
+ *
+ * Queries the event log for the decomposition that created this epic,
+ * then extracts the files array for the matching subtask.
+ *
+ * @param projectKey - Project path
+ * @param epicId - Epic ID
+ * @param subtaskId - Subtask cell ID  
+ * @returns Array of file patterns this subtask owns, or null if not found
+ */
+async function getSubtaskFilesOwned(
+  projectKey: string,
+  epicId: string,
+  subtaskId: string
+): Promise<string[] | null> {
+  try {
+    // Import readEvents from swarm-mail
+    const { readEvents } = await import("swarm-mail");
+    
+    // Query for decomposition_generated events for this epic
+    const events = await readEvents({
+      projectKey,
+      types: ["decomposition_generated"],
+    }, projectKey);
+    
+    // Find the event for this epic
+    const decompositionEvent = events.find((e: any) => 
+      e.type === "decomposition_generated" && e.epic_id === epicId
+    );
+    
+    if (!decompositionEvent) {
+      console.warn(`[swarm_complete] No decomposition event found for epic ${epicId}`);
+      return null;
+    }
+    
+    // Extract subtask index from subtask ID (e.g., "bd-abc123.0" -> 0)
+    // Subtask IDs follow pattern: epicId.index
+    const subtaskMatch = subtaskId.match(/\.(\d+)$/);
+    if (!subtaskMatch) {
+      console.warn(`[swarm_complete] Could not parse subtask index from ${subtaskId}`);
+      return null;
+    }
+    
+    const subtaskIndex = parseInt(subtaskMatch[1], 10);
+    const subtasks = (decompositionEvent as any).subtasks || [];
+    
+    if (subtaskIndex >= subtasks.length) {
+      console.warn(`[swarm_complete] Subtask index ${subtaskIndex} out of range (${subtasks.length} subtasks)`);
+      return null;
+    }
+    
+    const subtask = subtasks[subtaskIndex];
+    return subtask.files || [];
+  } catch (error) {
+    console.error(`[swarm_complete] Failed to query subtask files:`, error);
+    return null;
+  }
+}
+
 /**
  * Query beads for subtasks of an epic using HiveAdapter (not bd CLI)
  */
@@ -1109,17 +1290,16 @@ export const swarm_complete = tool({
         if (!reviewStatusResult.reviewed) {
           return JSON.stringify(
             {
-              success: false,
-              error: "Review required before completion",
+              success: true,
+              status: "pending_review",
               review_status: reviewStatusResult,
-              hint: `This task requires coordinator review before completion.
-
-**Next steps:**
-1. Request review with swarm_review(project_key="${args.project_key}", epic_id="${epicId}", task_id="${args.bead_id}", files_touched=[...])
-2. Wait for coordinator to review and approve with swarm_review_feedback
-3. Once approved, call swarm_complete again
-
-Or use skip_review=true to bypass (not recommended for production work).`,
+              message: "Task completed but awaiting coordinator review before finalization.",
+              next_steps: [
+                `Request review with swarm_review(project_key="${args.project_key}", epic_id="${epicId}", task_id="${args.bead_id}", files_touched=[...])`,
+                "Wait for coordinator to review and approve with swarm_review_feedback",
+                "Once approved, call swarm_complete again to finalize",
+                "Or use skip_review=true to bypass (not recommended for production work)",
+              ],
             },
             null,
             2,
@@ -1129,15 +1309,15 @@ Or use skip_review=true to bypass (not recommended for production work).`,
         // Review was attempted but not approved
         return JSON.stringify(
           {
-            success: false,
-            error: "Review not approved",
+            success: true,
+            status: "needs_changes",
             review_status: reviewStatusResult,
-            hint: `Task was reviewed but not approved. ${reviewStatusResult.remaining_attempts} attempt(s) remaining.
-
-**Next steps:**
-1. Address the feedback from the reviewer
-2. Request another review with swarm_review
-3. Once approved, call swarm_complete again`,
+            message: `Task reviewed but changes requested. ${reviewStatusResult.remaining_attempts} attempt(s) remaining.`,
+            next_steps: [
+              "Address the feedback from the reviewer",
+              `Request another review with swarm_review(project_key="${args.project_key}", epic_id="${epicId}", task_id="${args.bead_id}", files_touched=[...])`,
+              "Once approved, call swarm_complete again to finalize",
+            ],
           },
           null,
           2,
@@ -1147,15 +1327,14 @@ Or use skip_review=true to bypass (not recommended for production work).`,
 
     try {
       // Validate bead_id exists and is not already closed (EARLY validation)
-      const projectKey = args.project_key
-        .replace(/\//g, "-")
-        .replace(/\\/g, "-");
+      // NOTE: Use args.project_key directly - cells are stored with the original path
+      // (e.g., "/Users/joel/Code/project"), not a mangled version.
 
       // Use HiveAdapter for validation (not bd CLI)
       const adapter = await getHiveAdapter(args.project_key);
 
       // 1. Check if bead exists
-      const cell = await adapter.getCell(projectKey, args.bead_id);
+      const cell = await adapter.getCell(args.project_key, args.bead_id);
       if (!cell) {
         return JSON.stringify({
           success: false,
@@ -1180,14 +1359,14 @@ Or use skip_review=true to bypass (not recommended for production work).`,
 
       try {
         const agent = await getAgent(
-          projectKey,
+          args.project_key,
           args.agent_name,
           args.project_key,
         );
         agentRegistered = agent !== null;
 
         if (!agentRegistered) {
-          registrationWarning = `⚠️  WARNING: Agent '${args.agent_name}' was NOT registered in swarm-mail for project '${projectKey}'.
+          registrationWarning = `⚠️  WARNING: Agent '${args.agent_name}' was NOT registered in swarm-mail for project '${args.project_key}'.
 
 This usually means you skipped the MANDATORY swarmmail_init step.
 
@@ -1286,6 +1465,48 @@ Continuing with completion, but this should be fixed for future subtasks.`;
         }
       }
 
+      // Contract Validation - check files_touched against WorkerHandoff contract
+      let contractValidation: { valid: boolean; violations: string[] } | null = null;
+      let contractWarning: string | undefined;
+
+      if (args.files_touched && args.files_touched.length > 0) {
+        // Extract epic ID from subtask ID
+        const isSubtask = args.bead_id.includes(".");
+        
+        if (isSubtask) {
+          const epicId = args.bead_id.split(".")[0];
+          
+          // Query decomposition event for files_owned
+          const filesOwned = await getSubtaskFilesOwned(
+            args.project_key,
+            epicId,
+            args.bead_id
+          );
+          
+          if (filesOwned) {
+            contractValidation = validateContract(args.files_touched, filesOwned);
+            
+            if (!contractValidation.valid) {
+              // Contract violation - log warning (don't block completion)
+              contractWarning = `⚠️  CONTRACT VIOLATION: Modified files outside owned scope
+              
+**Files owned**: ${filesOwned.join(", ")}
+**Files touched**: ${args.files_touched.join(", ")}
+**Violations**: ${contractValidation.violations.join(", ")}
+
+This indicates scope creep - the worker modified files they weren't assigned.
+This will be recorded as a negative learning signal.`;
+
+              console.warn(`[swarm_complete] ${contractWarning}`);
+            } else {
+              console.log(`[swarm_complete] Contract validation passed: all ${args.files_touched.length} files within owned scope`);
+            }
+          } else {
+            console.warn(`[swarm_complete] Could not retrieve files_owned for contract validation - skipping`);
+          }
+        }
+      }
+
       // Parse and validate evaluation if provided
       let parsedEvaluation: Evaluation | undefined;
       if (args.evaluation) {
@@ -1367,6 +1588,8 @@ Continuing with completion, but this should be fixed for future subtasks.`;
           error_count: args.error_count || 0,
           retry_count: args.retry_count || 0,
           success: true,
+          scope_violation: contractValidation ? !contractValidation.valid : undefined,
+          violation_files: contractValidation?.violations,
         });
         await appendEvent(event, args.project_key);
       } catch (error) {
@@ -1544,6 +1767,21 @@ Files touched: ${args.files_touched?.join(", ") || "none recorded"}`,
             ? "Learning automatically stored in semantic-memory"
             : `Failed to store: ${memoryError}. Learning lost unless semantic-memory is available.`,
         },
+        // Contract validation result
+        contract_validation: contractValidation
+          ? {
+              validated: true,
+              passed: contractValidation.valid,
+              violations: contractValidation.violations,
+              warning: contractWarning,
+              note: contractValidation.valid
+                ? "All files within owned scope"
+                : "Scope violation detected - recorded as negative learning signal",
+            }
+          : {
+              validated: false,
+              reason: "No files_owned contract found (non-epic subtask or decomposition event missing)",
+            },
       };
 
       return JSON.stringify(response, null, 2);

package/src/swarm-prompts.ts

@@ -13,6 +13,7 @@
  */
 
 import { tool } from "@opencode-ai/plugin";
+import { generateWorkerHandoff } from "./swarm-orchestrate";
 
 // ============================================================================
 // Prompt Templates
@@ -326,10 +327,32 @@ swarmmail_reserve(
 
 **Workers reserve their own files.** This prevents edit conflicts with other agents.
 
-### Step 5: Do the Work
-- Read your assigned files
-- Implement changes
-- Verify (typecheck if applicable)
+### Step 5: Do the Work (TDD MANDATORY)
+
+**Follow RED → GREEN → REFACTOR. No exceptions.**
+
+1. **RED**: Write a failing test that describes the expected behavior
+   - Test MUST fail before you write implementation
+   - If test passes immediately, your test is wrong
+   
+2. **GREEN**: Write minimal code to make the test pass
+   - Don't over-engineer - just make it green
+   - Hardcode if needed, refactor later
+   
+3. **REFACTOR**: Clean up while tests stay green
+   - Run tests after every change
+   - If tests break, undo and try again
+
+\`\`\`bash
+# Run tests continuously
+bun test <your-test-file> --watch
+\`\`\`
+
+**Why TDD?**
+- Catches bugs before they exist
+- Documents expected behavior
+- Enables fearless refactoring
+- Proves your code works
 
 ### Step 6: Report Progress at Milestones
 \`\`\`
@@ -591,6 +614,26 @@ export function formatSubtaskPromptV2(params: {
     }
   }
 
+  // Generate WorkerHandoff contract (machine-readable section)
+  const handoff = generateWorkerHandoff({
+    task_id: params.bead_id,
+    files_owned: params.files,
+    files_readonly: [],
+    dependencies_completed: [],
+    success_criteria: [
+      "All files compile without errors",
+      "Tests pass for modified code",
+      "Code follows project patterns",
+    ],
+    epic_summary: params.subtask_description || params.subtask_title,
+    your_role: params.subtask_title,
+    what_others_did: params.recovery_context?.shared_context || "",
+    what_comes_next: "",
+  });
+
+  const handoffJson = JSON.stringify(handoff, null, 2);
+  const handoffSection = `\n## WorkerHandoff Contract\n\nThis is your machine-readable contract. The contract IS the instruction.\n\n\`\`\`json\n${handoffJson}\n\`\`\`\n`;
+
   return SUBTASK_PROMPT_V2.replace(/{bead_id}/g, params.bead_id)
     .replace(/{epic_id}/g, params.epic_id)
     .replace(/{project_path}/g, params.project_path || "$PWD")
@@ -602,7 +645,7 @@ export function formatSubtaskPromptV2(params: {
     .replace("{file_list}", fileList)
     .replace("{shared_context}", params.shared_context || "(none)")
     .replace("{compressed_context}", compressedSection)
-    .replace("{error_context}", errorSection + recoverySection);
+    .replace("{error_context}", errorSection + recoverySection + handoffSection);
 }
 
 /**

package/src/swarm-review.ts

@@ -686,6 +686,13 @@ export function clearReviewStatus(taskId: string): void {
   clearAttempts(taskId);
 }
 
+/**
+ * Mark a task as reviewed but not approved (for testing)
+ */
+export function markReviewRejected(taskId: string): void {
+  reviewStatus.set(taskId, { approved: false, timestamp: Date.now() });
+}
+
 // ============================================================================
 // Exports
 // ============================================================================