chati-dev 3.2.5 → 3.3.0

package/src/memory/gotchas.js

@@ -24,14 +24,71 @@ function normalizeErrorMessage(message) {
     .trim();
 }
 
+/**
+ * Error categories for gotcha classification.
+ * @enum {string}
+ */
+export const GotchaCategory = {
+  BUILD: 'BUILD',
+  TEST: 'TEST',
+  LINT: 'LINT',
+  RUNTIME: 'RUNTIME',
+  INTEGRATION: 'INTEGRATION',
+  SECURITY: 'SECURITY',
+  CONFIG: 'CONFIG',
+  UNKNOWN: 'UNKNOWN',
+};
+
+/**
+ * Severity levels for gotchas.
+ * @enum {string}
+ */
+export const GotchaSeverity = {
+  INFO: 'INFO',
+  WARNING: 'WARNING',
+  CRITICAL: 'CRITICAL',
+};
+
+/**
+ * Patterns for classifying errors into categories and severities.
+ */
+const CLASSIFICATION_PATTERNS = [
+  { regex: /Cannot find module|ENOENT|import.*not found/i, category: GotchaCategory.BUILD, severity: GotchaSeverity.WARNING },
+  { regex: /SyntaxError|Unexpected token/i, category: GotchaCategory.BUILD, severity: GotchaSeverity.CRITICAL },
+  { regex: /TypeError|ReferenceError/i, category: GotchaCategory.RUNTIME, severity: GotchaSeverity.WARNING },
+  { regex: /test.*fail|assertion|expect/i, category: GotchaCategory.TEST, severity: GotchaSeverity.WARNING },
+  { regex: /lint.*error|eslint|prettier/i, category: GotchaCategory.LINT, severity: GotchaSeverity.INFO },
+  { regex: /CORS|ETIMEDOUT|timeout|ECONNREFUSED/i, category: GotchaCategory.INTEGRATION, severity: GotchaSeverity.WARNING },
+  { regex: /security|vulnerability|injection|EACCES|401|403|unauthorized/i, category: GotchaCategory.SECURITY, severity: GotchaSeverity.CRITICAL },
+  { regex: /out of memory|heap|stack overflow/i, category: GotchaCategory.RUNTIME, severity: GotchaSeverity.CRITICAL },
+  { regex: /config|yaml|json.*parse|invalid.*option/i, category: GotchaCategory.CONFIG, severity: GotchaSeverity.WARNING },
+  { regex: /deprecated/i, category: GotchaCategory.BUILD, severity: GotchaSeverity.INFO },
+];
+
+/**
+ * Classify an error message into category and severity.
+ * @param {string} message - Error message
+ * @returns {{ category: string, severity: string }}
+ */
+export function classifyError(message) {
+  const lowerMessage = (message || '').toLowerCase();
+  for (const pattern of CLASSIFICATION_PATTERNS) {
+    if (pattern.regex.test(lowerMessage)) {
+      return { category: pattern.category, severity: pattern.severity };
+    }
+  }
+  return { category: GotchaCategory.UNKNOWN, severity: GotchaSeverity.INFO };
+}
+
 /**
  * Hash an error message to create a pattern identifier.
+ * Uses SHA-256 truncated to 16 chars for collision resistance.
  * @param {string} message - Error message
- * @returns {string} Hash (first 8 chars)
+ * @returns {string} Hash (first 16 chars)
  */
 function hashErrorMessage(message) {
   const normalized = normalizeErrorMessage(message);
-  return createHash('md5').update(normalized).digest('hex').substring(0, 8);
+  return createHash('sha256').update(normalized).digest('hex').substring(0, 16);
 }
 
 /**
@@ -167,6 +224,7 @@ export function recordError(projectDir, error) {
 
     // Create new gotcha
     const gotchaId = generateGotchaId(gotchas);
+    const classification = classifyError(message);
     const newGotcha = {
       id: gotchaId,
       pattern: hash,
@@ -179,6 +237,8 @@ export function recordError(projectDir, error) {
       last_seen: timestamp,
       promoted_at: timestamp,
       resolution: null,
+      category: classification.category,
+      severity: classification.severity,
       context,
     };
 
@@ -307,11 +367,27 @@ export function getGotchaStats(projectDir) {
     .sort((a, b) => b.count - a.count)
     .slice(0, 10);
 
+  // Count by category
+  const categoryCounts = {};
+  for (const g of gotchas) {
+    const cat = g.category || GotchaCategory.UNKNOWN;
+    categoryCounts[cat] = (categoryCounts[cat] || 0) + 1;
+  }
+
+  // Count by severity
+  const severityCounts = {};
+  for (const g of gotchas) {
+    const sev = g.severity || GotchaSeverity.INFO;
+    severityCounts[sev] = (severityCounts[sev] || 0) + 1;
+  }
+
   return {
     totalErrors: errorLog.length,
     totalGotchas: gotchas.length,
     recentErrors: recentErrors.length,
     topPatterns,
+    categoryCounts,
+    severityCounts,
   };
 }
 

package/src/merger/semantic-merger.js

@@ -0,0 +1,292 @@
+/**
+ * @fileoverview Semantic merge engine for parallel agent outputs.
+ *
+ * Detects file-level, import, and naming conflicts between
+ * changes produced by concurrent agents, and applies merge
+ * strategies (conservative or latest-wins).
+ *
+ * Constitution Protocol 5 — Two-Layer Handoff.
+ */
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Conflict type identifiers. */
+export const CONFLICT_TYPES = {
+  FILE_OVERLAP: 'file_overlap',
+  IMPORT_CONFLICT: 'import_conflict',
+  NAMING_CONFLICT: 'naming_conflict',
+  STRUCTURAL_CONFLICT: 'structural_conflict',
+};
+
+/** Merge strategy options. */
+export const MERGE_STRATEGIES = {
+  CONSERVATIVE: 'conservative',
+  LATEST: 'latest',
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} Change
+ * @property {string} agent - Agent name that produced the change
+ * @property {string} file - File path affected
+ * @property {string} [content] - New content (for full-file changes)
+ * @property {string[]} [imports] - Import statements added
+ * @property {string[]} [exports] - Export names added
+ * @property {string} [timestamp] - ISO timestamp of the change
+ */
+
+/**
+ * @typedef {object} Conflict
+ * @property {string} type - Conflict type (from CONFLICT_TYPES)
+ * @property {string} file - File involved
+ * @property {string[]} agents - Agents that conflict
+ * @property {string} description - Human-readable description
+ * @property {string} severity - 'error' | 'warning'
+ */
+
+/**
+ * Detect conflicts between a set of changes from different agents.
+ *
+ * @param {Change[]} changes
+ * @returns {{ hasConflicts: boolean, conflicts: Conflict[] }}
+ */
+export function detectConflicts(changes) {
+  if (!Array.isArray(changes) || changes.length < 2) {
+    return { hasConflicts: false, conflicts: [] };
+  }
+
+  const conflicts = [];
+
+  // 1. File overlap detection — multiple agents changing same file
+  const fileAgentMap = groupByFile(changes);
+  for (const [file, agentChanges] of fileAgentMap.entries()) {
+    const agents = [...new Set(agentChanges.map(c => c.agent))];
+    if (agents.length > 1) {
+      conflicts.push({
+        type: CONFLICT_TYPES.FILE_OVERLAP,
+        file,
+        agents,
+        description: `Multiple agents (${agents.join(', ')}) modified ${file}`,
+        severity: 'error',
+      });
+    }
+  }
+
+  // 2. Import conflict detection — duplicate or contradictory imports
+  const importsByFile = new Map();
+  for (const change of changes) {
+    if (!change.imports || change.imports.length === 0) continue;
+    if (!importsByFile.has(change.file)) {
+      importsByFile.set(change.file, []);
+    }
+    importsByFile.get(change.file).push({ agent: change.agent, imports: change.imports });
+  }
+
+  for (const [file, importSets] of importsByFile.entries()) {
+    if (importSets.length < 2) continue;
+
+    // Check for duplicate imports from different agents
+    const allImports = new Map();
+    for (const { agent, imports } of importSets) {
+      for (const imp of imports) {
+        const normalized = normalizeImport(imp);
+        if (allImports.has(normalized)) {
+          const existing = allImports.get(normalized);
+          if (existing.agent !== agent) {
+            conflicts.push({
+              type: CONFLICT_TYPES.IMPORT_CONFLICT,
+              file,
+              agents: [existing.agent, agent],
+              description: `Duplicate import "${normalized}" from agents ${existing.agent} and ${agent}`,
+              severity: 'warning',
+            });
+          }
+        } else {
+          allImports.set(normalized, { agent, raw: imp });
+        }
+      }
+    }
+  }
+
+  // 3. Naming conflict detection — same export name from different agents
+  const exportsByName = new Map();
+  for (const change of changes) {
+    if (!change.exports || change.exports.length === 0) continue;
+    for (const exp of change.exports) {
+      if (!exportsByName.has(exp)) {
+        exportsByName.set(exp, []);
+      }
+      exportsByName.get(exp).push({ agent: change.agent, file: change.file });
+    }
+  }
+
+  for (const [name, sources] of exportsByName.entries()) {
+    const uniqueAgents = [...new Set(sources.map(s => s.agent))];
+    if (uniqueAgents.length > 1) {
+      const files = [...new Set(sources.map(s => s.file))];
+      conflicts.push({
+        type: CONFLICT_TYPES.NAMING_CONFLICT,
+        file: files[0],
+        agents: uniqueAgents,
+        description: `Export name "${name}" defined by multiple agents: ${uniqueAgents.join(', ')}`,
+        severity: 'error',
+      });
+    }
+  }
+
+  return {
+    hasConflicts: conflicts.length > 0,
+    conflicts,
+  };
+}
+
+/**
+ * Merge changes from multiple agents using a strategy.
+ *
+ * @param {Change[]} changes
+ * @param {string} [strategy='conservative'] - Merge strategy
+ * @returns {{ merged: Change[], skipped: Change[], strategy: string }}
+ */
+export function mergeChanges(changes, strategy = MERGE_STRATEGIES.CONSERVATIVE) {
+  if (!Array.isArray(changes) || changes.length === 0) {
+    return { merged: [], skipped: [], strategy };
+  }
+
+  if (changes.length === 1) {
+    return { merged: [...changes], skipped: [], strategy };
+  }
+
+  const fileAgentMap = groupByFile(changes);
+  const merged = [];
+  const skipped = [];
+
+  for (const [file, agentChanges] of fileAgentMap.entries()) {
+    const agents = [...new Set(agentChanges.map(c => c.agent))];
+
+    if (agents.length === 1) {
+      // No conflict — include all changes for this file
+      merged.push(...agentChanges);
+      continue;
+    }
+
+    // Conflict resolution based on strategy
+    if (strategy === MERGE_STRATEGIES.LATEST) {
+      // Latest wins — sort by timestamp, take the most recent
+      const sorted = [...agentChanges].sort((a, b) => {
+        const tA = a.timestamp ? new Date(a.timestamp).getTime() : 0;
+        const tB = b.timestamp ? new Date(b.timestamp).getTime() : 0;
+        return tB - tA;
+      });
+      merged.push(sorted[0]);
+      skipped.push(...sorted.slice(1));
+    } else {
+      // Conservative — keep the first agent's changes, skip later ones
+      const sorted = [...agentChanges].sort((a, b) => {
+        const tA = a.timestamp ? new Date(a.timestamp).getTime() : 0;
+        const tB = b.timestamp ? new Date(b.timestamp).getTime() : 0;
+        return tA - tB;
+      });
+      merged.push(sorted[0]);
+      skipped.push(...sorted.slice(1));
+    }
+  }
+
+  return { merged, skipped, strategy };
+}
+
+/**
+ * Validate that a merged result is structurally sound.
+ *
+ * @param {string} original - Original file content
+ * @param {string} merged - Merged file content
+ * @returns {{ valid: boolean, issues: string[] }}
+ */
+export function validateMergedResult(original, merged) {
+  const issues = [];
+
+  if (!merged || typeof merged !== 'string') {
+    issues.push('Merged content is empty or not a string');
+    return { valid: false, issues };
+  }
+
+  // Check for obvious syntax issues
+
+  // 1. Balanced braces
+  const openBraces = (merged.match(/\{/g) || []).length;
+  const closeBraces = (merged.match(/\}/g) || []).length;
+  if (openBraces !== closeBraces) {
+    issues.push(`Unbalanced braces: ${openBraces} open, ${closeBraces} close`);
+  }
+
+  // 2. Balanced parentheses
+  const openParens = (merged.match(/\(/g) || []).length;
+  const closeParens = (merged.match(/\)/g) || []).length;
+  if (openParens !== closeParens) {
+    issues.push(`Unbalanced parentheses: ${openParens} open, ${closeParens} close`);
+  }
+
+  // 3. Balanced brackets
+  const openBrackets = (merged.match(/\[/g) || []).length;
+  const closeBrackets = (merged.match(/\]/g) || []).length;
+  if (openBrackets !== closeBrackets) {
+    issues.push(`Unbalanced brackets: ${openBrackets} open, ${closeBrackets} close`);
+  }
+
+  // 4. Check that imports haven't been duplicated
+  const importLines = merged.match(/^import\s+.+$/gm) || [];
+  const normalizedImports = importLines.map(normalizeImport);
+  const uniqueImports = new Set(normalizedImports);
+  if (uniqueImports.size < normalizedImports.length) {
+    issues.push(`Duplicate imports detected (${normalizedImports.length - uniqueImports.size} duplicates)`);
+  }
+
+  // 5. Check content wasn't completely destroyed
+  if (original && merged.length < original.length * 0.5) {
+    issues.push('Merged content is less than 50% of original size — possible data loss');
+  }
+
+  return {
+    valid: issues.length === 0,
+    issues,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Group changes by file path.
+ *
+ * @param {Change[]} changes
+ * @returns {Map<string, Change[]>}
+ */
+function groupByFile(changes) {
+  const map = new Map();
+  for (const change of changes) {
+    if (!change.file) continue;
+    if (!map.has(change.file)) {
+      map.set(change.file, []);
+    }
+    map.get(change.file).push(change);
+  }
+  return map;
+}
+
+/**
+ * Normalize an import statement for comparison.
+ *
+ * @param {string} importStr
+ * @returns {string}
+ */
+function normalizeImport(importStr) {
+  return importStr
+    .replace(/['"]/g, "'")
+    .replace(/\s+/g, ' ')
+    .trim();
+}

package/src/orchestrator/agent-selector.js

@@ -87,6 +87,26 @@ export function selectAgent(context) {
 
   // If starting fresh with no completed agents
   if (completedAgents.length === 0) {
+    // Quick Flow: fast-track pipeline (Brief quick → Dev → QA → Deploy)
+    if (intent === INTENT_TYPES.QUICK_FLOW) {
+      return {
+        agent: 'brief',
+        reason: 'Quick flow detected — fast-track pipeline',
+        parallelGroup: null,
+        workflowType: 'quick-flow',
+      };
+    }
+
+    // Standard Flow: mid-tier pipeline (8 agents)
+    if (intent === INTENT_TYPES.STANDARD_FLOW) {
+      return {
+        agent: 'brief',
+        reason: 'Standard flow detected — mid-tier pipeline',
+        parallelGroup: null,
+        workflowType: 'standard-flow',
+      };
+    }
+
     // Planning intent starts with WU
     if (intent === INTENT_TYPES.DISCOVER) {
       const wuAgent = isGreenfield ? 'greenfield-wu' : 'brownfield-wu';

package/src/orchestrator/handoff-engine.js

@@ -222,6 +222,83 @@ export function getHandoffHistory(projectDir) {
   }
 }
 
+/**
+ * Minimum required handoff fields per receiving agent.
+ * Used by pre-flight context integrity check.
+ */
+const AGENT_HANDOFF_REQUIREMENTS = {
+  'brief':               { needs: ['summary'] },
+  'detail':              { needs: ['summary', 'outputs'] },
+  'architect':           { needs: ['summary', 'outputs'] },
+  'ux':                  { needs: ['summary', 'outputs'] },
+  'phases':              { needs: ['summary', 'outputs'] },
+  'tasks':               { needs: ['summary', 'outputs'] },
+  'qa-planning':         { needs: ['summary', 'outputs'] },
+  'dev':                 { needs: ['summary', 'outputs'] },
+  'qa-implementation':   { needs: ['summary', 'outputs'] },
+  'devops':              { needs: ['summary', 'outputs'] },
+};
+
+/**
+ * Pre-flight context integrity check.
+ * Validates that a handoff contains sufficient context for the receiving agent.
+ * Run this BEFORE activating an agent to catch missing context early.
+ *
+ * @param {object|null} handoff - Loaded handoff from previous agent
+ * @param {string} receivingAgent - Agent about to be activated
+ * @returns {{ valid: boolean, missing: string[], warnings: string[] }}
+ */
+export function validateHandoffIntegrity(handoff, receivingAgent) {
+  const missing = [];
+  const warnings = [];
+
+  // No handoff at all
+  if (!handoff) {
+    missing.push('No handoff document found from previous agent');
+    return { valid: false, missing, warnings };
+  }
+
+  // Universal checks
+  if (!handoff.summary || handoff.summary.trim().length < 10) {
+    missing.push('Handoff summary is empty or too short (< 10 chars)');
+  }
+
+  if (handoff.status === 'partial') {
+    warnings.push('Previous agent handoff is marked as partial');
+  }
+
+  if (handoff.score !== null && handoff.score !== undefined && handoff.score < 90) {
+    warnings.push(`Previous agent score (${handoff.score}) is below 90% threshold`);
+  }
+
+  // Agent-specific checks
+  const reqs = AGENT_HANDOFF_REQUIREMENTS[receivingAgent];
+  if (reqs) {
+    for (const field of reqs.needs) {
+      const value = handoff[field];
+      if (!value || (Array.isArray(value) && value.length === 0)) {
+        missing.push(`Required field '${field}' is missing or empty`);
+      }
+    }
+  }
+
+  // Check for unresolved blockers
+  if (handoff.blockers && handoff.blockers.length > 0) {
+    const criticalBlockers = handoff.blockers.filter(b =>
+      b.toLowerCase().includes('critical') || b.toLowerCase().includes('blocking')
+    );
+    if (criticalBlockers.length > 0) {
+      warnings.push(`${criticalBlockers.length} critical blocker(s) from previous agent`);
+    }
+  }
+
+  return {
+    valid: missing.length === 0,
+    missing,
+    warnings,
+  };
+}
+
 /**
  * Check if rollback to a previous agent is possible.
  * @param {string} projectDir

package/src/orchestrator/index.js

@@ -32,14 +32,6 @@ export {
   markAgentInProgress,
 } from './pipeline-manager.js';
 
-export {
-  loadPipelineState,
-  savePipelineState,
-  updatePipelineState,
-  sessionExists,
-  deleteSession,
-} from './pipeline-state.js';
-
 export {
   executeHandoff,
   validateHandoffPreconditions,