opencode-swarm 5.2.0 → 6.1.0

package/README.md

@@ -1,9 +1,9 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-5.2.0-blue" alt="Version">
+  <img src="https://img.shields.io/badge/version-6.0.0-blue" alt="Version">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
   <img src="https://img.shields.io/badge/opencode-plugin-purple" alt="OpenCode Plugin">
   <img src="https://img.shields.io/badge/agents-7-orange" alt="Agents">
-  <img src="https://img.shields.io/badge/tests-1101-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-1188-brightgreen" alt="Tests">
 </p>
 
 <h1 align="center">🐝 OpenCode Swarm</h1>
@@ -138,15 +138,24 @@ OpenCode Swarm:
 ┌─────────────────────────────────────────────────────────────────────────┐
 │  PHASE 5: Execute (per task)                                            │
 │                                                                         │
-│   ┌─────────┐    ┌────────────┐    ┌──────────────┐                    │
-│   │ @coder  │ →  │ @reviewer  │ →  │    @test     │                    │
-│   │ 1 task  │    │ check all  │    │ write + run  │                    │
-│   └─────────┘    └────────────┘    └──────────────┘                    │
-│        │               │                   │                            │
-│        │     If REJECTED: retry    If FAIL: fix + retest               │
-│        └───────────────┘                                                │
+│   ┌─────────┐    ┌───────┐    ┌────────────┐    ┌──────────────┐       │
+│   │ @coder  │ →  │ diff  │ →  │ @reviewer  │ →  │    @test     │       │
+│   │ 1 task  │    │ tool  │    │ check all  │    │ write + run  │       │
+│   └─────────┘    └───────┘    └────────────┘    └──────────────┘       │
+│        │              │             │                   │               │
+│        │    Contract   │   If REJECTED:        If FAIL: fix            │
+│        │    changes?   │   retry from coder    + retest                │
+│        │       │       │             │                                  │
+│        │       ▼       │             ▼                                  │
+│        │  ┌─────────┐  │   ┌──────────────┐    ┌──────────────┐       │
+│        │  │@explorer│  │   │  @reviewer   │ →  │    @test     │       │
+│        │  │ impact  │  │   │ security-only│    │ adversarial  │       │
+│        │  │analysis │  │   │   (if match) │    │   (attacks)  │       │
+│        │  └─────────┘  │   └──────────────┘    └──────────────┘       │
+│        │               │                                               │
+│        └───────────────┘                                               │
 │                                                                         │
-│   Update plan.md: [x] Task complete (only if PASS)                      │
+│   Update plan.md: [x] Task complete (only after ALL gates pass)        │
 │   Next task...                                                          │
 └─────────────────────────────────────────────────────────────────────────┘
                                     │
@@ -334,6 +343,13 @@ bunx opencode-swarm uninstall --clean
 
 ## What's New
 
+### v6.0.0 — Core QA & Security Gates
+- **Dual-pass security reviewer** — After the general reviewer APPROVES, the architect automatically triggers a second security-only review pass when the changed file matches security-sensitive paths (`auth`, `crypto`, `session`, `token`, `middleware`, `api`, `security`) or the coder's output contains security keywords. Configurable via `review_passes` config.
+- **Adversarial testing** — After verification tests PASS, the test engineer is re-delegated with adversarial-only framing: attack vectors, boundary violations, and injection attempts. Pure prompt engineering, no new infrastructure.
+- **Integration impact analysis** — After the coder completes, the `diff` tool detects contract changes (exported functions, interfaces, types). If found, the explorer runs impact analysis across dependents before review begins.
+- **`diff` tool** — New agent-accessible tool providing structured git diff with numstat parsing, contract change detection, configurable base ref (`HEAD`/staged/unstaged), path filtering, and 500-line truncation.
+- **87 new tests** — 1188 total tests across 53+ files (up from 1101 in v5.2.0).
+
 ### v5.2.0 — Per-Invocation Guardrails
 - **Per-invocation budget isolation** — Guardrail limits (tool calls, duration, errors) now reset with each agent delegation. Second invocation of the same agent gets a fresh budget, preventing false circuit breaker trips in long-running projects.
 - **Architect protocol enforcement** — New mandatory QA gate rules: every coder task must go through reviewer approval + test_engineer verification before the next coder task. Protocol violations detected at runtime with warning injection.
