wogiflow 2.11.0 → 2.12.0

package/.claude/docs/explore-agents.md

@@ -226,6 +226,41 @@ Return:
 
 **Blast-radius artifact**: Results are persisted to `.workflow/state/blast-radius-{taskId}.json` for use by downstream gates (context estimator, standards compliance, workspace dispatch).
 
+## MCP Capability Injection (Pre-Launch)
+
+Before launching agents, inject MCP capability hints so agents can leverage available MCP tools (CC 2.1.101+ — sub-agents inherit MCP tools from parent session).
+
+**Step 1**: Check if capabilities are classified:
+```bash
+node scripts/flow-mcp-capabilities.js check-cache
+```
+
+**Step 2**: If `cache-miss` AND you have MCP tools available (tools starting with `mcp__` in your tool catalog):
+1. Inspect your available `mcp__*` tools
+2. For each tool, classify it into a capability category using the category definitions:
+   ```bash
+   node scripts/flow-mcp-capabilities.js categories
+   ```
+3. Cache the classifications:
+   ```bash
+   node scripts/flow-mcp-capabilities.js cache '<json>'
+   ```
+   Format: `{ "server-name": { "tools": [{ "name": "mcp__server__tool", "description": "...", "category": "category-id" }] } }`
+
+**Step 3**: For each agent, get its role-specific hint and append to the agent prompt:
+```bash
+node scripts/flow-mcp-capabilities.js hint explore-codebase    # Agent 1
+node scripts/flow-mcp-capabilities.js hint explore-practices   # Agent 2
+node scripts/flow-mcp-capabilities.js hint explore-versions    # Agent 3
+node scripts/flow-mcp-capabilities.js hint explore-risk        # Agent 4
+node scripts/flow-mcp-capabilities.js hint explore-standards   # Agent 5
+node scripts/flow-mcp-capabilities.js hint explore-impact      # Agent 6
+```
+
+If the hint is non-empty, append it to the agent's prompt. If empty (no relevant MCP tools for that role), skip — the agent works fine without them.
+
+**Skip when**: No MCP servers configured (`node scripts/flow-mcp-capabilities.js discover` returns empty), or `config.mcpCapabilities.enabled` is false.
+
 ## Launching
 
 All agents launch in parallel as `Agent(subagent_type=Explore)` calls in a single message. When `config.hybrid.enabled`, use the `model` parameter on each Agent call to route by task type:

package/lib/workspace.js

