opencode-swarm 6.58.0 → 6.59.0

package/dist/index.js

@@ -389,7 +389,8 @@ var init_constants = __esm(() => {
     retrieve_summary: "retrieve the full content of a stored tool output summary",
     search: "Workspace-scoped ripgrep-style text search with structured JSON output. Supports literal and regex modes, glob filtering, and result limits. NOTE: This is text search, not structural AST search \u2014 use symbols and imports tools for structural queries.",
     batch_symbols: "Batched symbol extraction across multiple files. Returns per-file symbol summaries with isolated error handling.",
-    suggest_patch: "Reviewer-safe structured patch suggestion tool. Produces context-anchored patch artifacts without file modification. Returns structured diagnostics on context mismatch."
+    suggest_patch: "Reviewer-safe structured patch suggestion tool. Produces context-anchored patch artifacts without file modification. Returns structured diagnostics on context mismatch.",
+    lint_spec: "validate .swarm/spec.md format and required fields"
   };
   for (const [agentName, tools] of Object.entries(AGENT_TOOL_MAP)) {
     const invalidTools = tools.filter((tool) => !TOOL_NAME_SET.has(tool));
@@ -15848,19 +15849,50 @@ async function appendLedgerEvent(directory, eventInput, options) {
   fs3.renameSync(tempPath, ledgerPath);
   return event;
 }
+async function appendLedgerEventWithRetry(directory, eventInput, options) {
+  const maxRetries = options.maxRetries ?? 3;
+  const backoffBase = options.backoffMs ?? 10;
+  let currentExpected = options.expectedHash;
+  let attempt = 0;
+  while (true) {
+    try {
+      return await appendLedgerEvent(directory, eventInput, {
+        expectedHash: currentExpected,
+        planHashAfter: options.planHashAfter
+      });
+    } catch (error49) {
+      if (!(error49 instanceof LedgerStaleWriterError) || attempt >= maxRetries) {
+        throw error49;
+      }
+      attempt++;
+      const delayMs = backoffBase * 2 ** (attempt - 1);
+      await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+      if (options.verifyValid) {
+        const stillValid = await options.verifyValid();
+        if (!stillValid) {
+          return null;
+        }
+      }
+      currentExpected = computeCurrentPlanHash(directory);
+    }
+  }
+}
 async function takeSnapshotEvent(directory, plan, options) {
   const payloadHash = computePlanHash(plan);
   const snapshotPayload = {
     plan,
     payload_hash: payloadHash
   };
+  if (options?.approvalMetadata) {
+    snapshotPayload.approval = options.approvalMetadata;
+  }
   const planId = `${plan.swarm}-${plan.title}`.replace(/[^a-zA-Z0-9-_]/g, "_");
   return appendLedgerEvent(directory, {
     event_type: "snapshot",
-    source: "takeSnapshotEvent",
+    source: options?.source ?? "takeSnapshotEvent",
     plan_id: planId,
     payload: snapshotPayload
-  }, options);
+  }, { planHashAfter: options?.planHashAfter });
 }
 async function replayFromLedger(directory, options) {
   const events = await readLedgerEvents(directory);
@@ -15949,6 +15981,40 @@ function applyEventToPlan(plan, event) {
       throw new Error(`applyEventToPlan: unhandled event type "${event.event_type}" at seq ${event.seq}`);
   }
 }
+async function loadLastApprovedPlan(directory, expectedPlanId) {
+  const events = await readLedgerEvents(directory);
+  if (events.length === 0) {
+    return null;
+  }
+  for (let i2 = events.length - 1;i2 >= 0; i2--) {
+    const event = events[i2];
+    if (event.event_type !== "snapshot")
+      continue;
+    if (event.source !== "critic_approved")
+      continue;
+    if (expectedPlanId !== undefined && event.plan_id !== expectedPlanId) {
+      continue;
+    }
+    const payload = event.payload;
+    if (!payload || typeof payload !== "object" || !payload.plan) {
+      continue;
+    }
+    if (expectedPlanId !== undefined) {
+      const payloadPlanId = `${payload.plan.swarm}-${payload.plan.title}`.replace(/[^a-zA-Z0-9-_]/g, "_");
+      if (payloadPlanId !== expectedPlanId) {
+        continue;
+      }
+    }
+    return {
+      plan: payload.plan,
+      seq: event.seq,
+      timestamp: event.timestamp,
+      approval: payload.approval,
+      payloadHash: payload.payload_hash
+    };
+  }
+  return null;
+}
 var LEDGER_SCHEMA_VERSION = "1.0.0", LEDGER_FILENAME = "plan-ledger.jsonl", PLAN_JSON_FILENAME = "plan.json", LedgerStaleWriterError;
 var init_ledger = __esm(() => {
   init_plan_schema();
@@ -16111,6 +16177,23 @@ async function loadPlan(directory) {
                     return rebuilt;
                   }
                 } catch (replayError) {
+                  try {
+                    const approved = await loadLastApprovedPlan(directory, currentPlanId);
+                    if (approved) {
+                      await rebuildPlan(directory, approved.plan);
+                      try {
+                        await takeSnapshotEvent(directory, approved.plan, {
+                          source: "recovery_from_approved_snapshot",
+                          approvalMetadata: approved.approval
+                        });
+                      } catch (healError) {
+                        warn(`[loadPlan] Recovery-heal snapshot append failed: ${healError instanceof Error ? healError.message : String(healError)}. Next loadPlan may re-enter recovery path.`);
+                      }
+                      const approvedPhase = approved.approval && typeof approved.approval === "object" && "phase" in approved.approval ? approved.approval.phase : undefined;
+                      warn(`[loadPlan] Ledger replay failed (${replayError instanceof Error ? replayError.message : String(replayError)}) \u2014 recovered from critic-approved snapshot seq=${approved.seq} (approval phase=${approvedPhase ?? "unknown"}, timestamp=${approved.timestamp}). This may roll the plan back to an earlier phase \u2014 verify before continuing.`);
+                      return approved.plan;
+                    }
+                  } catch {}
                   warn(`[loadPlan] Ledger replay failed during hash-mismatch rebuild: ${replayError instanceof Error ? replayError.message : String(replayError)}. Returning stale plan.json. To recover: check SWARM_PLAN.md for a checkpoint, or run /swarm reset-session.`);
                 }
               }
