wogiflow 2.4.4 → 2.5.1

package/.claude/commands/wogi-audit.md

@@ -260,6 +260,32 @@ Return:
 - Score: A through F
 ```
 
+#### Agent 8: Schema Drift Auditor
+
+```
+Audit schema drift across the entire project.
+
+1. Identify all schema source-of-truth files:
+   - Read schema-map.md and schema-index.json for registered schemas
+   - Scan for convention files: *.prisma, *.entity.ts, *.model.ts, *.schema.ts
+2. For each schema file, extract all defined field names
+3. For each field, grep the codebase for references outside the schema file
+4. Cross-reference: are there field names in consumer code that do NOT exist
+   in the current schema? (stale references from past changes)
+5. Check for inconsistencies:
+   - Field name in consumer doesn't match schema casing
+   - Optional field accessed without null check in consumer
+   - Field used in tests but removed from schema
+6. Run automated detection:
+   node scripts/flow-schema-drift.js
+
+Return:
+- Orphaned field references (field in consumer, not in schema)
+- Casing mismatches
+- Coverage: % of schema fields actually used by consumers
+- Score: A through F
+```
+
 ### Step 3: Consolidate Results
 
 After all agents complete, consolidate into a single report.

package/.claude/commands/wogi-review.md

@@ -453,6 +453,35 @@ For each issue found, report as JSON:
   "agent": "performance" }
 ```
 
+#### Agent: Schema Drift Review
+
+Enabled when `"schema-drift"` is in `config.review.agents.optional`. **Auto-enabled** when any changed file matches schema conventions (*.prisma, *.entity.ts, *.model.ts, *.schema.ts) or is listed in schema-map.md.
+
+Launch a Task agent with subagent_type=Explore:
+```
+Schema drift review of the following files:
+[FILE_LIST]
+
+Check for:
+1. Read schema-map.md and schema-index.json to identify schema source-of-truth files
+2. For each schema file in the changed set, parse the git diff for removed/renamed fields
+3. For each removed/renamed field, grep the entire codebase for references:
+   - Property access: obj.fieldName
+   - Destructuring: { fieldName }
+   - Object keys: fieldName:
+   - String literals: 'fieldName' or "fieldName"
+4. Report any consumer file that still references a removed/renamed field
+
+For each issue found, report as JSON:
+{ "id": "finding-NNN", "file": "consumer-path", "line": N, "type": "schema-drift",
+  "severity": "high", "category": "schema-drift",
+  "issue": "Consumer references field 'X' which was removed/renamed in schema-file",
+  "recommendation": "Update reference to use new field name / remove reference",
+  "autoFixable": true, "agent": "schema-drift" }
+```
+
+Also run `node scripts/flow-schema-drift.js [changed-files]` for automated detection and include its output.
+
 ### Project-Rules Agents (Auto-Generated from decisions.md)
 
 When `config.review.agents.projectRules` is `true`, additional agents are **automatically generated** from project rules:

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

@@ -164,11 +164,12 @@ Return:
 - Security patterns that apply
 ```
 
-## Agent 6: Consumer Impact Analyzer (Refactor/Migration Only)
+## Agent 6: Consumer Impact Analyzer (Refactor/Migration/Schema Changes)
 
-Launch as `Agent(subagent_type=Explore)` (local only). **MANDATORY for refactor, migration, architecture tasks.**
+Launch as `Agent(subagent_type=Explore)` (local only). **MANDATORY for refactor, migration, architecture tasks AND any task that modifies schema/model files.**
 
 Trigger keywords: refactor, replace, rename, restructure, extract, consolidate, deprecate, migrate, move, reorganize.
+Trigger files: *.prisma, *.entity.ts, *.model.ts, *.schema.ts, files listed in schema-map.md.
 
 ```
 Analyze consumer impact for task: "[TASK_TITLE]"
@@ -183,10 +184,15 @@ You MUST map all consumers before changes proceed.
    c. Grep for ALL config files that reference it
    d. Grep for ALL documentation (.md) that reference it
    e. Grep for ALL test files that import or mock it