@@ -409,7 +425,7 @@ All features are opt-in via configuration. See [Installation Guide](docs/install
 ### ✅ Quality Assurance
 | Agent | Role |
 |-------|------|
-| `reviewer` | Combined correctness + security review. The architect specifies CHECK dimensions (security, correctness, edge-cases, performance, etc.) per call. |
+| `reviewer` | Dual-pass review: correctness review first, then automatic security-only pass for security-sensitive files. The architect specifies CHECK dimensions per call. OWASP Top 10 categories built in. |
 | `critic` | Plan review gate. Reviews the architect's plan BEFORE implementation — checks completeness, feasibility, scope, dependencies, and flags AI-slop. |
 
 ---
@@ -516,6 +532,38 @@ Override limits for specific agents that need more (or less) room:
 
 Profiles merge with base config — only specified fields are overridden.
 
+### Review Passes
+
+Control the dual-pass security review behavior:
+
+```jsonc
+{
+  "review_passes": {
+    "always_security_review": false,  // default: false (only on security-sensitive files)
+    "security_globs": [               // default patterns:
+      "**/*auth*", "**/*crypto*",
+      "**/*session*", "**/*token*",
+      "**/*middleware*", "**/*api*",
+      "**/*security*"
+    ]
+  }
+}
+```
+
+Set `always_security_review: true` to run the security pass on every task, regardless of file path.
+
+### Integration Analysis
+
+Control whether contract change detection triggers impact analysis:
+
+```jsonc
+{
+  "integration_analysis": {
+    "enabled": true  // default: true
+  }
+}
+```
+
 > **Architect is exempt/unlimited by default:** The architect agent has no guardrail limits by default. To override, add a `profiles.architect` entry in your guardrails config.
 
 ### Per-Invocation Budgets
@@ -549,7 +597,7 @@ This prevents long-running projects from accumulating session-wide counters that
 | Execution | Serial (predictable) | Parallel (chaotic) | Parallel | Configurable |
 | Planning | Phased with acceptance criteria | Ad-hoc | Role-based | Graph-based |
 | Memory | Persistent `.swarm/` files | Session only | Session only | Checkpoints |
-| QA | Per-task (unified review) | Optional | Optional | Manual |
+| QA | Dual-pass per-task (review + security + adversarial) | Optional | Optional | Manual |
 | Model mixing | Per-agent configuration | Limited | Limited | Manual |
 | Resume projects | ✅ Native | ❌ | ❌ | Partial |
 | SME domains | Open-domain (any) | Generic | Generic | Generic |
@@ -561,7 +609,7 @@ This prevents long-running projects from accumulating session-wide counters that
 
 1. **Plan before code** - Documented phases with acceptance criteria
 2. **One task at a time** - Focused work, quality output
-3. **Review everything immediately** - Correctness + security review per task, not per project
+3. **Review everything immediately** - Dual-pass review (correctness + security) with adversarial testing per task
 4. **Cache SME knowledge** - Don't re-ask answered questions
 5. **Persistent memory** - `.swarm/` files survive sessions
 6. **Serial execution** - Predictable, debuggable, no race conditions
@@ -582,7 +630,7 @@ bun test
 bun test tests/unit/config/schema.test.ts
 ```
 
-1101 tests across 48 files covering config, tools, agents, hooks, commands, state, guardrails, evidence, plan schemas, circuit breaker race conditions, invocation windows, and multi-invocation isolation. Uses Bun's built-in test runner — zero additional test dependencies.
+1188 tests across 53+ files covering config, tools, agents, hooks, commands, state, guardrails, evidence, plan schemas, circuit breaker race conditions, invocation windows, multi-invocation isolation, security categories, review/integration schemas, and diff tool. Uses Bun's built-in test runner — zero additional test dependencies.
 
 ## Troubleshooting
 

package/dist/agents/designer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './architect';
+export declare function createDesignerAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/agents/docs.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './architect';
+export declare function createDocsAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/agents/index.d.ts

@@ -19,7 +19,9 @@ export declare function getAgentConfigs(config?: PluginConfig): Record<string, S
 export { createArchitectAgent } from './architect';
 export { createCoderAgent } from './coder';
 export { createCriticAgent } from './critic';
+export { createDesignerAgent } from './designer';
+export { createDocsAgent } from './docs';
 export { createExplorerAgent } from './explorer';
-export { createReviewerAgent } from './reviewer';
+export { createReviewerAgent, SECURITY_CATEGORIES, type SecurityCategory, } from './reviewer';
 export { createSMEAgent } from './sme';
 export { createTestEngineerAgent } from './test-engineer';

package/dist/agents/reviewer.d.ts

@@ -1,2 +1,5 @@
 import type { AgentDefinition } from './architect';
+/** OWASP Top 10 2021 categories for security-focused review passes */
+export declare const SECURITY_CATEGORIES: readonly ["broken-access-control", "cryptographic-failures", "injection", "insecure-design", "security-misconfiguration", "vulnerable-components", "auth-failures", "data-integrity-failures", "logging-monitoring-failures", "ssrf"];
+export type SecurityCategory = (typeof SECURITY_CATEGORIES)[number];
 export declare function createReviewerAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/config/constants.d.ts

@@ -1,8 +1,8 @@
 export declare const QA_AGENTS: readonly ["reviewer", "critic"];
 export declare const PIPELINE_AGENTS: readonly ["explorer", "coder", "test_engineer"];
 export declare const ORCHESTRATOR_NAME: "architect";
-export declare const ALL_SUBAGENT_NAMES: readonly ["sme", "reviewer", "critic", "explorer", "coder", "test_engineer"];
-export declare const ALL_AGENT_NAMES: readonly ["architect", "sme", "reviewer", "critic", "explorer", "coder", "test_engineer"];
+export declare const ALL_SUBAGENT_NAMES: readonly ["sme", "docs", "designer", "reviewer", "critic", "explorer", "coder", "test_engineer"];
+export declare const ALL_AGENT_NAMES: readonly ["architect", "sme", "docs", "designer", "reviewer", "critic", "explorer", "coder", "test_engineer"];
 export type QAAgentName = (typeof QA_AGENTS)[number];
 export type PipelineAgentName = (typeof PIPELINE_AGENTS)[number];
 export type AgentName = (typeof ALL_AGENT_NAMES)[number];

package/dist/config/loader.d.ts

@@ -13,6 +13,8 @@ export declare function deepMerge<T extends Record<string, unknown>>(base?: T, o
  * 2. Project config: <directory>/.opencode/opencode-swarm.json
  *
  * Project config takes precedence. Nested objects are deep-merged.
+ * IMPORTANT: Raw configs are merged BEFORE Zod parsing so that
+ * Zod defaults don't override explicit user values.
  */
 export declare function loadPluginConfig(directory: string): PluginConfig;
 /**

package/dist/config/schema.d.ts

@@ -128,6 +128,26 @@ export declare const SummaryConfigSchema: z.ZodObject<{
     retention_days: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type SummaryConfig = z.infer<typeof SummaryConfigSchema>;
+export declare const ReviewPassesConfigSchema: z.ZodObject<{
+    always_security_review: z.ZodDefault<z.ZodBoolean>;
+    security_globs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ReviewPassesConfig = z.infer<typeof ReviewPassesConfigSchema>;
+export declare const IntegrationAnalysisConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type IntegrationAnalysisConfig = z.infer<typeof IntegrationAnalysisConfigSchema>;
+export declare const DocsConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    doc_patterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type DocsConfig = z.infer<typeof DocsConfigSchema>;
+export declare const UIReviewConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    trigger_paths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    trigger_keywords: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type UIReviewConfig = z.infer<typeof UIReviewConfigSchema>;
 export declare const GuardrailsProfileSchema: z.ZodObject<{
     max_tool_calls: z.ZodOptional<z.ZodNumber>;
     max_duration_minutes: z.ZodOptional<z.ZodNumber>;
@@ -282,6 +302,23 @@ export declare const PluginConfigSchema: z.ZodObject<{
         max_stored_bytes: z.ZodDefault<z.ZodNumber>;
         retention_days: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
+    review_passes: z.ZodOptional<z.ZodObject<{
+        always_security_review: z.ZodDefault<z.ZodBoolean>;
+        security_globs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    integration_analysis: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    docs: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        doc_patterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    ui_review: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        trigger_paths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        trigger_keywords: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    _loadedFromFile: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 export type PluginConfig = z.infer<typeof PluginConfigSchema>;
 export type { AgentName, PipelineAgentName, QAAgentName, } from './constants';

package/dist/hooks/delegation-tracker.d.ts

@@ -8,7 +8,7 @@ import type { PluginConfig } from '../config/schema';
 /**
  * Creates the chat.message hook for delegation tracking.
  */
-export declare function createDelegationTrackerHook(config: PluginConfig): (input: {
+export declare function createDelegationTrackerHook(config: PluginConfig, guardrailsEnabled?: boolean): (input: {
     sessionID: string;
     agent?: string;
 }, output: Record<string, unknown>) => Promise<void>;

package/dist/index.js

@@ -13630,6 +13630,61 @@ var SummaryConfigSchema = exports_external.object({
   max_stored_bytes: exports_external.number().min(10240).max(104857600).default(10485760),
   retention_days: exports_external.number().min(1).max(365).default(7)
 });
+var ReviewPassesConfigSchema = exports_external.object({
+  always_security_review: exports_external.boolean().default(false),
+  security_globs: exports_external.array(exports_external.string()).default([
+    "**/auth/**",
+    "**/api/**",
+    "**/crypto/**",
+    "**/security/**",
+    "**/middleware/**",
+    "**/session/**",
+    "**/token/**"
+  ])
+});
+var IntegrationAnalysisConfigSchema = exports_external.object({
+  enabled: exports_external.boolean().default(true)
+});
+var DocsConfigSchema = exports_external.object({
+  enabled: exports_external.boolean().default(true),
+  doc_patterns: exports_external.array(exports_external.string()).default([
+    "README.md",
+    "CONTRIBUTING.md",
+    "docs/**/*.md",
+    "docs/**/*.rst",
+    "**/CHANGELOG.md"
+  ])
+});
+var UIReviewConfigSchema = exports_external.object({
+  enabled: exports_external.boolean().default(false),
+  trigger_paths: exports_external.array(exports_external.string()).default([
+    "**/pages/**",
+    "**/components/**",
+    "**/views/**",
+    "**/screens/**",
+    "**/ui/**",
+    "**/layouts/**"
+  ]),
+  trigger_keywords: exports_external.array(exports_external.string()).default([
+    "new page",
+    "new screen",
+    "new component",
+    "redesign",
+    "layout change",
+    "form",
+    "modal",
+    "dialog",
+    "dropdown",
+    "sidebar",
+    "navbar",
+    "dashboard",
+    "landing page",
+    "signup",
+    "login form",
+    "settings page",
+    "profile page"
+  ])
+});
 var GuardrailsProfileSchema = exports_external.object({
   max_tool_calls: exports_external.number().min(0).max(1000).optional(),
   max_duration_minutes: exports_external.number().min(0).max(480).optional(),
@@ -13674,6 +13729,16 @@ var DEFAULT_AGENT_PROFILES = {
     max_tool_calls: 200,
     max_duration_minutes: 30,
     warning_threshold: 0.65
+  },
+  docs: {
+    max_tool_calls: 200,
+    max_duration_minutes: 30,
+    warning_threshold: 0.75
+  },
+  designer: {
+    max_tool_calls: 150,
+    max_duration_minutes: 20,
+    warning_threshold: 0.75
   }
 };
 var DEFAULT_ARCHITECT_PROFILE = DEFAULT_AGENT_PROFILES.architect;
@@ -13729,7 +13794,12 @@ var PluginConfigSchema = exports_external.object({
   context_budget: ContextBudgetConfigSchema.optional(),
   guardrails: GuardrailsConfigSchema.optional(),
   evidence: EvidenceConfigSchema.optional(),
-  summaries: SummaryConfigSchema.optional()
+  summaries: SummaryConfigSchema.optional(),
+  review_passes: ReviewPassesConfigSchema.optional(),
+  integration_analysis: IntegrationAnalysisConfigSchema.optional(),
+  docs: DocsConfigSchema.optional(),
+  ui_review: UIReviewConfigSchema.optional(),
+  _loadedFromFile: exports_external.boolean().default(false)
 });
 
 // src/config/loader.ts
@@ -13739,25 +13809,26 @@ var MAX_CONFIG_FILE_BYTES = 102400;
 function getUserConfigDir() {
   return process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
 }
-function loadConfigFromPath(configPath) {
+function loadRawConfigFromPath(configPath) {
   try {
     const stats = fs.statSync(configPath);
     if (stats.size > MAX_CONFIG_FILE_BYTES) {
       console.warn(`[opencode-swarm] Config file too large (max 100 KB): ${configPath}`);
+      console.warn("[opencode-swarm] \u26A0\uFE0F Guardrails will be DISABLED as a safety precaution. Fix the config file to restore normal operation.");
       return null;
     }
     const content = fs.readFileSync(configPath, "utf-8");
     const rawConfig = JSON.parse(content);
-    const result = PluginConfigSchema.safeParse(rawConfig);
-    if (!result.success) {
-      console.warn(`[opencode-swarm] Invalid config at ${configPath}:`);
-      console.warn(result.error.format());
+    if (typeof rawConfig !== "object" || rawConfig === null || Array.isArray(rawConfig)) {
+      console.warn(`[opencode-swarm] Invalid config at ${configPath}: expected an object`);
+      console.warn("[opencode-swarm] \u26A0\uFE0F Guardrails will be DISABLED as a safety precaution. Fix the config file to restore normal operation.");
       return null;
     }
-    return result.data;
+    return rawConfig;
   } catch (error48) {
     if (error48 instanceof Error && "code" in error48 && error48.code !== "ENOENT") {
-      console.warn(`[opencode-swarm] Error reading config from ${configPath}:`, error48.message);
+      console.warn(`[opencode-swarm] \u26A0\uFE0F CONFIG LOAD FAILURE \u2014 config exists at ${configPath} but could not be loaded: ${error48.message}`);
+      console.warn("[opencode-swarm] \u26A0\uFE0F Guardrails will be DISABLED as a safety precaution. Fix the config file to restore normal operation.");
     }
     return null;
   }
@@ -13779,30 +13850,36 @@ function deepMergeInternal(base, override, depth) {
   }
   return result;
 }
-function deepMerge(base, override) {
-  if (!base)
-    return override;
-  if (!override)
-    return base;
-  return deepMergeInternal(base, override, 0);
-}
 function loadPluginConfig(directory) {
   const userConfigPath = path.join(getUserConfigDir(), "opencode", CONFIG_FILENAME);
   const projectConfigPath = path.join(directory, ".opencode", CONFIG_FILENAME);
-  let config2 = loadConfigFromPath(userConfigPath) ?? {
-    max_iterations: 5,
-    qa_retry_limit: 3,
-    inject_phase_reminders: true
-  };
-  const projectConfig = loadConfigFromPath(projectConfigPath);
-  if (projectConfig) {
-    config2 = {
-      ...config2,
-      ...projectConfig,
-      agents: deepMerge(config2.agents, projectConfig.agents)
+  const rawUserConfig = loadRawConfigFromPath(userConfigPath);
+  const rawProjectConfig = loadRawConfigFromPath(projectConfigPath);
+  const loadedFromFile = rawUserConfig !== null || rawProjectConfig !== null;
+  let mergedRaw = rawUserConfig ?? {};
+  if (rawProjectConfig) {
+    mergedRaw = deepMergeInternal(mergedRaw, rawProjectConfig, 0);
+  }
+  const result = PluginConfigSchema.safeParse(mergedRaw);
+  if (!result.success) {
+    if (rawUserConfig) {
+      const userResult = PluginConfigSchema.safeParse(rawUserConfig);
+      if (userResult.success) {
+        console.warn("[opencode-swarm] Project config ignored due to validation errors. Using user config.");
+        return { ...userResult.data, _loadedFromFile: true };
+      }
+    }
+    console.warn("[opencode-swarm] Merged config validation failed:");
+    console.warn(result.error.format());
+    console.warn("[opencode-swarm] \u26A0\uFE0F Guardrails will be DISABLED as a safety precaution. Fix the config file to restore normal operation.");
+    return {
+      max_iterations: 5,
+      qa_retry_limit: 3,
+      inject_phase_reminders: true,
+      _loadedFromFile: false
     };
   }
-  return config2;
+  return { ...result.data, _loadedFromFile: loadedFromFile };
 }
 function loadAgentPrompt(agentName) {
   const promptsDir = path.join(getUserConfigDir(), "opencode", PROMPTS_DIR_NAME);
@@ -13832,6 +13909,8 @@ var PIPELINE_AGENTS = ["explorer", "coder", "test_engineer"];
 var ORCHESTRATOR_NAME = "architect";
 var ALL_SUBAGENT_NAMES = [
   "sme",
+  "docs",
+  "designer",
   ...QA_AGENTS,
   ...PIPELINE_AGENTS
 ];
@@ -13847,6 +13926,8 @@ var DEFAULT_MODELS = {
   sme: "google/gemini-2.0-flash",
   reviewer: "google/gemini-2.0-flash",
   critic: "google/gemini-2.0-flash",
+  docs: "google/gemini-2.0-flash",
+  designer: "google/gemini-2.0-flash",
   default: "google/gemini-2.0-flash"
 };
 var DEFAULT_SCORING_CONFIG = {
@@ -13998,7 +14079,7 @@ var ARCHITECT_PROMPT = `You are Architect - orchestrator of a multi-agent swarm.
 ## IDENTITY
 
 Swarm: {{SWARM_ID}}
-Your agents: {{AGENT_PREFIX}}explorer, {{AGENT_PREFIX}}sme, {{AGENT_PREFIX}}coder, {{AGENT_PREFIX}}reviewer, {{AGENT_PREFIX}}critic, {{AGENT_PREFIX}}test_engineer
+Your agents: {{AGENT_PREFIX}}explorer, {{AGENT_PREFIX}}sme, {{AGENT_PREFIX}}coder, {{AGENT_PREFIX}}reviewer, {{AGENT_PREFIX}}critic, {{AGENT_PREFIX}}test_engineer, {{AGENT_PREFIX}}docs, {{AGENT_PREFIX}}designer
 
 ## ROLE
 
@@ -14021,17 +14102,18 @@ You THINK. Subagents DO. You have the largest context window and strongest reaso
    - If NEEDS_REVISION: Revise plan and re-submit to critic (max 2 cycles)
    - If REJECTED after 2 cycles: Escalate to user with explanation
    - ONLY AFTER critic approval: Proceed to implementation (Phase 3+)
-7. **MANDATORY QA GATE (Execute AFTER every coder task)**:
-   - Step A: {{AGENT_PREFIX}}coder completes implementation \u2192 STOP
-   - Step B: IMMEDIATELY delegate to {{AGENT_PREFIX}}reviewer with CHECK dimensions (security, correctness, edge-cases, etc.)
-   - Step C: Wait for reviewer verdict
-     - If VERDICT: REJECTED \u2192 Send FIXES back to {{AGENT_PREFIX}}coder (return to Step A)
-     - If VERDICT: APPROVED \u2192 Proceed to Step D
-   - Step D: IMMEDIATELY delegate to {{AGENT_PREFIX}}test_engineer to generate and run tests
-   - Step E: Wait for test verdict
-     - If VERDICT: FAIL \u2192 Send failure details back to {{AGENT_PREFIX}}coder (return to Step A)
-     - If VERDICT: PASS \u2192 Mark task complete, proceed to next task
-8. **NEVER skip the QA gate**: You cannot delegate to {{AGENT_PREFIX}}coder for a new task until the previous task passes BOTH reviewer approval AND test_engineer verification. The sequence is ALWAYS: coder \u2192 reviewer \u2192 test_engineer \u2192 next_coder.
+7. **MANDATORY QA GATE (Execute AFTER every coder task)** \u2014 sequence: coder \u2192 diff \u2192 review \u2192 security review \u2192 verification tests \u2192 adversarial tests \u2192 next task.
+   - After coder completes: run \`diff\` tool. If \`hasContractChanges\` is true \u2192 delegate {{AGENT_PREFIX}}explorer for integration impact analysis. BREAKING \u2192 return to coder. COMPATIBLE \u2192 proceed.
+   - Delegate {{AGENT_PREFIX}}reviewer with CHECK dimensions. REJECTED \u2192 return to coder (max {{QA_RETRY_LIMIT}} attempts). APPROVED \u2192 continue.
+   - If file matches security globs (auth, api, crypto, security, middleware, session, token) OR coder output contains security keywords \u2192 delegate {{AGENT_PREFIX}}reviewer AGAIN with security-only CHECK. REJECTED \u2192 return to coder.
+   - Delegate {{AGENT_PREFIX}}test_engineer for verification tests. FAIL \u2192 return to coder.
+   - Delegate {{AGENT_PREFIX}}test_engineer for adversarial tests (attack vectors only). FAIL \u2192 return to coder.
+   - All pass \u2192 mark task complete, proceed to next task.
+9. **UI/UX DESIGN GATE**: Before delegating UI tasks to {{AGENT_PREFIX}}coder, check if the task involves UI components. Trigger conditions (ANY match):
+   - Task description contains UI keywords: new page, new screen, new component, redesign, layout change, form, modal, dialog, dropdown, sidebar, navbar, dashboard, landing page, signup, login form, settings page, profile page
+   - Target file is in: pages/, components/, views/, screens/, ui/, layouts/
+   If triggered: delegate to {{AGENT_PREFIX}}designer FIRST to produce a code scaffold. Then pass the scaffold to {{AGENT_PREFIX}}coder as INPUT alongside the task. The coder implements the TODOs in the scaffold without changing component structure or accessibility attributes.
+   If not triggered: delegate directly to {{AGENT_PREFIX}}coder as normal.
 
 ## AGENTS
 
@@ -14041,9 +14123,13 @@ You THINK. Subagents DO. You have the largest context window and strongest reaso
 {{AGENT_PREFIX}}reviewer - Code review (correctness, security, and any other dimensions you specify)
 {{AGENT_PREFIX}}test_engineer - Test generation AND execution (writes tests, runs them, reports PASS/FAIL)
 {{AGENT_PREFIX}}critic - Plan review gate (reviews plan BEFORE implementation)
+{{AGENT_PREFIX}}docs - Documentation updates (README, API docs, guides \u2014 NOT .swarm/ files)
+{{AGENT_PREFIX}}designer - UI/UX design specs (scaffold generation for UI components \u2014 runs BEFORE coder on UI tasks)
 
 SMEs advise only. Reviewer and critic review only. None of them write code.
 
+Available Tools: diff (structured git diff with contract change detection)
+
 ## DELEGATION FORMAT
 
 All delegations use this structure:
@@ -14099,6 +14185,41 @@ PLAN: [paste the plan.md content]
 CONTEXT: [codebase summary from explorer]
 OUTPUT: VERDICT + CONFIDENCE + ISSUES + SUMMARY
 
+{{AGENT_PREFIX}}reviewer
+TASK: Security-only review of login validation
+FILE: src/auth/login.ts
+CHECK: [security-only] \u2014 evaluate against OWASP Top 10, scan for hardcoded secrets, injection vectors, insecure crypto, missing input validation
+OUTPUT: VERDICT + RISK + SECURITY ISSUES ONLY
+
+{{AGENT_PREFIX}}test_engineer
+TASK: Adversarial security testing
+FILE: src/auth/login.ts
+CONSTRAINT: ONLY attack vectors \u2014 malformed inputs, oversized payloads, injection attempts, auth bypass, boundary violations
+OUTPUT: Test file + VERDICT: PASS/FAIL
+
+{{AGENT_PREFIX}}explorer
+TASK: Integration impact analysis
+INPUT: Contract changes detected: [list from diff tool]
+OUTPUT: BREAKING CHANGES + CONSUMERS AFFECTED + VERDICT: BREAKING/COMPATIBLE
+CONSTRAINT: Read-only. grep for imports/usages of changed exports.
+
+{{AGENT_PREFIX}}docs
+TASK: Update documentation for Phase 2 changes
+FILES CHANGED: src/auth/login.ts, src/auth/session.ts, src/types/user.ts
+CHANGES SUMMARY:
+  - Added login() function with email/password authentication
+  - Added SessionManager class with create/revoke/refresh methods
+  - Added UserSession interface with refreshToken field
+DOC FILES: README.md, docs/api.md, docs/installation.md
+OUTPUT: Updated doc files + SUMMARY
+
+{{AGENT_PREFIX}}designer
+TASK: Design specification for user settings page
+CONTEXT: Users need to update profile info, change password, manage notification preferences. App uses React + Tailwind + shadcn/ui.
+FRAMEWORK: React (TSX)
+EXISTING PATTERNS: All forms use react-hook-form, validation with zod, toast notifications for success/error
+OUTPUT: Code scaffold for src/pages/Settings.tsx with component tree, typed props, layout, and accessibility
+
 ## WORKFLOW
 
 ### Phase 0: Resume Check
@@ -14150,21 +14271,24 @@ Delegate plan to {{AGENT_PREFIX}}critic for review BEFORE any implementation beg
 ### Phase 5: Execute
 For each task (respecting dependencies):
 
-5a. {{AGENT_PREFIX}}coder - Implement (MANDATORY)
-5b. {{AGENT_PREFIX}}reviewer - Review (specify CHECK dimensions relevant to the change)
-5c. **GATE - Check VERDICT:**
-    - **APPROVED** \u2192 Proceed to 5d
-    - **REJECTED** (attempt < {{QA_RETRY_LIMIT}}) \u2192 STOP. Send FIXES to {{AGENT_PREFIX}}coder with specific changes. Retry from 5a. Do NOT proceed to 5d.
-    - **REJECTED** (attempt {{QA_RETRY_LIMIT}}) \u2192 STOP. Escalate to user or handle directly.
-5d. {{AGENT_PREFIX}}test_engineer - Generate AND run tests (ONLY if 5c = APPROVED). Expect VERDICT: PASS/FAIL.
-5e. If test VERDICT is FAIL \u2192 Send failures to {{AGENT_PREFIX}}coder for fixes, then re-run from 5b.
-5f. Update plan.md [x], proceed to next task (ONLY if tests PASS)
+5a. **UI DESIGN GATE** (conditional \u2014 Rule 9): If task matches UI trigger \u2192 {{AGENT_PREFIX}}designer produces scaffold \u2192 pass scaffold to coder as INPUT. If no match \u2192 skip.
+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. BREAKING \u2192 coder retry.
+5d. {{AGENT_PREFIX}}reviewer - General review. REJECTED (< {{QA_RETRY_LIMIT}}) \u2192 coder retry. REJECTED ({{QA_RETRY_LIMIT}}) \u2192 escalate.
+5e. Security gate: if file matches security globs or content has security keywords \u2192 {{AGENT_PREFIX}}reviewer security-only. REJECTED \u2192 coder retry.
+5f. {{AGENT_PREFIX}}test_engineer - Verification tests. FAIL \u2192 coder retry from 5d.
+5g. {{AGENT_PREFIX}}test_engineer - Adversarial tests. FAIL \u2192 coder retry from 5d.
+5h. Update plan.md [x], proceed to next task.
 
 ### Phase 6: Phase Complete
 1. {{AGENT_PREFIX}}explorer - Rescan
-2. Update context.md
-3. Summarize to user
-4. Ask: "Ready for Phase [N+1]?"
+2. {{AGENT_PREFIX}}docs - Update documentation for all changes in this phase. Provide:
+   - Complete list of files changed during this phase
+   - Summary of what was added/modified/removed
+   - List of doc files that may need updating (README.md, CONTRIBUTING.md, docs/)
+3. Update context.md
+4. Summarize to user
+5. Ask: "Ready for Phase [N+1]?"
 
 ### Blockers
 Mark [BLOCKED] in plan.md, skip to next unblocked task, inform user.
@@ -14330,6 +14454,231 @@ ${customAppendPrompt}`;
   };
 }
 