@@ -16201,6 +16284,31 @@ async function loadPlan(directory) {
       await savePlan(directory, rebuilt);
       return rebuilt;
     }
+    try {
+      const anchorEvents = await readLedgerEvents(directory);
+      if (anchorEvents.length === 0) {
+        warn("[loadPlan] Ledger present but no events readable \u2014 refusing approved-snapshot recovery (cannot verify plan identity).");
+        return null;
+      }
+      const expectedPlanId = anchorEvents[0].plan_id;
+      const approved = await loadLastApprovedPlan(directory, expectedPlanId);
+      if (approved) {
+        const approvedPhase = approved.approval && typeof approved.approval === "object" && "phase" in approved.approval ? approved.approval.phase : undefined;
+        warn(`[loadPlan] Ledger replay returned no plan \u2014 recovered from critic-approved snapshot seq=${approved.seq} timestamp=${approved.timestamp} (approval phase=${approvedPhase ?? "unknown"}). This may roll the plan back to an earlier phase \u2014 verify before continuing.`);
+        await savePlan(directory, approved.plan);
+        try {
+          await takeSnapshotEvent(directory, approved.plan, {
+            source: "recovery_from_approved_snapshot",
+            approvalMetadata: approved.approval
+          });
+        } catch (healError) {
+          warn(`[loadPlan] Recovery-heal snapshot append failed: ${healError instanceof Error ? healError.message : String(healError)}. Next loadPlan may re-enter recovery path.`);
+        }
+        return approved.plan;
+      }
+    } catch (recoveryError) {
+      warn(`[loadPlan] Approved-snapshot recovery failed: ${recoveryError instanceof Error ? recoveryError.message : String(recoveryError)}`);
+    }
   }
   return null;
 }
@@ -16334,16 +16442,31 @@ async function savePlan(directory, plan, options) {
               to_status: task.status,
               source: "savePlan"
             };
-            await appendLedgerEvent(directory, eventInput, {
+            const capturedFromStatus = oldTask.status;
+            const capturedTaskId = task.id;
+            await appendLedgerEventWithRetry(directory, eventInput, {
               expectedHash: currentHash,
-              planHashAfter: hashAfter
+              planHashAfter: hashAfter,
+              maxRetries: 3,
+              verifyValid: async () => {
+                const onDisk = await loadPlanJsonOnly(directory);
+                if (!onDisk)
+                  return true;
+                for (const p of onDisk.phases) {
+                  const t = p.tasks.find((x) => x.id === capturedTaskId);
+                  if (t) {
+                    return t.status === capturedFromStatus;
+                  }
+                }
+                return false;
+              }
             });
           }
         }
       }
     } catch (error49) {
       if (error49 instanceof LedgerStaleWriterError) {
-        throw new Error(`Concurrent plan modification detected: ${error49.message}. Please retry the operation.`);
+        throw new Error(`Concurrent plan modification detected after retries: ${error49.message}. Please retry the operation.`);
       }
       throw error49;
     }
@@ -47025,7 +47148,7 @@ async function executeWriteRetro(args2, directory) {
         message: "Invalid task ID: path traversal detected"
       }, null, 2);
     }