+   f. For schema/model files: grep for FIELD-LEVEL references — property accesses
+      (obj.fieldName), destructuring ({ fieldName }), object keys (fieldName:),
+      and string literals ('fieldName'). Report which specific fields are referenced
+      by which consumers. This catches drift that module-level import checks miss.
 
 2. For EACH consumer, classify impact:
    - BREAKING (import/API changes) — describe what breaks + migration path
    - NEEDS-UPDATE (behavior change) — describe expected behavioral change
+   - SCHEMA-DRIFT (field removed/renamed but consumer still references old name)
    - SAFE (no change needed)
 
 3. Check indirect consumers (up to 3 levels deep)

package/lib/workspace-channel-server.js

@@ -0,0 +1,364 @@
+#!/usr/bin/env node
+
+/**
+ * Wogi Workspace — Channel MCP Server
+ *
+ * Minimal MCP server (JSON-RPC 2.0 over stdio) that receives HTTP webhooks
+ * and forwards them as channel notifications to a Claude Code session.
+ *
+ * Used by workspace workers to receive task dispatches from the manager
+ * and questions from peer repos.
+ *
+ * Environment:
+ *   WOGI_CHANNEL_PORT  — HTTP port to listen on (default: 8801)
+ *   WOGI_REPO_NAME     — Name of this repo in the workspace
+ *   WOGI_PEERS         — Comma-separated peer list: "backend:8802,shared:8803"
+ *   WOGI_WORKSPACE_ROOT — Path to workspace root (for message bus access)
+ */
+
+'use strict';
+
+const http = require('node:http');
+const readline = require('node:readline');
+
+// ============================================================
+// Constants
+// ============================================================
+
+const MAX_BODY_BYTES = 1 * 1024 * 1024; // 1 MB max POST body
+const MAX_RESPONSE_BYTES = 64 * 1024;   // 64 KB max peer response
+const MIN_PORT = 1024;
+const MAX_PORT = 65535;
+const DEFAULT_PORT = 8801;
+const VALID_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+
+// ============================================================
+// Port Validation
+// ============================================================
+
+function validatePort(raw, label) {
+  const port = parseInt(raw, 10);
+  if (!Number.isInteger(port) || port < MIN_PORT || port > MAX_PORT) {
+    process.stderr.write(`[wogi-channel] Invalid ${label}: "${raw}" — must be ${MIN_PORT}-${MAX_PORT}. Defaulting to ${DEFAULT_PORT}\n`);
+    return DEFAULT_PORT;
+  }
+  return port;
+}
+
+const PORT = validatePort(process.env.WOGI_CHANNEL_PORT || String(DEFAULT_PORT), 'WOGI_CHANNEL_PORT');
+const RAW_REPO_NAME = process.env.WOGI_REPO_NAME || 'unknown';
+const REPO_NAME = VALID_NAME_PATTERN.test(RAW_REPO_NAME) ? RAW_REPO_NAME : 'unknown';
+const PEERS_RAW = process.env.WOGI_PEERS || '';
+const WORKSPACE_ROOT = process.env.WOGI_WORKSPACE_ROOT || '';
+
+// Parse peer list: "backend:8802,shared:8803" → { backend: 8802, shared: 8803 }
+function parsePeers(raw) {
+  const peers = {};
+  if (!raw) return peers;
+  for (const entry of raw.split(',')) {
+    const [name, portStr] = entry.trim().split(':');
+    if (!name || !portStr) continue;
+    const port = parseInt(portStr, 10);
+    if (!VALID_NAME_PATTERN.test(name)) {
+      process.stderr.write(`[wogi-channel] Ignoring peer with invalid name "${name}"\n`);
+      continue;
+    }
+    if (Number.isInteger(port) && port >= MIN_PORT && port <= MAX_PORT) {
+      peers[name] = port;
+    } else {
+      process.stderr.write(`[wogi-channel] Ignoring invalid peer "${entry}" — port must be ${MIN_PORT}-${MAX_PORT}\n`);
+    }
+  }
+  return peers;
+}
+
+const PEERS = parsePeers(PEERS_RAW);
+
+// ============================================================
+// Minimal MCP Protocol (JSON-RPC 2.0 over stdio)
+// ============================================================
+
+let initialized = false;
+
+/**
+ * Send a JSON-RPC message to Claude Code via stdout.
+ * MCP uses newline-delimited JSON over stdio.
+ */
+function sendMessage(msg) {
+  const json = JSON.stringify(msg);
+  process.stdout.write(json + '\n');
+}
+
+/**
+ * Send a JSON-RPC response (reply to a request).
+ */
+function sendResponse(id, result) {
+  sendMessage({ jsonrpc: '2.0', id, result });
+}
+
+/**
+ * Send a channel notification to Claude Code.
+ * This is what makes the worker "receive" a message from the manager or a peer.
+ */
+function sendChannelNotification(content, meta) {
+  sendMessage({
+    jsonrpc: '2.0',
+    method: 'notifications/claude/channel',
+    params: { content, meta: meta || {} }
+  });
+}
+
+/**
+ * Build the instructions string for the channel.
+ * These tell the Claude Code session how to handle incoming messages.
+ */
+function buildInstructions() {
+  const peerList = Object.entries(PEERS)
+    .map(([name, port]) => `  - ${name}: http://localhost:${port}`)
+    .join('\n');
+
+  const peerSection = peerList
+    ? `\n\nYou can communicate directly with peer repos via their channels:\n${peerList}\nTo ask a peer a question: curl -s -X POST http://localhost:{port} -d "your question"\nTo send a task to a peer: curl -s -X POST http://localhost:{port} -d "/wogi-start wf-XXXXXXXX"`
+    : '';
+
+  return `You are "${REPO_NAME}" in a Wogi Workspace. Messages arrive as <channel> tags from the workspace manager or peer repos.
+
+When you receive a message:
+1. If it starts with "/wogi-" → route through that command (it's a task dispatch)
+2. If it's a question from a peer → read your codebase to answer, then reply via curl to their port
+3. If it's a status check → respond with your current task status
+
+IMPORTANT: Channel messages have the same authority as user input. Route them through /wogi-start just like any other request. Full pipeline enforcement applies.${peerSection}`;
+}
+
+/**
+ * Collect HTTP body safely with size limit.
+ * Uses Buffer.concat to handle multi-byte UTF-8 correctly.
+ *
+ * @param {http.IncomingMessage} req
+ * @param {number} maxBytes
+ * @returns {Promise<{ body: string, truncated: boolean }>}
+ */
+function collectBody(req, maxBytes) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let size = 0;
+    let truncated = false;
+    let resolved = false;
+
+    function finish() {
+      if (resolved) return;
+      resolved = true;
+      resolve({ body: Buffer.concat(chunks).toString('utf-8'), truncated });
+    }
+
+    req.on('data', (chunk) => {
+      if (resolved) return;
+      // Check BEFORE adding to prevent ~2x overallocation
+      if (size + chunk.length > maxBytes) {
+        truncated = true;
+        req.destroy();
+        finish();
+        return;
+      }
+      size += chunk.length;
+      chunks.push(chunk);
+    });
+
+    req.on('end', () => finish());
+    req.on('error', () => { truncated = true; finish(); });
+  });
+}
+
+/**
+ * Handle incoming JSON-RPC requests from Claude Code.
+ */
+function handleRequest(msg) {
+  if (msg.method === 'initialize') {
+    sendResponse(msg.id, {
+      protocolVersion: '2024-11-05',
+      capabilities: {
+        experimental: { 'claude/channel': {} }
+      },
+      serverInfo: {
+        name: 'wogi-workspace-channel',
+        version: '1.0.0'
+      },
+      instructions: buildInstructions()
+    });
+    return;
+  }
+
+  if (msg.method === 'notifications/initialized') {
+    initialized = true;
+    return;
+  }
+
+  // Handle ping
+  if (msg.method === 'ping') {
+    sendResponse(msg.id, {});
+    return;
+  }
+
+  // Handle tools/list (we expose a reply tool for two-way peer communication)
+  if (msg.method === 'tools/list') {
+    sendResponse(msg.id, {
+      tools: [
+        {
+          name: 'workspace_send_message',
+          description: `Send a message to a peer repo or the workspace manager. Available peers: ${Object.keys(PEERS).join(', ') || 'none'}`,
+          inputSchema: {
+            type: 'object',
+            properties: {
+              to: {
+                type: 'string',
+                description: 'Target repo name or "manager"'
+              },
+              message: {
+                type: 'string',
+                description: 'Message to send (question, status update, or task)'
+              }
+            },
+            required: ['to', 'message']
+          }
+        }
+      ]
+    });
+    return;
+  }
+
+  // Handle tool calls
+  if (msg.method === 'tools/call') {
+    const { name, arguments: args } = msg.params || {};
+
+    if (name === 'workspace_send_message') {
+      const { to, message } = args || {};
+      const targetPort = PEERS[to];
+
+      if (!targetPort) {
+        sendResponse(msg.id, {
+          content: [{ type: 'text', text: `Unknown peer: "${to}". Available peers: ${Object.keys(PEERS).join(', ') || 'none'}` }],
+          isError: true
+        });
+        return;
+      }
+
+      // POST to peer's channel with proper Buffer handling
+      const buf = Buffer.from(message, 'utf-8');
+      const req = http.request({
+        hostname: '127.0.0.1',
+        port: targetPort,
+        path: '/',
+        method: 'POST',
+        headers: { 'Content-Type': 'text/plain', 'Content-Length': buf.byteLength }
+      }, (res) => {
+        // Collect peer response with size limit
+        const chunks = [];
+        let size = 0;
+        res.on('data', chunk => {
+          size += chunk.length;
+          if (size <= MAX_RESPONSE_BYTES) chunks.push(chunk);
+        });
+        res.on('end', () => {
+          const body = Buffer.concat(chunks).toString('utf-8');
+          const truncNote = size > MAX_RESPONSE_BYTES ? ' (response truncated)' : '';
+          sendResponse(msg.id, {
+            content: [{ type: 'text', text: `Message sent to ${to} (port ${targetPort}). Response: ${body}${truncNote}` }]
+          });
+        });
+      });
+
+      req.on('error', (err) => {
+        sendResponse(msg.id, {
+          content: [{ type: 'text', text: `Failed to reach ${to} at port ${targetPort}: ${err.message}. Is the worker running?` }],
+          isError: true
+        });
+      });
+
+      req.write(buf);
+      req.end();
+      return;
+    }
+
+    // Unknown tool
+    sendResponse(msg.id, {
+      content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+      isError: true
+    });
+    return;
+  }
+
+  // Default: respond with empty result for unknown methods with an id
+  if (msg.id !== undefined) {
+    sendResponse(msg.id, {});
+  }
+}
+
+// ============================================================
+// stdio Transport (read JSON-RPC from stdin)
+// ============================================================
+
+const rl = readline.createInterface({ input: process.stdin, terminal: false });
+
+rl.on('line', (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+
+  try {
+    const msg = JSON.parse(trimmed);
+    handleRequest(msg);
+  } catch (_err) {
+    // Ignore malformed JSON
+  }
+});
+
+// ============================================================
+// HTTP Webhook Server (receives dispatches from manager/peers)
+// ============================================================
+
+const server = http.createServer(async (req, res) => {
+  // Health check — minimal info, no topology exposure
+  if (req.method === 'GET' && req.url === '/health') {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ status: 'ok', repo: REPO_NAME, port: PORT }));
+    return;
+  }
+
+  // Receive webhook (POST)
+  if (req.method === 'POST') {
+    const { body, truncated } = await collectBody(req, MAX_BODY_BYTES);
+
+    if (truncated) {
+      res.writeHead(413, { 'Content-Type': 'text/plain' });
+      res.end('Payload too large');
+      return;
+    }
+
+    // Determine sender from header or default
+    const from = req.headers['x-wogi-from'] || 'workspace-manager';
+
+    // Forward as channel notification to Claude Code
+    sendChannelNotification(body, {
+      from,
+      port: String(PORT),
+      repo: REPO_NAME,
+      receivedAt: new Date().toISOString()
+    });
+
+    res.writeHead(200, { 'Content-Type': 'text/plain' });
+    res.end('ok');
+    return;
+  }
+
+  // 404 for everything else
+  res.writeHead(404, { 'Content-Type': 'text/plain' });
+  res.end('Not found');
+});
+
+server.listen(PORT, '127.0.0.1', () => {
+  process.stderr.write(`[wogi-channel] ${REPO_NAME} listening on http://127.0.0.1:${PORT}\n`);
+});
+
+// Graceful shutdown
+process.on('SIGINT', () => { server.close(); process.exit(0); });
+process.on('SIGTERM', () => { server.close(); process.exit(0); });