chati-dev 4.2.2 → 4.3.1

package/src/orchestrator/pipeline-manager.js

@@ -55,6 +55,7 @@ export const AGENT_STATUS = {
   COMPLETED: 'completed',
   SKIPPED: 'skipped',
   NEEDS_REVALIDATION: 'needs_revalidation',
+  PENDING_REWORK: 'pending_rework',
   FAILED: 'failed',
 };
 
@@ -63,6 +64,131 @@ export const AGENT_STATUS = {
  */
 const QA_PLANNING_THRESHOLD = 95;
 const QA_IMPLEMENTATION_THRESHOLD = 95;
+const QA_VISUAL_THRESHOLD = 90;
+
+/**
+ * Fault Vector Protocol (Article XXII) — max correction cycles per (QA, target) pair
+ * before escalating to human.
+ */
+export const MAX_CORRECTION_CYCLES = 2;
+
+/**
+ * Fault Vector Protocol routing table. Given a failing QA agent and the majority
+ * fault_origin of its Decision Trail entries, returns the agent that should
+ * re-work. Origins not listed default to UNKNOWN → each QA's primary rework target.
+ */
+const FVP_ROUTING = {
+  'qa-planning': {
+    INTENT: 'brief',
+    SPEC: 'architect',
+    CODE: 'detail',
+    UNKNOWN: 'architect',
+  },
+  'qa-implementation': {
+    INTENT: 'brief',
+    SPEC: 'tasks',
+    CODE: 'dev',
+    UNKNOWN: 'dev',
+  },
+  'qa-visual': {
+    INTENT: 'brief',
+    SPEC: 'ux',
+    CODE: 'dev',
+    UNKNOWN: 'dev',
+  },
+};
+
+/**
+ * QA thresholds by agent name.
+ */
+const QA_THRESHOLDS = {
+  'qa-planning': QA_PLANNING_THRESHOLD,
+  'qa-implementation': QA_IMPLEMENTATION_THRESHOLD,
+  'qa-visual': QA_VISUAL_THRESHOLD,
+};
+
+/**
+ * Route a failing QA to the correct rework target via Fault Vector Protocol.
+ *
+ * @param {string} qaAgent - The QA agent that failed ('qa-planning' | 'qa-implementation' | 'qa-visual')
+ * @param {string} faultOrigin - INTENT | SPEC | CODE | DEFER | UNKNOWN
+ * @param {object} state - Pipeline state (used to honor brownfield greenfield-wu routing)
+ * @returns {{ nextAgent: string|null, reason: string }}
+ */
+export function routeByFaultVector(qaAgent, faultOrigin, state = {}) {
+  const origin = (faultOrigin || 'UNKNOWN').toUpperCase();
+
+  // DEFER = defect acknowledged but out of scope for current pipeline — no rework.
+  if (origin === 'DEFER') {
+    return { nextAgent: null, reason: `${qaAgent} flagged DEFER — logging only, no rework` };
+  }
+
+  const table = FVP_ROUTING[qaAgent];
+  if (!table) {
+    return { nextAgent: null, reason: `Unknown QA agent: ${qaAgent}` };
+  }
+
+  let target = table[origin] || table.UNKNOWN;
+
+  // Honor greenfield/brownfield: INTENT issues in brownfield route to brownfield-wu
+  if (origin === 'INTENT' && state.isGreenfield === false) {
+    target = 'brownfield-wu';
+  }
+
+  return {
+    nextAgent: target,
+    reason: `${qaAgent} failed with fault_origin=${origin}, routing to ${target}`,
+  };
+}
+
+/**
+ * Determine the primary fault_origin from Decision Trail entries (majority vote of
+ * unresolved entries). Falls back to UNKNOWN when no data is available.
+ *
+ * @param {object} handoffData - { decision_trail_entries?: object[], resolved_decision_trail?: string[] }
+ * @returns {string} INTENT | SPEC | CODE | DEFER | UNKNOWN
+ */
+export function extractPrimaryFaultOrigin(handoffData) {
+  const entries = handoffData?.decision_trail_entries || [];
+  if (entries.length === 0) return 'UNKNOWN';
+
+  // Consider only unresolved entries — resolved ones describe historical routing.
+  const active = entries.filter(e => !e.resolved);
+  if (active.length === 0) return 'UNKNOWN';
+
+  const counts = {};
+  for (const e of active) {
+    const origin = (e.fault_origin || 'UNKNOWN').toUpperCase();
+    counts[origin] = (counts[origin] || 0) + 1;
+  }
+
+  let winner = 'UNKNOWN';
+  let max = 0;
+  for (const [origin, count] of Object.entries(counts)) {
+    if (count > max) {
+      max = count;
+      winner = origin;
+    }
+  }
+  return winner;
+}
+
+/**
+ * Build the key used to track correction cycles per (qa, target) pair.
+ */
+function correctionKey(qaAgent, target) {
+  return `${qaAgent}->${target}`;
+}
+
+/**
+ * Check if a QA agent's score is below its threshold.
+ */
+function qaScoreBelowThreshold(qaAgent, score) {
+  const threshold = QA_THRESHOLDS[qaAgent];
+  if (threshold === undefined) return false;
+  if (score === null || score === undefined) return true;
+  return score < threshold;
+}
 
 /**
  * Initialize a new pipeline for a project.
@@ -119,6 +245,7 @@ export function initPipeline(options = {}) {
     currentAgent: null,
     modeTransitions: [],
     history: [],
+    correctionCycles: {},
   };
 }
 
@@ -128,7 +255,8 @@ export function initPipeline(options = {}) {
  */
 const STANDARD_FLOW_AGENTS = [
   'brief', 'detail', 'architect', 'tasks',
-  'qa-planning', 'dev', 'qa-implementation', 'devops',
+  // qa-planning removed — now inside Planning Team, score synced via handleTeamDissolve
+  'dev', 'qa-implementation', 'devops',
 ];
 
 /**
@@ -183,6 +311,7 @@ export function initQuickFlowPipeline(options = {}) {
     currentAgent: null,
     modeTransitions: [],
     history: [],
+    correctionCycles: {},
   };
 }
 
@@ -233,6 +362,7 @@ export function initStandardFlowPipeline(options = {}) {
     currentAgent: null,
     modeTransitions: [],
     history: [],
+    correctionCycles: {},
   };
 }
 
@@ -279,14 +409,15 @@ export function advancePipeline(pipelineState, completedAgent, results = {}) {
   });
 
   // Special handling for QA agents - check if they meet thresholds
-  const isQAAgent = completedAgent === 'qa-planning' || completedAgent === 'qa-implementation';
+  const isQAAgent = completedAgent === 'qa-planning' || completedAgent === 'qa-implementation' || completedAgent === 'qa-visual';
   if (isQAAgent) {
     const transitionCheck = checkPhaseTransition(newState);
 
     if (transitionCheck.canAdvance) {
-      // User Preview gate: when QA-Implementation passes in build phase,
-      // don't advance to deploy yet — let user preview first.
-      if (completedAgent === 'qa-implementation' && newState.phase === 'build') {
+      // User Preview gate: when the final QA gate (qa-visual) passes in build phase,
+      // don't advance to deploy yet — let user preview first. (4.3.0+: qa-visual is
+      // the final build gate; previously this was qa-implementation.)
+      if (completedAgent === 'qa-visual' && newState.phase === 'build') {
         return {
           state: newState,
           nextAction: 'user_preview',
@@ -294,7 +425,9 @@ export function advancePipeline(pipelineState, completedAgent, results = {}) {
           needsModeSwitch: false,
           contextBracket,
           previewContext: {
-            qaScore: newState.agents['qa-implementation'].score,
+            qaImplScore: newState.agents['qa-implementation']?.score,
+            qaVisualScore: newState.agents['qa-visual']?.score,
+            qaScore: newState.agents['qa-visual']?.score,
           },
         };
       }
@@ -334,13 +467,119 @@ export function advancePipeline(pipelineState, completedAgent, results = {}) {
         contextBracket,
       };
     } else {
-      // QA failed - wait for issues to be fixed
+      // QA failed — trigger backward transition via Fault Vector Protocol.
+      // We re-open the rework target, NOT wait for manual intervention.
+      const faultOrigin = (results.faultOrigin || extractPrimaryFaultOrigin(results.handoffData)).toUpperCase();
+      const { nextAgent: correctionTarget, reason: routingReason } = routeByFaultVector(
+        completedAgent,
+        faultOrigin,
+        newState,
+      );
+
+      // DEFER or unroutable — log and stay in wait (legacy behavior)
+      if (!correctionTarget) {
+        newState.history.push({
+          agent: completedAgent,
+          action: 'qa_failed_no_rework',
+          timestamp: new Date().toISOString(),
+          faultOrigin,
+          score: results.score ?? null,
+        });
+        return {
+          state: newState,
+          nextAction: 'wait',
+          nextAgent: null,
+          needsModeSwitch: false,
+          contextBracket,
+          correction: {
+            source: completedAgent,
+            target: null,
+            faultOrigin,
+            reason: routingReason,
+          },
+        };
+      }
+
+      // Increment correction cycle counter for (qa → target) pair
+      newState.correctionCycles = newState.correctionCycles || {};
+      const key = correctionKey(completedAgent, correctionTarget);
+      const cycle = (newState.correctionCycles[key] || 0) + 1;
+      newState.correctionCycles[key] = cycle;
+
+      // Exceeded max cycles — escalate to human, don't loop forever
+      if (cycle > MAX_CORRECTION_CYCLES) {
+        newState.history.push({
+          agent: completedAgent,
+          action: 'correction_escalated',
+          target: correctionTarget,
+          cycle,
+          faultOrigin,
+          timestamp: new Date().toISOString(),
+        });
+        return {
+          state: newState,
+          nextAction: 'escalate',
+          nextAgent: null,
+          needsModeSwitch: false,
+          contextBracket,
+          correction: {
+            source: completedAgent,
+            target: correctionTarget,
+            faultOrigin,
+            cycle,
+            exceeded: true,
+            reason: `Max ${MAX_CORRECTION_CYCLES} correction cycles exceeded for ${key}. Human intervention required.`,
+            findings: results.findings || [],
+            score: results.score ?? null,
+          },
+        };
+      }
+
+      // Re-open target and every agent after it (they will need to re-run
+      // after target re-completes).
+      const targetIndex = AGENT_PIPELINE.findIndex(a => a.name === correctionTarget);
+      if (targetIndex >= 0) {
+        const toReset = AGENT_PIPELINE.slice(targetIndex).map(a => a.name);
+        for (const agentName of toReset) {
+          if (!newState.agents[agentName]) continue;
+          const isTarget = agentName === correctionTarget;
+          newState.agents[agentName] = {
+            status: isTarget ? AGENT_STATUS.PENDING_REWORK : AGENT_STATUS.PENDING,
+            score: null,
+            startedAt: isTarget ? new Date().toISOString() : null,
+            completedAt: null,
+          };
+        }
+        newState.completedAgents = newState.completedAgents.filter(a => !toReset.includes(a));
+      }
+
+      newState.currentAgent = correctionTarget;
+      newState.history.push({
+        agent: completedAgent,
+        action: 'triggered_correction',
+        target: correctionTarget,
+        cycle,
+        faultOrigin,
+        score: results.score ?? null,
+        timestamp: new Date().toISOString(),
+      });
+
       return {
         state: newState,
-        nextAction: 'wait',
-        nextAgent: null,
+        nextAction: 'correction_loop',
+        nextAgent: correctionTarget,
         needsModeSwitch: false,
         contextBracket,
+        correction: {
+          source: completedAgent,
+          target: correctionTarget,
+          faultOrigin,
+          cycle,
+          exceeded: false,
+          reason: routingReason,
+          findings: results.findings || [],
+          score: results.score ?? null,
+        },
       };
     }
   }
@@ -454,8 +693,16 @@ export function checkPhaseTransition(pipelineState) {
 
   // Check based on current phase
   if (phase === 'discover') {
-    // DISCOVER -> PLAN transition: all discover agents must be completed
-    // (brief must be done to advance to plan)
+    // DISCOVER -> PLAN transition: brief must be completed
+    // (WU runs first, then brief — both must finish before advancing to plan)
+    const brief = agents['brief'];
+    if (!brief || brief.status !== AGENT_STATUS.COMPLETED) {
+      return {
+        canAdvance: false,
+        reason: 'Brief agent not yet completed',
+        requiredScore: null,
+      };
+    }
     return {
       canAdvance: true,
       reason: 'Discover phase agents completed',
@@ -464,8 +711,14 @@ export function checkPhaseTransition(pipelineState) {
   }
 
   if (phase === 'plan') {
-    // Need QA-Planning to be completed with score >= 95
+    // PLAN -> BUILD transition requires:
+    // 1. QA-Planning completed with score >= 95 (validates Planning Team output)
+    // 2. Phases completed (work broken into phases)
+    // 3. Tasks completed (task list created)
     const qaPlanning = agents['qa-planning'];
+    const phases = agents['phases'];
+    const tasks = agents['tasks'];
+
     if (!qaPlanning) {
       return {
         canAdvance: false,
@@ -490,17 +743,37 @@ export function checkPhaseTransition(pipelineState) {
       };
     }
 
+    if (!phases || phases.status !== AGENT_STATUS.COMPLETED) {
+      return {
+        canAdvance: false,
+        reason: 'Phases agent not yet completed',
+        requiredScore: null,
+      };
+    }
+
+    if (!tasks || tasks.status !== AGENT_STATUS.COMPLETED) {
+      return {
+        canAdvance: false,
+        reason: 'Tasks agent not yet completed',
+        requiredScore: null,
+      };
+    }
+
     return {
       canAdvance: true,
-      reason: `QA-Planning approved with score ${qaPlanning.score}`,
+      reason: `Plan phase complete: QA-Planning ${qaPlanning.score}%, phases + tasks done`,
       requiredScore: null,
     };
   }
 
   if (phase === 'build') {
-    // Need dev and QA-Implementation completed
+    // BUILD -> DEPLOY transition requires:
+    // 1. Dev completed (implementation)
+    // 2. QA-Implementation completed with score >= 95 (code quality)
+    // 3. QA-Visual completed with score >= 90 (visual quality)
     const dev = agents['dev'];
     const qaImpl = agents['qa-implementation'];
+    const qaVisual = agents['qa-visual'];
 
     if (!dev || !qaImpl) {
       return {
@@ -534,9 +807,27 @@ export function checkPhaseTransition(pipelineState) {
       };
     }
 
+    // QA-Visual is optional if agent is not in pipeline (older sessions)
+    if (qaVisual) {
+      if (qaVisual.status !== AGENT_STATUS.COMPLETED) {
+        return {
+          canAdvance: false,
+          reason: 'QA-Visual not yet completed',
+          requiredScore: 90,
+        };
+      }
+      if (qaVisual.score === null || qaVisual.score < 90) {
+        return {
+          canAdvance: false,
+          reason: `QA-Visual score ${qaVisual.score || 0} below threshold 90`,
+          requiredScore: 90,
+        };
+      }
+    }
+
     return {
       canAdvance: true,
-      reason: `QA-Implementation approved with score ${qaImpl.score}`,
+      reason: `Build phase complete: QA-Impl ${qaImpl.score}%, QA-Visual ${qaVisual?.score ?? 'n/a'}%`,
       requiredScore: null,
     };
   }