-    const VALID_TASK_ID = /^(retro-\d+|\d+\.\d+(\.\d+)*)$/;
+    const VALID_TASK_ID = /^(retro-[a-zA-Z0-9][a-zA-Z0-9_-]*|\d+\.\d+(\.\d+)*)$/;
     if (!VALID_TASK_ID.test(tid)) {
       return JSON.stringify({
         success: false,
@@ -47173,6 +47296,7 @@ var write_retro = createSwarmTool({
 var ARCHIVE_ARTIFACTS = [
   "plan.json",
   "plan.md",
+  "plan-ledger.jsonl",
   "context.md",
   "events.jsonl",
   "handoff.md",
@@ -47182,7 +47306,9 @@ var ARCHIVE_ARTIFACTS = [
   "close-lessons.md"
 ];
 var ACTIVE_STATE_TO_CLEAN = [
+  "plan.json",
   "plan.md",
+  "plan-ledger.jsonl",
   "events.jsonl",
   "handoff.md",
   "handoff-prompt.md",
@@ -47257,6 +47383,33 @@ async function handleCloseCommand(directory, args2) {
       }
     }
   }
+  const wrotePhaseRetro = closedPhases.length > 0;
+  if (!wrotePhaseRetro && !planExists) {
+    try {
+      const sessionRetroResult = await executeWriteRetro({
+        phase: 1,
+        task_id: "retro-session",
+        summary: isForced ? "Plan-free session force-closed via /swarm close --force" : "Plan-free session closed via /swarm close",
+        task_count: 1,
+        task_complexity: "simple",
+        total_tool_calls: 0,
+        coder_revisions: 0,
+        reviewer_rejections: 0,
+        test_failures: 0,
+        security_findings: 0,
+        integration_issues: 0,
+        metadata: { session_scope: "plan_free" }
+      }, directory);
+      try {
+        const parsed = JSON.parse(sessionRetroResult);
+        if (parsed.success !== true) {
+          warnings.push(`Session retrospective write failed: ${parsed.message ?? "unknown"}`);
+        }
+      } catch {}
+    } catch (retroError) {
+      warnings.push(`Session retrospective write threw: ${retroError instanceof Error ? retroError.message : String(retroError)}`);
+    }
+  }
   const lessonsFilePath = path14.join(swarmDir, "close-lessons.md");
   let explicitLessons = [];
   try {
@@ -47269,6 +47422,8 @@ async function handleCloseCommand(directory, args2) {
     await curateAndStoreSwarm(explicitLessons, projectName, { phase_number: 0 }, directory, config3);
     curationSucceeded = true;
   } catch (error93) {
+    const msg = error93 instanceof Error ? error93.message : String(error93);
+    warnings.push(`Lessons curation failed: ${msg}`);
     console.warn("[close-command] curateAndStoreSwarm error:", error93);
   }
   if (curationSucceeded && explicitLessons.length > 0) {
@@ -47294,6 +47449,8 @@ async function handleCloseCommand(directory, args2) {
     try {
       await fs9.writeFile(planPath, JSON.stringify(planData, null, 2), "utf-8");
     } catch (error93) {
+      const msg = error93 instanceof Error ? error93.message : String(error93);
+      warnings.push(`Failed to persist terminal plan.json state: ${msg}`);
       console.warn("[close-command] Failed to write plan.json:", error93);
     }
   }
@@ -47355,6 +47512,8 @@ async function handleCloseCommand(directory, args2) {
   try {
     await archiveEvidence(directory, 30, 10);
   } catch (error93) {
+    const msg = error93 instanceof Error ? error93.message : String(error93);
+    warnings.push(`Evidence retention archive failed: ${msg}`);
     console.warn("[close-command] archiveEvidence error:", error93);
   }
   let configBackupsRemoved = 0;
@@ -47383,6 +47542,12 @@ async function handleCloseCommand(directory, args2) {
         configBackupsRemoved++;
       } catch {}
     }
+    const ledgerSiblings = swarmFiles.filter((f) => (f.startsWith("plan-ledger.archived-") || f.startsWith("plan-ledger.backup-")) && f.endsWith(".jsonl"));
+    for (const sibling of ledgerSiblings) {
+      try {
+        await fs9.unlink(path14.join(swarmDir, sibling));
+      } catch {}
+    }
   } catch {}
   const contextPath = path14.join(swarmDir, "context.md");
   const contextContent = [
@@ -47399,6 +47564,8 @@ async function handleCloseCommand(directory, args2) {
   try {
     await fs9.writeFile(contextPath, contextContent, "utf-8");
   } catch (error93) {
+    const msg = error93 instanceof Error ? error93.message : String(error93);
+    warnings.push(`Failed to reset context.md: ${msg}`);
     console.warn("[close-command] Failed to write context.md:", error93);
   }
   const pruneBranches = args2.includes("--prune-branches");
@@ -47528,16 +47695,27 @@ async function handleCloseCommand(directory, args2) {
   try {
     await fs9.writeFile(closeSummaryPath, summaryContent, "utf-8");
   } catch (error93) {
+    const msg = error93 instanceof Error ? error93.message : String(error93);
+    warnings.push(`Failed to write close-summary.md: ${msg}`);
     console.warn("[close-command] Failed to write close-summary.md:", error93);
   }
   try {
     await flushPendingSnapshot(directory);
   } catch (error93) {
+    const msg = error93 instanceof Error ? error93.message : String(error93);
+    warnings.push(`flushPendingSnapshot failed: ${msg}`);
     console.warn("[close-command] flushPendingSnapshot error:", error93);
   }
   await writeCheckpoint(directory).catch(() => {});
-  swarmState.agentSessions.clear();
-  swarmState.delegationChains.clear();
+  const preservedClient = swarmState.opencodeClient;
+  const preservedFullAutoFlag = swarmState.fullAutoEnabledInConfig;
+  const preservedCuratorInitNames = swarmState.curatorInitAgentNames;
+  const preservedCuratorPhaseNames = swarmState.curatorPhaseAgentNames;
+  resetSwarmState();
+  swarmState.opencodeClient = preservedClient;
+  swarmState.fullAutoEnabledInConfig = preservedFullAutoFlag;
+  swarmState.curatorInitAgentNames = preservedCuratorInitNames;
+  swarmState.curatorPhaseAgentNames = preservedCuratorPhaseNames;
   if (pruneErrors.length > 0) {
     warnings.push(`Could not prune ${pruneErrors.length} branch(es) (unmerged or checked out): ${pruneErrors.join(", ")}`);
   }
@@ -47632,17 +47810,21 @@ When exploring a codebase area, systematically report all four dimensions:
 - State management approach (global, module-level, passed through)
 - Configuration pattern (env vars, config files, hardcoded)
 
-### RISKS
-- Files with high cyclomatic complexity or deep nesting
-- Circular dependencies
-- Missing error handling paths
-- Dead code or unreachable branches
+### COMPLEXITY INDICATORS
+- High cyclomatic complexity, deep nesting, or complex control flow
+- Large files (>500 lines) with many exported symbols
+- Deep inheritance hierarchies or complex type hierarchies
+
+### RUNTIME/BEHAVIORAL CONCERNS
+- Missing error handling paths or single-throw patterns
 - Platform-specific assumptions (path separators, line endings, OS APIs)
 
-### RELEVANT CONTEXT FOR TASK
-- Existing tests that cover this area (paths and what they test)
-- Related documentation files
-- Similar implementations elsewhere in the codebase that should be consistent
+### RELEVANT CONSTRAINTS
+- Architectural patterns observed (layered architecture, event-driven, microservice, etc.)
+- Error handling coverage patterns observed in the codebase
+- Platform-specific assumptions observed in the codebase
+- Established conventions (naming patterns, error handling approaches, testing strategies)
+- Configuration management approaches (env vars, config files, feature flags)
 
 OUTPUT FORMAT (MANDATORY \u2014 deviations will be rejected):
 Begin directly with PROJECT. Do NOT prepend "Here's my analysis..." or any conversational preamble.
@@ -47653,16 +47835,41 @@ FRAMEWORK: [if any]
 
 STRUCTURE:
 [key directories, 5-10 lines max]
+Example:
+src/agents/     \u2014 agent factories and definitions
+src/tools/       \u2014 CLI tool implementations
+src/config/      \u2014 plan schema and constants
 
 KEY FILES:
 - [path]: [purpose]
+Example:
+src/agents/explorer.ts \u2014 explorer agent factory and all prompt definitions
+src/agents/architect.ts \u2014 architect orchestrator with all mode handlers
 
 PATTERNS: [observations]
+Example: Factory pattern for agent creation; Result type for error handling; Module-level state via closure
+
+COMPLEXITY INDICATORS:
+[structural complexity concerns: elevated cyclomatic complexity, deep nesting, large files, deep inheritance hierarchies, or similar \u2014 describe what is OBSERVED]
+Example: explorer.ts (289 lines, 12 exports); architect.ts (complex branching in mode handlers)
+
+OBSERVED CHANGES:
+[if INPUT referenced specific files/changes: what changed in those targets; otherwise "none" or "general exploration"]
+
+CONSUMERS_AFFECTED:
+[if integration impact mode: list files that import/use the changed symbols; otherwise "not applicable"]
+
+RELEVANT CONSTRAINTS:
+[architectural patterns, error handling coverage patterns, platform-specific assumptions, established conventions observed in the codebase]
+Example: Layered architecture (agents \u2192 tools \u2192 filesystem); Bun-native path handling; Error-first callbacks in hooks
 
 DOMAINS: [relevant SME domains: powershell, security, python, etc.]
+Example: typescript, nodejs, cli-tooling, powershell
 
-REVIEW NEEDED:
-- [path]: [why, which SME]
+FOLLOW-UP CANDIDATE AREAS:
+- [path]: [observable condition, relevant domain]
+Example:
+src/tools/declare-scope.ts \u2014 function has 12 parameters, consider splitting; tool-authoring
 
 ## INTEGRATION IMPACT ANALYSIS MODE
 Activates when delegated with "Integration impact analysis" or INPUT lists contract changes.
@@ -47678,10 +47885,15 @@ OUTPUT FORMAT (MANDATORY \u2014 deviations will be rejected):
 Begin directly with BREAKING_CHANGES. Do NOT prepend conversational preamble.
 
 BREAKING_CHANGES: [list with affected consumer files, or "none"]
+Example: src/agents/explorer.ts \u2014 removed createExplorerAgent export (was used by 3 files)
 COMPATIBLE_CHANGES: [list, or "none"]
+Example: src/config/constants.ts \u2014 added new optional field to Config interface
 CONSUMERS_AFFECTED: [list of files that import/use changed exports, or "none"]
-VERDICT: BREAKING | COMPATIBLE
-MIGRATION_NEEDED: [yes \u2014 description of required caller updates | no]
+Example: src/agents/coder.ts, src/agents/reviewer.ts, src/main.ts
+COMPATIBILITY SIGNALS: [COMPATIBLE | INCOMPATIBLE | UNCERTAIN \u2014 based on observable contract changes]
+Example: INCOMPATIBLE \u2014 removeExport changes function arity from 3 to 2
+MIGRATION_SURFACE: [yes \u2014 list of observable call signatures affected | no \u2014 no observable impact detected]
+Example: yes \u2014 createExplorerAgent(model, customPrompt?, customAppendPrompt?) \u2192 createExplorerAgent(model)
 
 ## DOCUMENTATION DISCOVERY MODE
 Activates automatically during codebase reality check at plan ingestion.
@@ -47727,8 +47939,8 @@ PROJECT_CONTEXT: [context.md excerpt]
 ACTIONS:
 - Read the prior summary to understand session history
 - Cross-reference knowledge entries against project context
-- Identify contradictions (knowledge says X, project state shows Y)
-- Recommend rewrites for verbose or stale lessons
+- Note contradictions (knowledge says X, project state shows Y)
+- Observe where lessons could be tighter or stale
 - Produce a concise briefing for the architect
 
 RULES:
@@ -47744,13 +47956,13 @@ BRIEFING:
 CONTRADICTIONS:
 - [entry_id]: [description] (or "None detected")
 
-KNOWLEDGE_UPDATES:
-- promote <uuid>: <reason>       (boost confidence, mark hive_eligible)
-- archive <uuid>: <reason>       (mark as archived \u2014 no longer injected)
-- rewrite <uuid>: <new lesson text>  (replace verbose/stale lesson with tighter version, max 280 chars)
-- flag_contradiction <uuid>: <reason>  (tag as contradicted)
-- promote new: <new lesson text>   (add a brand-new entry)
-Use the UUID from KNOWLEDGE_ENTRIES when archiving, rewriting, or flagging an existing entry. Use "new" only when recommending a brand-new entry.
+OBSERVATIONS:
+- entry <uuid> appears high-confidence: [observable evidence]  (suggests boost confidence, mark hive_eligible)
+- entry <uuid> appears stale: [observable evidence]  (suggests archive \u2014 no longer injected)
+- entry <uuid> could be tighter: [what's verbose or duplicate]  (suggests rewrite with tighter version, max 280 chars)
+- entry <uuid> contradicts project state: [observable conflict]  (suggests tag as contradicted)
+- new candidate: [concise lesson text from observed patterns]  (suggests new entry)
+Use the UUID from KNOWLEDGE_ENTRIES when observing about existing entries. Use "new candidate" only when observing a potential new entry.
 
 KNOWLEDGE_STATS:
 - Entries reviewed: [N]
@@ -47772,14 +47984,15 @@ KNOWLEDGE_ENTRIES: [JSON array of existing entries with UUIDs]
 
 ACTIONS:
 - Extend the prior digest with this phase's outcomes (do NOT regenerate from scratch)
-- Identify workflow deviations: missing reviewer, missing retro, skipped test_engineer
-- Recommend knowledge updates: entries to promote, archive, rewrite, or flag as contradicted
+- Observe workflow deviations: missing reviewer, missing retro, skipped test_engineer
+- Report knowledge update candidates with observable evidence: entries that appear promoted, archived, rewritten, or contradicted
 - Summarize key decisions and blockers resolved
 
 RULES:
 - Output under 2000 chars
 - No code modifications
 - Compliance observations are READ-ONLY \u2014 report, do not enforce
+- OBSERVATIONS should not contain directives \u2014 report what is observed, do not instruct the architect what to do
 - Extend the digest, never replace it
 
 OUTPUT FORMAT:
@@ -47792,15 +48005,15 @@ key_decisions: [list]
 blockers_resolved: [list]
 
 COMPLIANCE:
-- [type]: [description] (or "No deviations observed")
+- [type] observed: [description] (or "No deviations observed")
 
-KNOWLEDGE_UPDATES:
-- promote <uuid>: <reason>       (boost confidence, mark hive_eligible)
-- archive <uuid>: <reason>       (mark as archived \u2014 no longer injected)
-- rewrite <uuid>: <new lesson text>  (replace verbose/stale lesson with tighter version, max 280 chars)
-- flag_contradiction <uuid>: <reason>  (tag as contradicted)
-- promote new: <new lesson text>   (add a brand-new entry)
-Use the UUID from KNOWLEDGE_ENTRIES when archiving, rewriting, or flagging an existing entry. Use "new" only when recommending a brand-new entry.
+OBSERVATIONS:
+- entry <uuid> appears high-confidence: [observable evidence]  (suggests boost confidence, mark hive_eligible)
+- entry <uuid> appears stale: [observable evidence]  (suggests archive \u2014 no longer injected)
+- entry <uuid> could be tighter: [what's verbose or duplicate]  (suggests rewrite with tighter version, max 280 chars)
+- entry <uuid> contradicts project state: [observable conflict]  (suggests tag as contradicted)
+- new candidate: [concise lesson text from observed patterns]  (suggests new entry)
+Use the UUID from KNOWLEDGE_ENTRIES when observing about existing entries. Use "new candidate" only when observing a potential new entry.
 
 EXTENDED_DIGEST:
 [the full running digest with this phase appended]
@@ -47816,7 +48029,7 @@ ${customAppendPrompt}`;
   }
   return {
     name: "explorer",
-    description: "Fast codebase discovery and analysis. Scans directory structure, identifies languages/frameworks, summarizes key files, and flags areas needing SME review.",
+    description: "Fast codebase discovery and analysis. Scans directory structure, identifies languages/frameworks, summarizes key files, and identifies areas where specialized domain knowledge may be beneficial.",
     config: {
       model,
       temperature: 0.1,
@@ -47838,7 +48051,7 @@ init_utils2();
 var DEFAULT_CURATOR_LLM_TIMEOUT_MS = 300000;
 function parseKnowledgeRecommendations(llmOutput) {
   const recommendations = [];
-  const section = llmOutput.match(/KNOWLEDGE_UPDATES:\s*\n([\s\S]*?)(?:\n\n|\n[A-Z_]+:|$)/);
+  const section = llmOutput.match(/OBSERVATIONS:\s*\n([\s\S]*?)(?:\n\n|\n[A-Z_]+:|$)/);
   if (!section)
     return recommendations;
   const lines = section[1].split(`
@@ -47847,19 +48060,33 @@ function parseKnowledgeRecommendations(llmOutput) {
     const trimmed = line.trim();
     if (!trimmed.startsWith("-"))
       continue;
-    const match = trimmed.match(/^-\s+(promote|archive|flag_contradiction|rewrite)\s+(\S+):\s+(.+)$/i);
-    if (match) {
-      const action = match[1].toLowerCase();
-      const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-      const entryId = match[2] === "new" || !UUID_V4.test(match[2]) ? undefined : match[2];
-      const reason = match[3].trim();
-      recommendations.push({
-        action,
-        entry_id: entryId,
-        lesson: reason,
-        reason
-      });
-    }
+    const match = trimmed.match(/^-\s+entry\s+(\S+)\s+\(([^)]+)\):\s+(.+)$/i);
+    if (!match)
+      continue;
+    const uuid8 = match[1];
+    const parenthetical = match[2];
+    const text = match[3].trim().replace(/\s+\([^)]+\)$/, "");
+    const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    const entryId = uuid8 === "new" || !UUID_V4.test(uuid8) ? undefined : uuid8;
+    let action = "rewrite";
+    const lowerParenthetical = parenthetical.toLowerCase();
+    if (lowerParenthetical.includes("suggests boost confidence") || lowerParenthetical.includes("mark hive_eligible") || lowerParenthetical.includes("appears high-confidence")) {
+      action = "promote";
+    } else if (lowerParenthetical.includes("suggests archive") || lowerParenthetical.includes("appears stale")) {
+      action = "archive";
+    } else if (lowerParenthetical.includes("contradicts project state")) {
+      action = "flag_contradiction";
+    } else if (lowerParenthetical.includes("suggests rewrite") || lowerParenthetical.includes("could be tighter")) {
+      action = "rewrite";
+    } else if (lowerParenthetical.includes("new candidate")) {
+      action = "promote";
+    }
+    recommendations.push({
+      action,
+      entry_id: entryId,
+      lesson: text,
+      reason: text
+    });
   }
   return recommendations;
 }
@@ -52925,6 +53152,20 @@ You THINK. Subagents DO. You have the largest context window and strongest reaso
 - Never pass raw files - summarize relevant parts
 - Never assume subagents remember prior context
 
+## EXPLORER ROLE BOUNDARIES (Phase 2+)
+Explorer is strictly a FACTUAL MAPPER \u2014 it observes and reports. It does NOT make judgments, verdicts, routing decisions, or enforcement actions.
+
+Explorer outputs (COMPLEXITY INDICATORS, FOLLOW-UP CANDIDATE AREAS, DOMAINS, etc.) are CANDIDATE EVIDENCE. As Architect, YOU decide what to use, how to route, and what to prioritize.
+
+Explorer should NEVER be treated as:
+- A verdict authority (its signals are informational, not binding)
+- A routing oracle (SME nominations and domain hints are suggestions, not assignments)
+- A compliance enforcer (workflow observations are read-only reports)
+
+The architect makes dispatch and routing decisions. Explorer provides facts.
+
+SPEED PRESERVATION: This change improves explorer precision by narrowing its job to factual mapping \u2014 it does NOT reduce explorer usage. All existing explorer calls and workflows remain intact. The goal is better signal quality, not fewer calls.
+
 ## RULES
 
 NAMESPACE RULE: "Phase N" and "Task N.M" ALWAYS refer to the PROJECT PLAN in .swarm/plan.md.
@@ -53271,7 +53512,7 @@ OUTPUT: Test file + VERDICT: PASS/FAIL
 {{AGENT_PREFIX}}explorer
 TASK: Integration impact analysis
 INPUT: Contract changes detected: [list from diff tool]
-OUTPUT: BREAKING_CHANGES + COMPATIBLE_CHANGES + CONSUMERS_AFFECTED + VERDICT: BREAKING/COMPATIBLE + MIGRATION_NEEDED
+OUTPUT: BREAKING_CHANGES + COMPATIBLE_CHANGES + CONSUMERS_AFFECTED + COMPATIBILITY SIGNALS: [COMPATIBLE | INCOMPATIBLE | UNCERTAIN] + MIGRATION_SURFACE: [yes \u2014 list of affected call signatures | no]
 CONSTRAINT: Read-only. use search to find imports/usages of changed exports.
 
 {{AGENT_PREFIX}}docs
@@ -53661,7 +53902,7 @@ All other gates: failure \u2192 return to coder. No self-fixes. No workarounds.
 5a-bis. **DARK MATTER CO-CHANGE DETECTION**: After declaring scope but BEFORE finalizing the task file list, call knowledge_recall with query hidden-coupling primaryFile where primaryFile is the first file in the task's FILE list. Extract primaryFile from the task's FILE list (first file = primary). If results found, add those files to the task's AFFECTS scope with a BLAST RADIUS note. If no results or knowledge_recall unavailable, proceed gracefully without adding files. This is advisory \u2014 the architect may exclude files from scope if they are unrelated to the current task. only after scope is declared.
 
 5b. {{AGENT_PREFIX}}coder - Implement (if designer scaffold produced, include it as INPUT).
-5c. Run \`diff\` tool. If \`hasContractChanges\` \u2192 {{AGENT_PREFIX}}explorer integration analysis. If VERDICT=BREAKING or MIGRATION_NEEDED=yes \u2192 coder retry. If VERDICT=COMPATIBLE and MIGRATION_NEEDED=no \u2192 proceed.
+5c. Run \`diff\` tool. If \`hasContractChanges\` \u2192 {{AGENT_PREFIX}}explorer integration analysis. If COMPATIBILITY SIGNALS=INCOMPATIBLE or MIGRATION_SURFACE=yes \u2192 coder retry. If COMPATIBILITY SIGNALS=COMPATIBLE and MIGRATION_SURFACE=no \u2192 proceed.
     \u2192 REQUIRED: Print "diff: [PASS | CONTRACT CHANGE \u2014 details]"
     5d. Run \`syntax_check\` tool. SYNTACTIC ERRORS \u2192 return to coder. NO ERRORS \u2192 proceed to placeholder_scan.
     \u2192 REQUIRED: Print "syntaxcheck: [PASS | FAIL \u2014 N errors]"
@@ -53757,6 +53998,14 @@ PRE-COMMIT RULE \u2014 Before ANY commit or push:
   If ANY box is unchecked: DO NOT COMMIT. Return to step 5b.
   There is no override. A commit without a completed QA gate is a workflow violation.
 
+## ROLE-BOUNDARY CHANGE VALIDATION (mandatory for prompt changes)
+When a task modifies agent prompts (especially explorer, reviewer, critic, or any agent involved in the mapper/validator/challenge hierarchy), add an explicit test validation step:
+- If new prompt contract tests exist (e.g., explorer-role-boundary.test.ts, explorer-consumer-contract.test.ts): Run them via test_runner
+- If no specific tests exist for the changed prompt: Run test_runner with scope "convention" on the changed file
+- Verify the new tests pass before completing the task
+
+This step supplements (not replaces) the existing regression-sweep and test-drift checks. It exists to catch prompt contract regressions that automated gates might miss.
+
 5o. \u26D4 TASK COMPLETION GATE \u2014 You MUST print this checklist with filled values before marking \u2713 in .swarm/plan.md:
   [TOOL] diff: PASS / SKIP \u2014 value: ___
   [TOOL] syntax_check: PASS \u2014 value: ___
@@ -54942,6 +55191,14 @@ DO NOT:
 
 Your unique value is catching LOGIC ERRORS, EDGE CASES, and SECURITY FLAWS that automated tools cannot detect. If your review only catches things a linter would catch, you are not adding value.
 
+## EXPLORER FINDINGS \u2014 VALIDATE BEFORE REPORTING
+Explorer agent outputs (from @mega_explorer) may contain observations labeled as REVIEW NEEDED, RISKS, VERDICT, BREAKING, COMPATIBLE, or similar judgment language. Treat these as CANDIDATE OBSERVATIONS, not established facts.
+- BEFORE including any issue-like finding from explorer input in your final report: READ the relevant code yourself and verify the issue independently
+- Do NOT adopt the explorer's VERDICT, BREAKING, or COMPATIBLE labels as your own \u2014 you must reach your own conclusion
+- Explorer's RISKS section names potential concerns \u2014 you determine if they are actual issues through your own review
+- If explorer suggests "REVIEW NEEDED" for an area, treat it as a hint to look there, not as a confirmed problem
+- Your verdict must reflect YOUR verification, not the explorer's framing
+
 DO (explicitly):
 - READ the changed files yourself \u2014 do not rely on the coder's self-report
 - VERIFY imports exist: if the coder added a new import, use search to verify the export exists in the source
@@ -65609,15 +65866,13 @@ async function executeDeclareScope(args2, fallbackDir) {
       errors: [`Task ${args2.taskId} does not exist in plan.json`]
     };
   }
-  for (const [_sessionId, session] of swarmState.agentSessions) {
-    const taskState = getTaskState(session, args2.taskId);
-    if (taskState === "complete") {
-      return {
-        success: false,
-        message: `Task ${args2.taskId} is already completed`,
-        errors: [`Cannot declare scope for completed task ${args2.taskId}`]
-      };
-    }
+  const taskInPlan = allTasks.find((t) => t.id === args2.taskId);
+  if (taskInPlan && taskInPlan.status === "completed") {
+    return {
+      success: false,
+      message: `Task ${args2.taskId} is already completed`,
+      errors: [`Cannot declare scope for completed task ${args2.taskId}`]
+    };
   }
   const rawMergedFiles = [...args2.files, ...args2.whitelist ?? []];
   const warnings = [];
@@ -69562,6 +69817,10 @@ var DEFAULT_STRING_PATTERNS = [
   },
   { pattern: /`[^`]*\bstub\b[^`]*`/i, rule_id: "placeholder/text-placeholder" }
 ];
+var FILE_ALLOWLIST = [
+  "src/tools/declare-scope.ts",
+  "src/tools/placeholder-scan.ts"
+];
 var DEFAULT_CODE_PATTERNS = [
   {
     pattern: /throw\s+new\s+Error\s*\(\s*["'][^"']*\bTODO\b[^"']*["']\s*\)/i,
@@ -69702,6 +69961,64 @@ function scanPlanFileForPlaceholders(content, filePath) {
   }
   return findings;
 }
+function isValidationPattern(lines, currentLineIdx) {
+  const currentLine = lines[currentLineIdx];
+  if (!/return\s+undefined\s*;/.test(currentLine)) {
+    return false;
+  }
+  const MAX_SEARCH_LINES = 50;
+  let jsdocContent = "";
+  let foundFunction = false;
+  const functionKeywords = /^(?:export\s+)?(?:async\s+)?function\s+\w+|^(?:export\s+)?(?:async\s+)?(?:\w+\s+)?\w+\s*\([^)]*\)\s*(?::\s*\w+\s*)?(?:\{|$)/;
+  for (let i2 = currentLineIdx - 1;i2 >= 0 && i2 >= currentLineIdx - MAX_SEARCH_LINES; i2--) {
+    const line = lines[i2].trim();
+    if (line.startsWith("*") || line.startsWith("*/")) {
+      const jsdocLine = line.replace(/^\*?\s?/, "").replace(/^\*\//, "");
+      jsdocContent = jsdocLine + `
+` + jsdocContent;
+    } else if (line.includes("*/")) {
+      break;
+    } else if (functionKeywords.test(line) || line.startsWith("function ")) {
+      foundFunction = true;
+      break;
+    } else if (line.length > 0 && !line.startsWith("//") && !line.startsWith("*")) {
+      break;
+    }
+  }
+  if (jsdocContent) {
+    const returnsPattern = /@returns\s*(?:\{[^}]*\})?\s*(?:undefined|[A-Za-z_]\w*)/i;
+    if (returnsPattern.test(jsdocContent)) {
+      return true;
+    }
+  }
+  let braceCount = 0;
+  let inFunction = false;
+  for (let i2 = currentLineIdx;i2 >= 0; i2--) {
+    const line = lines[i2];
+    for (const char of line) {
+      if (char === "{") {
+        braceCount++;
+        inFunction = true;
+      } else if (char === "}") {
+        braceCount--;
+      }
+    }
+    if (inFunction && braceCount === 0 && i2 < currentLineIdx) {
+      break;
+    }
+  }
+  const errorReturnPattern = /return\s+["'`][[:ascii:]]*["'`]\s*;/;
+  for (let i2 = currentLineIdx - 1;i2 >= 0 && i2 >= currentLineIdx - MAX_SEARCH_LINES; i2--) {
+    const line = lines[i2].trim();
+    if (functionKeywords.test(line) || line.startsWith("function ")) {
+      break;
+    }
+    if (errorReturnPattern.test(line)) {
+      return true;
+    }
+  }
+  return false;
+}
 function scanWithRegex(content, filePath, denyPatterns) {
   const findings = [];
   const lines = content.split(`
@@ -69761,6 +70078,11 @@ function scanWithRegex(content, filePath, denyPatterns) {
     for (const { pattern, rule_id } of denyPatterns.code) {
       const isTestLike = line.includes("describe(") || line.includes("it(") || line.includes("test(") || line.includes("expect(");
       if (!isTestLike && pattern.test(line)) {
+        if (rule_id === "placeholder/code-stub-return" && /return\s+undefined\s*;/.test(line)) {
+          if (isValidationPattern(lines, i2)) {
+            continue;
+          }
+        }
         findings.push({
           path: filePath,
           line: lineNumber,
@@ -69868,6 +70190,10 @@ async function placeholderScan(input, directory) {
     if (isAllowedByGlobs(filePath, allow_globs)) {
       continue;
     }
+    const relativeFilePath = path65.relative(directory, fullPath).replace(/\\/g, "/");
+    if (FILE_ALLOWLIST.some((allowed) => relativeFilePath.endsWith(allowed))) {
+      continue;
+    }
     let content;
     try {
       const stat2 = fs52.statSync(fullPath);
@@ -71438,13 +71764,13 @@ function validatePath(inputPath, baseDir, workspaceDir) {
     resolved = path67.resolve(baseDir, inputPath);
   }
   const workspaceResolved = path67.resolve(workspaceDir);
-  let relative11;
+  let relative12;
   if (isWinAbs) {
-    relative11 = path67.win32.relative(workspaceResolved, resolved);
+    relative12 = path67.win32.relative(workspaceResolved, resolved);
   } else {
-    relative11 = path67.relative(workspaceResolved, resolved);
+    relative12 = path67.relative(workspaceResolved, resolved);
   }
-  if (relative11.startsWith("..")) {
+  if (relative12.startsWith("..")) {
     return "path traversal detected";
   }
   return null;
@@ -76026,6 +76352,8 @@ var update_task_status = createSwarmTool({
 // src/tools/write-drift-evidence.ts
 init_tool();
 init_utils2();
+init_ledger();
+init_manager();
 init_create_tool();
 import fs66 from "fs";
 import path79 from "path";
@@ -76093,11 +76421,40 @@ async function executeWriteDriftEvidence(args2, directory) {
     const tempPath = path79.join(evidenceDir, `.${filename}.tmp`);
     await fs66.promises.writeFile(tempPath, JSON.stringify(evidenceContent, null, 2), "utf-8");
     await fs66.promises.rename(tempPath, validatedPath);
+    let snapshotInfo;
+    let snapshotError;
+    if (normalizedVerdict === "approved") {
+      try {
+        const currentPlan = await loadPlanJsonOnly(directory);
+        if (currentPlan) {
+          const snapshotEvent = await takeSnapshotEvent(directory, currentPlan, {
+            source: "critic_approved",
+            approvalMetadata: {
+              phase,
+              verdict: "APPROVED",
+              summary: summary.trim(),
+              approved_at: new Date().toISOString()
+            }
+          });
+          snapshotInfo = {
+            seq: snapshotEvent.seq,
+            timestamp: snapshotEvent.timestamp
+          };
+        } else {
+          snapshotError = "plan.json not available for snapshot";
+        }
+      } catch (err2) {
+        snapshotError = err2 instanceof Error ? err2.message : String(err2);
+        console.warn("[write_drift_evidence] critic-approved snapshot failed:", snapshotError);
+      }
+    }
     return JSON.stringify({
       success: true,
       phase,
       verdict: normalizedVerdict,
-      message: `Drift evidence written to .swarm/evidence/${phase}/drift-verifier.json`
+      message: `Drift evidence written to .swarm/evidence/${phase}/drift-verifier.json`,
+      approvedSnapshot: snapshotInfo,
+      snapshotError
     }, null, 2);
   } catch (error93) {
     return JSON.stringify({