@@ -717,20 +717,25 @@ grep -l '"from": "<repo-name>"' .workspace/messages/*.json 2>/dev/null
 4. If no message after 30s, check the worker's \`ready.json\` for task status
 5. Once message arrives, read it and present the results to the user
 
-**Message format** (what workers write automatically):
+**Message format** (what workers write automatically via the task-completed hook):
 \`\`\`json
 {
-  "id": "msg-XXXXXXXX",
+  "id": "msg-<taskId>-<timestamp>",
   "from": "<repo-name>",
   "to": "manager",
   "type": "task-complete",
   "subject": "Task completed: <title>",
-  "body": "**Task**: ...\\n**Files changed**: ...\\n**Summary**: ...",
+  "body": "**Task**: ...\\n**Files changed**: ...\\n**Verification evidence**: ...",
   "taskId": "wf-XXXXXXXX",
-  "status": "pending"
+  "status": "pending",
+  "verified": true,
+  "evidenceTier": "Tier 3 (INTERACTIVE)|Tier 2 (OBSERVATIONAL)|unknown",
+  "timestamp": "ISO-8601"
 }
 \`\`\`
 
+**Trust model**: Messages with \`"verified": true\` went through WogiFlow's quality gates (gate latch check). Freeform curl messages from workers are progress reports, not verified completions — investigate if a worker reports "done" via curl but no structured task-complete message arrives.
+
 **After reading a result**: Present the findings to the user. If the task requires follow-up (e.g., bug investigation found the issue in the other repo), dispatch the fix to the appropriate worker.
 
 **You are the SINGLE interface for the user.** They should never need to look at worker terminals. Read the messages, synthesize, and present.
@@ -1128,17 +1133,21 @@ This is NON-OPTIONAL. Every channel-dispatched task MUST end with a reply to the
 **Talk to PEERS directly** (do NOT go through the manager) when you need:
 - API shape/endpoint details from the other repo ("What does POST /customers return?")
 - Data model clarifications ("Does the Invoice entity have a lineItems relation?")
+- **Test credentials or accounts** ("Do you have E2E login credentials?" / "Can you create a test admin user?")
+- **Shared resources** ("Can you expose a test API token?" / "What's the connection string for staging?")
 - Coordination on shared types or contracts
 - Confirmation that the other side is ready for integration
 - Any technical question that the other repo can answer from its codebase
 
+Peers can not only ANSWER questions — they can CREATE resources you need (test accounts, API tokens, seed data, environment configs).
+
 **Talk to the MANAGER** (which means the user) only when:
 - You have **results to report** (task completed, investigation findings)
 - You need a **user decision** (design choice, product question, approval)
-- You are **stuck** and no peer can help
+- You are **stuck** and no peer can help (after trying Steps 1-2 below)
 - You need to **escalate** something the user should know about
 
-**Rule**: If a peer can answer your question, ask the peer. Do NOT route technical questions through the manager — the manager doesn't read source code and will just relay your question to the peer anyway. Cut out the middleman.
+**Rule**: If a peer can answer your question or create what you need, go to the peer. Do NOT route through the manager — the manager doesn't read source code and will just relay your question anyway. Cut out the middleman.
 
 **Peer channels:**
 ${peerNames.map(p => `- **${p}**: \`curl -s -X POST http://localhost:${channelMembers[p]?.port || '???'} -H "X-Wogi-From: ${name}" -d "your question"\``).join('\n')}
@@ -1152,15 +1161,37 @@ You are a workspace worker. There is NO human watching your terminal. You MUST o
 - **Auto-approve all reviews**: If /wogi-review asks for fix options, choose Option 1 (fix all) automatically.
 - **Never ask clarifying questions**: If something is ambiguous, make a reasonable decision and note it in your reply to the manager.
 
-### When to Escalate to Manager
+### CRITICAL: Stop, Don't Degrade
+
+**If you cannot verify your work to the required evidence tier, you may NOT mark the task as complete.** Report it as BLOCKED with the specific verification gap.
+
+- If browser verification is required but you can't log in → BLOCKED (not done)
+- If API testing is required but the server is unreachable → BLOCKED (not done)
+- If you need credentials you don't have → resolve via Steps 1-2 below, then continue. If unresolvable → BLOCKED.
+
+**Overnight runs STOP when verification is impossible.** Never degrade quality to keep the queue moving. A blocked task with honest status is infinitely better than a "completed" task that doesn't work.
+
+### When You're Blocked — Resolution Protocol
+
+**Step 1: Self-resolve** — check \`.workspace/state/\` for credentials, configs, tokens, test accounts, and any other shared resources. Also check \`.workspace/messages/\` for prior conversations where the resource may have been mentioned.
+
+**Step 2: Ask peers** — peers can CREATE what you need (test accounts, API tokens, seed data). Send a direct request:
+\`curl -s -X POST http://localhost:{peer_port} -H "X-Wogi-From: ${name}" -d "I need E2E test credentials. Do you have them, or can you create a test admin account?"\`
+
+**Step 3: ONLY THEN escalate** to the manager, including what you already tried:
+
+To escalate: \`curl -s -X POST http://localhost:${config.channels.managerPort || (config.channels.basePort - 1)} -H "X-Wogi-From: ${name}" -d "## Need Decision: [problem]
+Checked .workspace/state/: [what was found]
+Asked peers: [who, what response]
+Why this needs the owner: [explanation]"\`
+
+### When to Escalate (After Steps 1-2)
 
 Only send a question to the manager (instead of results) when:
-- The task requires a **design decision** that could go multiple ways (e.g., "should we use REST or GraphQL?")
+- The task requires a **design decision** that could go multiple ways
 - The task would **break an API contract** that other repos depend on
 - The task requires **deleting user data** or making irreversible changes
-- You are genuinely **stuck** and cannot proceed
-
-To escalate: \`curl -s -X POST http://localhost:${config.channels.managerPort || (config.channels.basePort - 1)} -H "X-Wogi-From: ${name}" -d "## Need Decision: [describe the choice and options]"\`
+- Steps 1-2 failed and you are genuinely **stuck**
 
 For everything else — just do the work and report results.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wogiflow",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "AI-powered development workflow management system with multi-model support",
   "main": "lib/index.js",
   "bin": {

package/scripts/flow-mcp-capabilities.js

@@ -0,0 +1,617 @@
+#!/usr/bin/env node
+
+/**
+ * Wogi Flow - MCP Capability Discovery for Sub-Agents
+ *
+ * Discovers available MCP servers, classifies their tools into generic
+ * capability categories, and generates role-specific prompt fragments
+ * so sub-agents know what MCP tools they have and when to use them.
+ *
+ * Design: The script handles discovery, taxonomy, caching, and formatting.
+ * The AI orchestrator handles classification (only it can see tool catalogs
+ * at runtime). Classifications are cached per session.
+ *
+ * Source: CC 2.1.101 — sub-agents now inherit MCP tools from parent session,
+ * but need awareness of what's available and when to use each tool.
+ *
+ * Usage:
+ *   node flow-mcp-capabilities.js check-cache
+ *   node flow-mcp-capabilities.js categories
+ *   node flow-mcp-capabilities.js roles
+ *   node flow-mcp-capabilities.js hint <role>
+ *   node flow-mcp-capabilities.js cache '<json>'
+ *   node flow-mcp-capabilities.js clear
+ *   node flow-mcp-capabilities.js discover
+ *   node flow-mcp-capabilities.js classify-prompt
+ *
+ * Programmatic:
+ *   const { getCapabilityCategories, getRoleCapabilities, generateHint } = require('./flow-mcp-capabilities');
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { PATHS, getConfig, safeJsonParse, readJson, writeJson, fileExists } = require('./flow-utils');
+
+// Prototype pollution protection — same pattern as flow-plugin-registry.js
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+// ============================================================
+// Constants
+// ============================================================
+
+const CACHE_PATH = path.join(PATHS.state, 'mcp-capabilities.json');
+
+/**
+ * Generic capability categories.
+ * Each category is defined by its PURPOSE, not by any specific MCP server.
+ * The `keywords` array is used by the AI orchestrator as guidance when
+ * classifying MCP tools — tools whose names or descriptions match these
+ * keywords likely belong to this category.
+ */
+const DEFAULT_CATEGORIES = {
+  'documentation-lookup': {
+    description: 'Fetch library, framework, or API documentation',
+    keywords: ['docs', 'library', 'resolve', 'reference', 'documentation', 'get-library', 'api-docs', 'man-page'],
+    agentGuidance: 'When you need current API docs, migration guides, or framework-specific patterns. Prefer over web search for library documentation — results are more accurate and structured.'
+  },
+  'browser-interaction': {
+    description: 'Navigate web pages, take screenshots, evaluate DOM, interact with UI elements',
+    keywords: ['navigate', 'screenshot', 'browser', 'evaluate', 'click', 'page', 'dom', 'tab', 'scroll', 'type'],
+    agentGuidance: 'When you need to verify UI behavior, inspect rendered output, or test user interactions in a browser.'
+  },
+  'design-files': {
+    description: 'Read or interact with design tools and design systems',
+    keywords: ['figma', 'design', 'component', 'frame', 'style', 'layout', 'variant', 'token', 'sketch'],
+    agentGuidance: 'When you need to inspect design specifications, extract design tokens, or verify UI implementations against design files.'
+  },
+  'code-execution': {
+    description: 'Execute or evaluate code in a sandboxed environment',
+    keywords: ['execute', 'eval', 'run', 'sandbox', 'repl', 'notebook', 'kernel', 'interpret'],
+    agentGuidance: 'When you need to test code snippets, evaluate expressions, or run scripts in an isolated environment.'
+  },
+  'data-query': {
+    description: 'Query databases, data stores, or structured data sources',
+    keywords: ['query', 'sql', 'database', 'table', 'schema', 'select', 'collection', 'index', 'record'],
+    agentGuidance: 'When you need to inspect database schemas, run queries, or verify data integrity.'
+  },
+  'communication': {
+    description: 'Send messages or notifications to external services',
+    keywords: ['send', 'message', 'slack', 'email', 'notify', 'post', 'channel', 'webhook', 'chat'],
+    agentGuidance: 'When you need to notify team members, post updates, or send messages to external communication channels.'
+  },
+  'file-management': {
+    description: 'Manage files in external storage or cloud systems',
+    keywords: ['upload', 'download', 'storage', 'bucket', 's3', 'blob', 'drive', 'sync', 'transfer'],
+    agentGuidance: 'When you need to upload, download, or manage files in cloud storage or external file systems.'
+  },
+  'code-analysis': {
+    description: 'Static analysis, AST inspection, linting, or code intelligence',
+    keywords: ['lint', 'ast', 'analyze', 'parse', 'syntax', 'diagnostic', 'symbol', 'definition', 'reference'],
+    agentGuidance: 'When you need deeper code analysis beyond grep — AST-level queries, cross-reference lookups, or structured code intelligence.'
+  },
+  'project-management': {
+    description: 'Interact with project management tools (issues, boards, sprints)',
+    keywords: ['issue', 'ticket', 'sprint', 'board', 'jira', 'linear', 'project', 'backlog', 'assignee', 'transition'],
+    agentGuidance: 'When you need to read or update project management state — issues, sprint boards, or task tracking.'
+  },
+  'version-control': {
+    description: 'Interact with version control platforms beyond local git',
+    keywords: ['pull-request', 'pr', 'merge', 'branch', 'commit', 'review', 'diff', 'release', 'tag'],
+    agentGuidance: 'When you need to interact with remote version control — PRs, code reviews, or release management.'
+  }
+};
+
+/**
+ * Role-to-capability mapping.
+ * Each agent role lists which capability categories would enhance its work.
+ * The orchestrator uses this to filter relevant MCP tools for each sub-agent.
+ */
+const DEFAULT_ROLE_CAPABILITIES = {
+  'explore-codebase': ['code-analysis', 'documentation-lookup'],
+  'explore-practices': ['documentation-lookup'],
+  'explore-versions': ['documentation-lookup'],
+  'explore-risk': ['code-analysis'],
+  'explore-standards': ['code-analysis'],
+  'explore-impact': ['code-analysis'],
+  'review-code': ['code-analysis', 'browser-interaction'],
+  'review-security': ['code-analysis'],
+  'review-architecture': ['code-analysis', 'documentation-lookup'],
+  'review-performance': ['code-analysis'],
+  'verify-ui': ['browser-interaction', 'design-files'],
+  'verify-api': ['data-query'],
+  'skeptical-evaluator': ['code-analysis', 'browser-interaction'],
+  'bug-investigation': ['code-analysis', 'browser-interaction', 'data-query'],
+  'onboard-stack': ['documentation-lookup'],
+  'general': ['documentation-lookup', 'code-analysis']
+};
+
+// ============================================================
+// Configuration
+// ============================================================
+
+/**
+ * Get MCP capabilities config, merging defaults with user overrides.
+ */
+function getMcpCapabilitiesConfig() {
+  const config = getConfig();
+  const userConfig = config.mcpCapabilities || {};
+  return {
+    enabled: userConfig.enabled !== false, // default: true
+    categoryOverrides: userConfig.categoryOverrides || {},
+    roleOverrides: userConfig.roleOverrides || {}
+  };
+}
+
+/**
+ * Get capability categories with user overrides applied.
+ */
+function getCapabilityCategories() {
+  const config = getMcpCapabilitiesConfig();
+  return { ...DEFAULT_CATEGORIES, ...config.categoryOverrides };
+}
+
+/**
+ * Get role-to-capability mapping with user overrides applied.
+ */
+function getRoleCapabilities(role) {
+  const config = getMcpCapabilitiesConfig();
+  const roles = { ...DEFAULT_ROLE_CAPABILITIES, ...config.roleOverrides };
+  return roles[role] || roles['general'] || [];
+}
+
+/**
+ * Get all role definitions.
+ */
+function getAllRoles() {
+  const config = getMcpCapabilitiesConfig();
+  return { ...DEFAULT_ROLE_CAPABILITIES, ...config.roleOverrides };
+}
+
+// ============================================================
+// MCP Server Discovery
+// ============================================================
+
+/**
+ * Discover all configured MCP servers from settings files and .mcp.json.
+ * Returns server names only — never includes config (may contain API keys).
+ *
+ * NOTE: This intentionally duplicates some discovery logic from flow-plugin-registry.js
+ * (scanUnregisteredMcpServers). The divergences are deliberate:
+ * - This function includes .mcp.json (CC 2.1.50+ canonical location); the registry doesn't
+ * - This function includes ~/.claude/settings.json (user-level); the registry is project-only
+ * - This function skips the internalPatterns filter (we want ALL servers for capability hints)
+ * If these divergences cause issues, extract shared logic into flow-utils.js.
+ *
+ * @returns {string[]} Array of MCP server names
+ */
+function discoverMcpServers() {
+  const servers = new Set();
+
+  // Check .mcp.json (project-level MCP config, CC 2.1.50+)
+  const mcpJsonPath = path.join(PATHS.root, '.mcp.json');
+  if (fileExists(mcpJsonPath)) {
+    try {
+      const mcpJson = safeJsonParse(mcpJsonPath, {});
+      const mcpServers = mcpJson.mcpServers || {};
+      for (const name of Object.keys(mcpServers)) {
+        servers.add(name);
+      }
+    } catch (_err) { /* silently skip */ }
+  }
+
+  // Check .claude/settings.local.json and .claude/settings.json
+  const settingsLocations = [
+    path.join(PATHS.root, '.claude', 'settings.local.json'),
+    path.join(PATHS.root, '.claude', 'settings.json')
+  ];
+
+  for (const settingsPath of settingsLocations) {
+    if (!fileExists(settingsPath)) continue;
+    try {
+      const settings = safeJsonParse(settingsPath, {});
+      const mcpServers = settings.mcpServers || {};
+      for (const name of Object.keys(mcpServers)) {
+        servers.add(name);
+      }
+    } catch (_err) { /* silently skip */ }
+  }
+
+  // Check user-level settings (~/.claude/settings.json)
+  const homePath = process.env.HOME || process.env.USERPROFILE;
+  if (homePath) {
+    const userSettingsPath = path.join(homePath, '.claude', 'settings.json');
+    if (fileExists(userSettingsPath)) {
+      try {
+        const userSettings = safeJsonParse(userSettingsPath, {});
+        const mcpServers = userSettings.mcpServers || {};
+        for (const name of Object.keys(mcpServers)) {
+          servers.add(name);
+        }
+      } catch (_err) { /* silently skip */ }
+    }
+  }
+
+  return [...servers];
+}
+
+// ============================================================
+// Cache Management
+// ============================================================
+
+/**
+ * Read cached MCP capability classifications.
+ *
+ * @returns {{ classifications: Object, cachedAt: string, sessionId: string } | null}
+ */
+function getCachedClassifications() {
+  if (!fileExists(CACHE_PATH)) return null;
+
+  try {
+    const cached = readJson(CACHE_PATH, null);
+    if (!cached || !cached.classifications) return null;
+    return cached;
+  } catch (_err) {
+    return null;
+  }
+}
+
+/**
+ * Cache MCP capability classifications.
+ *
+ * Expected input format:
+ * {
+ *   "server-name": {
+ *     "tools": [
+ *       { "name": "mcp__server__tool_name", "description": "What it does", "category": "documentation-lookup" }
+ *     ]
+ *   }
+ * }
+ *
+ * Validates input for prototype pollution and enforces length limits on tool
+ * name/description to prevent prompt injection via cache poisoning.
+ *
+ * @param {Object} classifications - Server-to-tool classifications
+ */
+function cacheClassifications(classifications) {
+  if (typeof classifications !== 'object' || classifications === null || Array.isArray(classifications)) {
+    return false;
+  }
+
+  // Sanitize: reject dangerous keys, enforce length limits on tool fields
+  const sanitized = {};
+  for (const [serverName, serverData] of Object.entries(classifications)) {
+    if (DANGEROUS_KEYS.has(serverName)) continue;
+    if (typeof serverData !== 'object' || serverData === null) continue;
+
+    const tools = Array.isArray(serverData.tools) ? serverData.tools : [];
+    sanitized[serverName] = {
+      tools: tools.map(tool => ({
+        name: String(tool.name || '').slice(0, 120),
+        description: String(tool.description || '').slice(0, 200).replace(/`/g, "'"),
+        category: String(tool.category || '').slice(0, 50)
+      })).filter(t => t.name && t.category)
+    };
+  }
+
+  const data = {
+    version: 1,
+    cachedAt: new Date().toISOString(),
+    classifications: sanitized
+  };
+
+  try {
+    writeJson(CACHE_PATH, data);
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+/**
+ * Clear the classification cache.
+ */
+function clearCache() {
+  try {
+    if (fileExists(CACHE_PATH)) {
+      fs.unlinkSync(CACHE_PATH);
+    }
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+// ============================================================
+// Prompt Generation
+// ============================================================
+
+/**
+ * Generate a capability-aware prompt fragment for a specific agent role.
+ *
+ * @param {string} role - Agent role (e.g., 'explore-codebase', 'review-code')
+ * @param {Object} [classifications] - Cached classifications (auto-loaded if omitted)
+ * @returns {string} Prompt fragment to append to agent prompt, or empty string if no relevant capabilities
+ */
+function generateHint(role, classifications) {
+  const config = getMcpCapabilitiesConfig();
+  if (!config.enabled) return '';
+
+  const cached = classifications || getCachedClassifications();
+  if (!cached) return '';
+
+  const classificationData = cached.classifications || cached;
+  const neededCapabilities = getRoleCapabilities(role);
+  if (!neededCapabilities || neededCapabilities.length === 0) return '';
+
+  const categories = getCapabilityCategories();
+  const neededSet = new Set(neededCapabilities);
+
+  // Collect tools grouped by capability category
+  const toolsByCategory = {};
+
+  for (const [_serverName, serverData] of Object.entries(classificationData)) {
+    const tools = serverData.tools || [];
+    for (const tool of tools) {
+      if (!tool.category || !neededSet.has(tool.category)) continue;
+
+      if (!toolsByCategory[tool.category]) {
+        toolsByCategory[tool.category] = [];
+      }
+      toolsByCategory[tool.category].push(tool);
+    }
+  }
+
+  // No relevant tools found
+  if (Object.keys(toolsByCategory).length === 0) return '';
+
+  // Build the prompt fragment
+  const lines = [
+    '',
+    '## Available MCP Capabilities',
+    '',
+    'You have access to specialized MCP tools beyond the standard toolset. Use them when they help accomplish your task more effectively.',
+    ''
+  ];
+
+  for (const [category, tools] of Object.entries(toolsByCategory)) {
+    const categoryDef = categories[category];
+    const categoryTitle = category.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+
+    lines.push(`### ${categoryTitle}`);
+    for (const tool of tools) {
+      lines.push(`- \`${tool.name}\` — ${tool.description}`);
+    }
+    if (categoryDef?.agentGuidance) {
+      lines.push(`**When to use**: ${categoryDef.agentGuidance}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate the classification prompt for the orchestrator AI.
+ * This prompt tells the orchestrator how to classify its available MCP tools.
+ *
+ * @returns {string} Instructions for the orchestrator to classify MCP tools
+ */
+function generateClassificationPrompt() {
+  const categories = getCapabilityCategories();
+  const servers = discoverMcpServers();
+
+  if (servers.length === 0) {
+    return '';
+  }
+
+  const categoryList = Object.entries(categories)
+    .map(([name, def]) => `  - \`${name}\`: ${def.description} (keywords: ${def.keywords.join(', ')})`)
+    .join('\n');
+
+  return `## MCP Capability Classification Required
+
+${servers.length} MCP server(s) detected: ${servers.join(', ')}
+
+You have MCP tools available in your tool catalog (they appear as \`mcp__<server>__<tool>\` in your available tools). Classify each one into capability categories so sub-agents know what's available.
+
+### Capability Categories
+${categoryList}
+
+### Instructions
+1. Inspect your available tools — look for any starting with \`mcp__\`
+2. For each MCP tool, determine which category best fits based on its name and what it does
+3. If a tool doesn't fit any category, skip it (don't force-classify)
+4. Cache the results by running:
+
+\`\`\`bash
+node scripts/flow-mcp-capabilities.js cache '<json>'
+\`\`\`
+
+Where \`<json>\` follows this format:
+\`\`\`json
+{
+  "<server-name>": {
+    "tools": [
+      { "name": "mcp__server__tool_name", "description": "Brief description", "category": "<category-id>" }
+    ]
+  }
+}
+\`\`\`
+
+Only include tools that match a category. Skip internal/utility tools that aren't useful for sub-agents.`;
+}
+
+// ============================================================
+// Exports
+// ============================================================
+
+module.exports = {
+  // Configuration
+  getMcpCapabilitiesConfig,
+  getCapabilityCategories,
+  getRoleCapabilities,
+  getAllRoles,
+
+  // Discovery
+  discoverMcpServers,
+
+  // Cache
+  getCachedClassifications,
+  cacheClassifications,
+  clearCache,
+  CACHE_PATH,
+
+  // Prompt generation
+  generateHint,
+  generateClassificationPrompt
+};
+
+// ============================================================
+// CLI Interface
+// ============================================================
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  switch (command) {
+    case 'check-cache': {
+      const cached = getCachedClassifications();
+      if (cached) {
+        const serverCount = Object.keys(cached.classifications || {}).length;
+        const toolCount = Object.values(cached.classifications || {})
+          .reduce((sum, s) => sum + (s.tools?.length || 0), 0);
+        console.log(JSON.stringify({
+          status: 'cache-hit',
+          cachedAt: cached.cachedAt,
+          servers: serverCount,
+          tools: toolCount
+        }));
+      } else {
+        console.log(JSON.stringify({ status: 'cache-miss' }));
+      }
+      break;
+    }
+
+    case 'categories': {
+      const categories = getCapabilityCategories();
+      console.log('\nCapability Categories:\n');
+      for (const [name, def] of Object.entries(categories)) {
+        console.log(`  ${name}`);
+        console.log(`    ${def.description}`);
+        console.log(`    Keywords: ${def.keywords.join(', ')}`);
+        console.log('');
+      }
+      break;
+    }
+
+    case 'roles': {
+      const roles = getAllRoles();
+      console.log('\nRole-to-Capability Mapping:\n');
+      for (const [role, capabilities] of Object.entries(roles)) {
+        console.log(`  ${role}: ${capabilities.join(', ')}`);
+      }
+      break;
+    }
+
+    case 'hint': {
+      const role = args[1];
+      if (!role) {
+        console.error('Usage: flow-mcp-capabilities.js hint <role>');
+        process.exit(1);
+      }
+      const hint = generateHint(role);
+      if (hint) {
+        console.log(hint);
+      } else {
+        console.log('');
+      }
+      break;
+    }
+
+    case 'cache': {
+      const jsonStr = args[1];
+      if (!jsonStr) {
+        console.error('Usage: flow-mcp-capabilities.js cache \'<json>\'');
+        process.exit(1);
+      }
+      try {
+        const data = JSON.parse(jsonStr);
+        if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+          console.error('Invalid input: expected a JSON object');
+          process.exit(1);
+        }
+        // cacheClassifications handles sanitization (dangerous keys, length limits)
+        const success = cacheClassifications(data);
+        if (success) {
+          const serverCount = Object.keys(data).length;
+          const toolCount = Object.values(data).reduce((sum, s) => sum + (s.tools?.length || 0), 0);
+          console.log(JSON.stringify({ status: 'cached', servers: serverCount, tools: toolCount }));
+        } else {
+          console.error('Failed to write cache');
+          process.exit(1);
+        }
+      } catch (err) {
+        console.error(`Invalid JSON: ${err.message}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'clear': {
+      clearCache();
+      console.log('Cache cleared');
+      break;
+    }
+
+    case 'discover': {
+      const servers = discoverMcpServers();
+      if (servers.length === 0) {
+        console.log('No MCP servers found');
+      } else {
+        console.log(`\nDiscovered ${servers.length} MCP server(s):\n`);
+        for (const name of servers) {
+          console.log(`  - ${name}`);
+        }
+      }
+      break;
+    }
+
+    case 'classify-prompt': {
+      const prompt = generateClassificationPrompt();
+      if (prompt) {
+        console.log(prompt);
+      } else {
+        console.log('No MCP servers detected — classification not needed.');
+      }
+      break;
+    }
+
+    default: {
+      console.log(`
+Wogi Flow - MCP Capability Discovery
+
+Usage:
+  node flow-mcp-capabilities.js <command> [args]
+
+Commands:
+  check-cache          Check if classification cache exists (JSON output)
+  categories           List all capability categories
+  roles                List all role-to-capability mappings
+  hint <role>          Generate capability hint for a specific agent role
+  cache '<json>'       Cache tool classifications (JSON input)
+  clear                Clear the classification cache
+  discover             List all discovered MCP servers
+  classify-prompt      Generate classification instructions for the orchestrator
+
+Examples:
+  node flow-mcp-capabilities.js check-cache
+  node flow-mcp-capabilities.js hint explore-codebase
+  node flow-mcp-capabilities.js discover
+  node flow-mcp-capabilities.js classify-prompt
+`);
+    }
+  }
+}

package/scripts/hooks/core/task-completed.js

@@ -349,8 +349,66 @@ async function handleTaskCompleted(input) {
     } catch (_err) {
       // Non-critical - registry manager may not be available
     }
-    // Workspace notifications are handled by the Stop hook (via HTTP to manager port).
-    // Removed duplicate file-based notification here to prevent double messages (finding-004).
+    // Workspace: write structured task-complete message to .workspace/messages/
+    // The Stop hook sends a freeform curl to the manager as a fallback, but this
+    // structured message is the VERIFIED completion signal — it went through quality
+    // gates (gate latch check above). The manager should trust these over freeform reports.
+    if (result.completed && process.env.WOGI_WORKSPACE_ROOT) {
+      try {
+        const workspaceRoot = process.env.WOGI_WORKSPACE_ROOT;
+
+        // Validate workspace root — must be absolute and exist (mirrors stop.js pattern)
+        if (!path.isAbsolute(workspaceRoot) || !fs.existsSync(workspaceRoot)) {
+          throw new Error(`Invalid WOGI_WORKSPACE_ROOT: ${workspaceRoot}`);
+        }
+
+        const messagesDir = path.join(workspaceRoot, '.workspace', 'messages');
+        const repoName = process.env.WOGI_REPO_NAME || 'unknown';
+
+        if (fs.existsSync(messagesDir)) {
+          const msgId = `msg-${completedTask.id}-${Date.now()}`;
+          // Sanitize changedFiles: limit count and path length, strip newlines
+          const rawFiles = input.changedFiles || [];
+          const changedFiles = rawFiles.slice(0, 20).map(f =>
+            String(f).replace(/[\n\r]/g, '').slice(0, 200)
+          );
+          const qualityGates = input.qualityGateResults || [];
+          const evidenceTier = input.evidenceTier || 'unknown';
+
+          const message = {
+            id: msgId,
+            from: repoName,
+            to: 'manager',
+            type: 'task-complete',
+            subject: `Task completed: ${completedTask.title || completedTask.id}`,
+            body: [
+              `**Task**: ${completedTask.id} — ${completedTask.title || ''}`,
+              `**Type**: ${completedTask.type || 'unknown'}`,
+              changedFiles.length > 0 ? `**Files changed**: ${changedFiles.join(', ')}` : null,
+              qualityGates.length > 0 ? `**Quality gates**: ${qualityGates.map(g => `${g.name}: ${g.passed ? 'PASS' : 'FAIL'}`).join(', ')}` : null,
+              `**Verification evidence**: ${evidenceTier}`,
+            ].filter(Boolean).join('\n'),
+            taskId: completedTask.id,
+            status: 'pending',
+            verified: true,
+            evidenceTier,
+            timestamp: new Date().toISOString()
+          };
+
+          fs.writeFileSync(
+            path.join(messagesDir, `${msgId}.json`),
+            JSON.stringify(message, null, 2),
+            { mode: 0o644 }
+          );
+        }
+      } catch (_err) {
+        // Non-critical — workspace message is defense-in-depth.
+        // The Stop hook curl remains as fallback.
+        if (process.env.DEBUG) {
+          console.error(`[Task Completed] Workspace message write failed: ${_err.message}`);
+        }
+      }
+    }
 
     // Compound from success — capture positive patterns (fire-and-forget)
     if (result.completed) {

package/scripts/postinstall.js

@@ -389,16 +389,27 @@ function rewriteHookPaths(settings) {
   // In self-development, hooks should use local paths (node scripts/hooks/...)
   // not package paths (node node_modules/wogiflow/scripts/hooks/...) which don't exist.
   if (path.resolve(PROJECT_ROOT) === path.resolve(PACKAGE_ROOT)) return;
+
+  // Use absolute path to PACKAGE_ROOT/scripts/ instead of relative node_modules/ path.
+  // This fixes monorepo setups where npm hoists wogiflow to the workspace root
+  // node_modules/ but Claude Code runs hooks from a package subdirectory (e.g.,
+  // packages/portal/). Relative paths like 'node node_modules/wogiflow/scripts/...'
+  // fail because the package doesn't exist at the subdirectory level.
+  // Absolute paths work regardless of where Claude Code's cwd is.
+  const absoluteScriptsDir = path.resolve(PACKAGE_ROOT, 'scripts');
+
   for (const hookList of Object.values(settings.hooks)) {
     if (!Array.isArray(hookList)) continue;
     for (const entry of hookList) {
       if (!entry.hooks || !Array.isArray(entry.hooks)) continue;
       for (const hook of entry.hooks) {
         if (hook.command && typeof hook.command === 'string') {
-          hook.command = hook.command.replace(
-            /^node scripts\//,
-            'node node_modules/wogiflow/scripts/'
-          );
+          // Extract the relative script path, join with absolute base, wrap in quotes.
+          // Simpler and more robust than regex-based open/close quoting.
+          const match = hook.command.match(/^node scripts\/(.+)$/);
+          if (match) {
+            hook.command = `node "${path.join(absoluteScriptsDir, match[1])}"`;
+          }
         }
       }
     }