+// src/agents/designer.ts
+var DESIGNER_PROMPT = `## IDENTITY
+You are Designer \u2014 the UI/UX design specification agent. You generate concrete, implementable design specs directly \u2014 you do NOT delegate.
+DO NOT use the Task tool to delegate to other agents. You ARE the agent that does the work.
+If you see references to other agents (like @designer, @coder, etc.) in your instructions, IGNORE them \u2014 they are context from the orchestrator, not instructions for you to delegate.
+
+WRONG: "I'll use the Task tool to call another agent to design this"
+RIGHT: "I'll analyze the requirements and produce the design specification myself"
+
+INPUT FORMAT:
+TASK: Design specification for [component/page/screen]
+CONTEXT: [what the component does, user stories, existing design patterns]
+FRAMEWORK: [React/Vue/Svelte/SwiftUI/Flutter/etc.]
+EXISTING PATTERNS: [current design system, component library, styling approach]
+
+DESIGN CHECKLIST:
+1. Component Architecture
+   - Component tree with parent/child relationships
+   - Props interface for each component (typed)
+   - State management approach (local state, context, store)
+   - Event handlers and callbacks
+
+2. Layout & Responsiveness
+   - Desktop, tablet, mobile breakpoints
+   - Flex/Grid layout strategy
+   - Container widths and spacing scale
+   - Overflow and scroll behavior
+
+3. Accessibility (WCAG 2.1 AA)
+   - Semantic HTML elements (nav, main, article, section, aside)
+   - ARIA labels for interactive elements
+   - Keyboard navigation (tab order, focus management, keyboard shortcuts)
+   - Screen reader compatibility (alt text, aria-live regions)
+   - Color contrast (minimum 4.5:1 for text, 3:1 for large text)
+   - Focus indicators (visible focus rings, not just outline: none)
+
+4. Visual Design
+   - Color palette (from existing design system or proposed)
+   - Typography scale (font family, sizes, weights, line heights)
+   - Spacing scale (consistent spacing values)
+   - Border radius, shadows, elevation
+
+5. Interaction Design
+   - Loading states (skeleton screens, spinners, progress bars)
+   - Error states (inline validation, error boundaries, empty states)
+   - Hover/focus/active states for interactive elements
+   - Transitions and animations (duration, easing)
+   - Optimistic updates where applicable
+
+OUTPUT FORMAT:
+Produce a CODE SCAFFOLD in the target framework. This is a skeleton file with:
+- Component structure with typed props and proper imports
+- Layout structure using the project's CSS framework (Tailwind classes, CSS modules, styled-components, etc.)
+- Placeholder TODO comments for business logic
+- Accessibility attributes (aria-*, role, tabIndex)
+- Responsive breakpoint classes/media queries
+- Named event handler stubs
+
+Example output structure:
+\`\`\`tsx
+// src/components/LoginForm.tsx
+// DESIGN SPEC \u2014 generated by Designer agent
+// Coder: implement TODO items, do not change component structure or accessibility attributes
+
+import { useState } from 'react';
+
+interface LoginFormProps {
+  onSubmit: (email: string, password: string) => Promise<void>;
+  onForgotPassword?: () => void;
+  isLoading?: boolean;
+  error?: string;
+}
+
+export function LoginForm({ onSubmit, onForgotPassword, isLoading, error }: LoginFormProps) {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-gray-50 px-4 sm:px-6 lg:px-8"
+         role="main">
+      <div className="w-full max-w-md space-y-8">
+        <div>
+          <h2 className="mt-6 text-center text-3xl font-bold tracking-tight text-gray-900">
+            {/* TODO: Use app name from config */}
+            Sign in to your account
+          </h2>
+        </div>
+        {error && (
+          <div role="alert" aria-live="polite"
+               className="rounded-md bg-red-50 p-4 text-sm text-red-800">
+            {error}
+          </div>
+        )}
+        <div className="mt-8 space-y-6">
+          <div className="space-y-4 rounded-md">
+            <div>
+              <label htmlFor="email" className="sr-only">Email address</label>
+              <input id="email" name="email" type="email" autoComplete="email" required
+                     aria-label="Email address"
+                     className="relative block w-full rounded-t-md border-0 py-1.5 text-gray-900 ring-1 ring-inset ring-gray-300 placeholder:text-gray-400 focus:z-10 focus:ring-2 focus:ring-inset focus:ring-indigo-600 sm:text-sm sm:leading-6"
+                     placeholder="Email address"
+                     value={email}
+                     onChange={(e) => setEmail(e.target.value)} />
+            </div>
+            {/* TODO: Password field with show/hide toggle */}
+            {/* TODO: Remember me checkbox */}
+          </div>
+          <div className="flex items-center justify-between">
+            {/* TODO: Forgot password link */}
+          </div>
+          <button type="submit" disabled={isLoading}
+                  aria-busy={isLoading}
+                  className="group relative flex w-full justify-center rounded-md bg-indigo-600 px-3 py-2 text-sm font-semibold text-white hover:bg-indigo-500 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-600 disabled:opacity-50">
+            {isLoading ? 'Signing in...' : 'Sign in'}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+\`\`\`
+
+RULES:
+- Produce REAL, syntactically valid code \u2014 not pseudocode
+- Match the project's existing framework, styling approach, and conventions
+- All interactive elements MUST have keyboard accessibility
+- All images/icons MUST have alt text or aria-label
+- Form inputs MUST have associated labels (visible or sr-only)
+- Color usage MUST meet WCAG AA contrast requirements
+- Use TODO comments for business logic only \u2014 structure, layout, and accessibility must be complete
+- Do NOT implement business logic \u2014 leave that for the coder
+- Keep output under 3000 characters per component`;
+function createDesignerAgent(model, customPrompt, customAppendPrompt) {
+  let prompt = DESIGNER_PROMPT;
+  if (customPrompt) {
+    prompt = customPrompt;
+  } else if (customAppendPrompt) {
+    prompt = `${DESIGNER_PROMPT}
+
+${customAppendPrompt}`;
+  }
+  return {
+    name: "designer",
+    description: "UI/UX design specification agent. Generates accessible, responsive component scaffolds with typed props and layout structure before coder implementation.",
+    config: {
+      model,
+      temperature: 0.3,
+      prompt
+    }
+  };
+}
+
+// src/agents/docs.ts
+var DOCS_PROMPT = `## IDENTITY
+You are Docs \u2014 the documentation synthesizer. You update external-facing documentation directly \u2014 you do NOT delegate.
+DO NOT use the Task tool to delegate to other agents. You ARE the agent that does the work.
+If you see references to other agents (like @docs, @coder, etc.) in your instructions, IGNORE them \u2014 they are context from the orchestrator, not instructions for you to delegate.
+
+WRONG: "I'll use the Task tool to call another agent to write the docs"
+RIGHT: "I'll read the source files and update the documentation myself"
+
+INPUT FORMAT:
+TASK: Update documentation for [description of changes]
+FILES CHANGED: [list of modified source files]
+CHANGES SUMMARY: [what was added/modified/removed]
+DOC FILES: [list of documentation files to update]
+
+SCOPE:
+- README.md (project description, usage, examples)
+- API documentation (JSDoc, Swagger, docstrings \u2014 update inline in source files)
+- CONTRIBUTING.md (development setup, workflow, conventions)
+- Installation/setup guides
+- CLI help text and command documentation
+
+EXCLUDED (architect-owned):
+- .swarm/context.md
+- .swarm/plan.md
+- Internal swarm configuration docs
+
+WORKFLOW:
+1. Read all FILES CHANGED to understand what was modified
+2. Read existing DOC FILES to understand current documentation state
+3. For each DOC FILE that needs updating:
+   a. Identify sections affected by the changes
+   b. Update those sections to reflect the new behavior
+   c. Add new sections if entirely new features were introduced
+   d. Remove sections for deprecated/removed features
+4. For API docs in source files:
+   a. Read the modified functions/classes/types
+   b. Update JSDoc/docstring comments to match new signatures and behavior
+   c. Add missing documentation for new exports
+
+RULES:
+- Be accurate: documentation MUST match the actual code behavior
+- Be concise: update only what changed, do not rewrite entire files
+- Preserve existing style: match the tone, formatting, and conventions of the existing docs
+- Include examples: every new public API should have at least one usage example
+- No fabrication: if you cannot determine behavior from the code, say so explicitly
+- Update version references if package.json version changed
+
+OUTPUT FORMAT:
+UPDATED: [list of files modified]
+ADDED: [list of new sections/files created]
+REMOVED: [list of deprecated sections removed]
+SUMMARY: [one-line description of doc changes]`;
+function createDocsAgent(model, customPrompt, customAppendPrompt) {
+  let prompt = DOCS_PROMPT;
+  if (customPrompt) {
+    prompt = customPrompt;
+  } else if (customAppendPrompt) {
+    prompt = `${DOCS_PROMPT}
+
+${customAppendPrompt}`;
+  }
+  return {
+    name: "docs",
+    description: "Documentation synthesizer. Updates README, API docs, and guides to reflect code changes after each phase.",
+    config: {
+      model,
+      temperature: 0.2,
+      prompt
+    }
+  };
+}
+
 // src/agents/explorer.ts
 var EXPLORER_PROMPT = `## IDENTITY
 You are Explorer. You analyze codebases directly \u2014 you do NOT delegate.
@@ -14664,6 +15013,18 @@ If you call @coder instead of @${swarmId}_coder, the call will FAIL or go to the
     testEngineer.name = prefixName("test_engineer");
     agents.push(applyOverrides(testEngineer, swarmAgents, swarmPrefix));
   }
+  if (!isAgentDisabled("docs", swarmAgents, swarmPrefix)) {
+    const docsPrompts = getPrompts("docs");
+    const docs = createDocsAgent(getModel("docs"), docsPrompts.prompt, docsPrompts.appendPrompt);
+    docs.name = prefixName("docs");
+    agents.push(applyOverrides(docs, swarmAgents, swarmPrefix));
+  }
+  if (pluginConfig?.ui_review?.enabled === true && !isAgentDisabled("designer", swarmAgents, swarmPrefix)) {
+    const designerPrompts = getPrompts("designer");
+    const designer = createDesignerAgent(getModel("designer"), designerPrompts.prompt, designerPrompts.appendPrompt);
+    designer.name = prefixName("designer");
+    agents.push(applyOverrides(designer, swarmAgents, swarmPrefix));
+  }
   return agents;
 }
 function createAgents(config2) {
@@ -16828,7 +17189,7 @@ ${originalText}`;
   };
 }
 // src/hooks/delegation-tracker.ts
-function createDelegationTrackerHook(config2) {
+function createDelegationTrackerHook(config2, guardrailsEnabled = true) {
   return async (input, _output) => {
     const now = Date.now();
     if (!input.agent || input.agent === "") {
@@ -16850,7 +17211,7 @@ function createDelegationTrackerHook(config2) {
     const isArchitect = strippedAgent === ORCHESTRATOR_NAME;
     const session = ensureAgentSession(input.sessionID, agentName);
     session.delegationActive = !isArchitect;
-    if (!isArchitect) {
+    if (!isArchitect && guardrailsEnabled) {
       beginInvocation(input.sessionID, agentName);
     }
     if (config2.hooks?.delegation_tracker === true && previousAgent && previousAgent !== agentName) {
@@ -17025,18 +17386,11 @@ function createGuardrailsHooks(config2) {
         return;
       }
       const lastMessage = messages[messages.length - 1];
-      let sessionId = lastMessage.info?.sessionID;
-      let targetWindow = sessionId ? getActiveWindow(sessionId) : undefined;
-      if (!targetWindow || !targetWindow.warningIssued && !targetWindow.hardLimitHit) {
-        for (const [id] of swarmState.agentSessions) {
-          const window = getActiveWindow(id);
-          if (window && (window.warningIssued || window.hardLimitHit)) {
-            targetWindow = window;
-            sessionId = id;
-            break;
-          }
-        }
+      const sessionId = lastMessage.info?.sessionID;
+      if (!sessionId) {
+        return;
       }
+      const targetWindow = getActiveWindow(sessionId);
       if (!targetWindow || !targetWindow.warningIssued && !targetWindow.hardLimitHit) {
         return;
       }
@@ -17244,6 +17598,18 @@ function createSystemEnhancerHook(config2, directory) {
             }
           }
           tryInject("[SWARM HINT] Large tool outputs may be auto-summarized. Use /swarm retrieve <id> to get the full content if needed.");
+          if (config2.review_passes?.always_security_review) {
+            tryInject("[SWARM CONFIG] Security review pass is MANDATORY for ALL tasks. Skip file-pattern check \u2014 always run security-only reviewer pass after general review APPROVED.");
+          }
+          if (config2.integration_analysis?.enabled === false) {
+            tryInject("[SWARM CONFIG] Integration analysis is DISABLED. Skip diff tool and integration impact analysis after coder tasks.");
+          }
+          if (config2.ui_review?.enabled) {
+            tryInject("[SWARM CONFIG] UI/UX Designer agent is ENABLED. For tasks matching UI trigger keywords or file paths, delegate to designer BEFORE coder (Rule 9).");
+          }
+          if (config2.docs?.enabled === false) {
+            tryInject("[SWARM CONFIG] Docs agent is DISABLED. Skip docs delegation in Phase 6.");
+          }
           return;
         }
         const userScoringConfig = config2.context_budget?.scoring;
@@ -17323,6 +17689,50 @@ function createSystemEnhancerHook(config2, directory) {
             }
           }
         }
+        if (config2.review_passes?.always_security_review) {
+          const text = "[SWARM CONFIG] Security review pass is MANDATORY for ALL tasks. Skip file-pattern check \u2014 always run security-only reviewer pass after general review APPROVED.";
+          candidates.push({
+            id: `candidate-${idCounter++}`,
+            kind: "phase",
+            text,
+            tokens: estimateTokens(text),
+            priority: 1,
+            metadata: { contentType: "prose" }
+          });
+        }
+        if (config2.integration_analysis?.enabled === false) {
+          const text = "[SWARM CONFIG] Integration analysis is DISABLED. Skip diff tool and integration impact analysis after coder tasks.";
+          candidates.push({
+            id: `candidate-${idCounter++}`,
+            kind: "phase",
+            text,
+            tokens: estimateTokens(text),
+            priority: 1,
+            metadata: { contentType: "prose" }
+          });
+        }
+        if (config2.ui_review?.enabled) {
+          const text = "[SWARM CONFIG] UI/UX Designer agent is ENABLED. For tasks matching UI trigger keywords or file paths, delegate to designer BEFORE coder (Rule 9).";
+          candidates.push({
+            id: `candidate-${idCounter++}`,
+            kind: "phase",
+            text,
+            tokens: estimateTokens(text),
+            priority: 1,
+            metadata: { contentType: "prose" }
+          });
+        }
+        if (config2.docs?.enabled === false) {
+          const text = "[SWARM CONFIG] Docs agent is DISABLED. Skip docs delegation in Phase 6.";
+          candidates.push({
+            id: `candidate-${idCounter++}`,
+            kind: "phase",
+            text,
+            tokens: estimateTokens(text),
+            priority: 1,
+            metadata: { contentType: "prose" }
+          });
+        }
         const ranked = rankCandidates(candidates, effectiveConfig);
         for (const candidate of ranked) {
           if (injectedTokens + candidate.tokens > maxInjectionTokens) {
@@ -17517,6 +17927,9 @@ function createToolSummarizerHook(config2, directory) {
     }
   };
 }
+// src/tools/diff.ts
+import { execSync } from "child_process";
+
 // node_modules/@opencode-ai/plugin/node_modules/zod/v4/classic/external.js
 var exports_external2 = {};
 __export(exports_external2, {
@@ -29837,7 +30250,149 @@ function tool(input) {
   return input;
 }
 tool.schema = exports_external2;
-
+// src/tools/diff.ts
+var MAX_DIFF_LINES = 500;
+var DIFF_TIMEOUT_MS = 30000;
+var MAX_BUFFER_BYTES = 5 * 1024 * 1024;
+var CONTRACT_PATTERNS = [
+  /^[+-]\s*export\s+(function|const|class|interface|type|enum|default)\b/,
+  /^[+-]\s*(interface|type)\s+\w+/,
+  /^[+-]\s*public\s+/,
+  /^[+-]\s*(async\s+)?function\s+\w+\s*\(/
+];
+var SAFE_REF_PATTERN = /^[a-zA-Z0-9._\-/~^@{}]+$/;
+var MAX_REF_LENGTH = 256;
+var MAX_PATH_LENGTH = 500;
+var SHELL_METACHARACTERS = /[;|&$`(){}<>!'"]/;
+function validateBase(base) {
+  if (base.length > MAX_REF_LENGTH) {
+    return `base ref exceeds maximum length of ${MAX_REF_LENGTH}`;
+  }
+  if (!SAFE_REF_PATTERN.test(base)) {
+    return "base contains invalid characters for git ref";
+  }
+  return null;
+}
+function validatePaths(paths) {
+  if (!paths)
+    return null;
+  for (const path7 of paths) {
+    if (!path7 || path7.length === 0) {
+      return "empty path not allowed";
+    }
+    if (path7.length > MAX_PATH_LENGTH) {
+      return `path exceeds maximum length of ${MAX_PATH_LENGTH}`;
+    }
+    if (SHELL_METACHARACTERS.test(path7)) {
+      return "path contains shell metacharacters";
+    }
+  }
+  return null;
+}
+var diff = tool({
+  description: "Analyze git diff for changed files, exports, interfaces, and function signatures. Returns structured output with contract change detection.",
+  args: {
+    base: tool.schema.string().optional().describe('Base ref to diff against (default: HEAD). Use "staged" for staged changes, "unstaged" for working tree changes.'),
+    paths: tool.schema.array(tool.schema.string()).optional().describe("Optional file paths to restrict diff scope.")
+  },
+  async execute(args, _context) {
+    try {
+      const base = args.base ?? "HEAD";
+      const pathSpec = args.paths?.length ? "-- " + args.paths.join(" ") : "";
+      const baseValidationError = validateBase(base);
+      if (baseValidationError) {
+        const errorResult = {
+          error: `invalid base: ${baseValidationError}`,
+          files: [],
+          contractChanges: [],
+          hasContractChanges: false
+        };
+        return JSON.stringify(errorResult, null, 2);
+      }
+      const pathsValidationError = validatePaths(args.paths);
+      if (pathsValidationError) {
+        const errorResult = {
+          error: `invalid paths: ${pathsValidationError}`,
+          files: [],
+          contractChanges: [],
+          hasContractChanges: false
+        };
+        return JSON.stringify(errorResult, null, 2);
+      }
+      let gitCmd;
+      if (base === "staged") {
+        gitCmd = "git --no-pager diff --cached";
+      } else if (base === "unstaged") {
+        gitCmd = "git --no-pager diff";
+      } else {
+        gitCmd = `git --no-pager diff ${base}`;
+      }
+      const numstatOutput = execSync(gitCmd + " --numstat " + pathSpec, {
+        encoding: "utf-8",
+        timeout: DIFF_TIMEOUT_MS
+      });
+      const fullDiffOutput = execSync(gitCmd + " -U3 " + pathSpec, {
+        encoding: "utf-8",
+        timeout: DIFF_TIMEOUT_MS,
+        maxBuffer: MAX_BUFFER_BYTES
+      });
+      const files = [];
+      const numstatLines = numstatOutput.split(`
+`);
+      for (const line of numstatLines) {
+        if (!line.trim())
+          continue;
+        const parts = line.split("\t");
+        if (parts.length >= 3) {
+          const additions = parseInt(parts[0]) || 0;
+          const deletions = parseInt(parts[1]) || 0;
+          const path7 = parts[2];
+          files.push({ path: path7, additions, deletions });
+        }
+      }
+      const contractChanges = [];
+      const diffLines = fullDiffOutput.split(`
+`);
+      let currentFile = "";
+      for (const line of diffLines) {
+        const gitLineMatch = line.match(/^diff --git.* b\/(.+)$/);
+        if (gitLineMatch) {
+          currentFile = gitLineMatch[1];
+        }
+        for (const pattern of CONTRACT_PATTERNS) {
+          if (pattern.test(line)) {
+            const trimmed = line.trim();
+            if (currentFile) {
+              contractChanges.push(`[${currentFile}] ${trimmed}`);
+            } else {
+              contractChanges.push(trimmed);
+            }
+            break;
+          }
+        }
+      }
+      const hasContractChanges = contractChanges.length > 0;
+      const fileCount = files.length;
+      const truncated = diffLines.length > MAX_DIFF_LINES;
+      const summary = truncated ? `${fileCount} files changed. Contract changes: ${hasContractChanges ? "YES" : "NO"}. (truncated to ${MAX_DIFF_LINES} lines)` : `${fileCount} files changed. Contract changes: ${hasContractChanges ? "YES" : "NO"}`;
+      const result = {
+        files,
+        contractChanges,
+        hasContractChanges,
+        summary
+      };
+      return JSON.stringify(result, null, 2);
+    } catch (e) {
+      const errorResult = {
+        error: e instanceof Error ? `git diff failed: ${e.constructor.name}` : "git diff failed: unknown error",
+        files: [],
+        contractChanges: [],
+        hasContractChanges: false
+      };
+      return JSON.stringify(errorResult, null, 2);
+    }
+  }
+});
 // src/tools/domain-detector.ts
 var DOMAIN_PATTERNS = {
   windows: [
@@ -30222,9 +30777,10 @@ var OpenCodeSwarm = async (ctx) => {
   const contextBudgetHandler = createContextBudgetHandler(config3);
   const commandHandler = createSwarmCommandHandler(ctx.directory, Object.fromEntries(agentDefinitions.map((agent) => [agent.name, agent])));
   const activityHooks = createAgentActivityHooks(config3, ctx.directory);
-  const delegationHandler = createDelegationTrackerHook(config3);
   const delegationGateHandler = createDelegationGateHook(config3);
-  const guardrailsConfig = GuardrailsConfigSchema.parse(config3.guardrails ?? {});
+  const guardrailsFallback = config3._loadedFromFile ? config3.guardrails ?? {} : { ...config3.guardrails, enabled: false };
+  const guardrailsConfig = GuardrailsConfigSchema.parse(guardrailsFallback);
+  const delegationHandler = createDelegationTrackerHook(config3, guardrailsConfig.enabled);
   const guardrailsHooks = createGuardrailsHooks(guardrailsConfig);
   const summaryConfig = SummaryConfigSchema.parse(config3.summaries ?? {});
   const toolSummarizerHook = createToolSummarizerHook(summaryConfig, ctx.directory);
@@ -30251,7 +30807,8 @@ var OpenCodeSwarm = async (ctx) => {
     tool: {
       detect_domains,
       extract_code_blocks,
-      gitingest
+      gitingest,
+      diff
     },
     config: async (opencodeConfig) => {
       if (!opencodeConfig.agent) {

package/dist/tools/diff.d.ts

@@ -0,0 +1,18 @@
+import { tool } from '@opencode-ai/plugin';
+export interface DiffResult {
+    files: Array<{
+        path: string;
+        additions: number;
+        deletions: number;
+    }>;
+    contractChanges: string[];
+    hasContractChanges: boolean;
+    summary: string;
+}
+export interface DiffErrorResult {
+    error: string;
+    files: [];
+    contractChanges: [];
+    hasContractChanges: false;
+}
+export declare const diff: ReturnType<typeof tool>;

package/dist/tools/index.d.ts

@@ -1,3 +1,4 @@
+export { type DiffErrorResult, type DiffResult, diff } from './diff';
 export { detect_domains } from './domain-detector';
 export { extract_code_blocks } from './file-extractor';
-export { gitingest, fetchGitingest, type GitingestArgs } from './gitingest';
+export { fetchGitingest, type GitingestArgs, gitingest } from './gitingest';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "5.2.0",
+	"version": "6.1.0",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",