claude-flow-novice 2.15.11 → 2.16.1

package/claude-assets/skills/cfn-loop-orchestration/src/helpers/product-owner-decision.ts

@@ -0,0 +1,316 @@
+/**
+ * Product Owner Decision Parser
+ *
+ * Migrated from execute-decision.sh (v3.1.0)
+ *
+ * Purpose: Parse Product Owner decision output and validate deliverables
+ *
+ * Three parsing patterns supported:
+ * 1. Structured: "Decision: PROCEED"
+ * 2. Unstructured: "PROCEED" anywhere in text
+ * 3. Case-insensitive: "proceed" or "PROCEED"
+ */
+
+export interface ProductOwnerDecisionInput {
+  taskId: string;
+  iteration: number;
+  maxIterations: number;
+  consensus: number;
+  threshold: number;
+  successCriteria?: string;
+  loop2Feedback?: string;
+  taskContext?: string;
+  timeout?: number; // seconds, default 60
+}
+
+export interface ProductOwnerDecision {
+  decision: 'PROCEED' | 'ITERATE' | 'ABORT';
+  reasoning: string;
+  confidence: number;
+  auditAnalysis?: string;
+  agentPerformance?: string;
+  timestamp: number;
+  iteration: number;
+  consensus: number;
+  threshold: number;
+  deliverableVerificationRequired: boolean;
+  deliverableVerificationPassed?: boolean;
+}
+
+export interface ProductOwnerOutput {
+  rawOutput: string;
+  exitCode: number;
+  timedOut: boolean;
+}
+
+/**
+ * Parse Product Owner decision from agent output
+ *
+ * Supports three parsing patterns:
+ * - Pattern 1: "Decision: PROCEED"
+ * - Pattern 2: "PROCEED" (standalone)
+ * - Pattern 3: "proceed" (case-insensitive)
+ */
+export function parseProductOwnerDecision(
+  output: ProductOwnerOutput,
+  input: ProductOwnerDecisionInput
+): ProductOwnerDecision {
+  const { rawOutput, exitCode, timedOut } = output;
+  const { iteration, consensus, threshold } = input;
+
+  // Handle timeout
+  if (timedOut || exitCode === 124) {
+    return {
+      decision: 'ABORT',
+      reasoning: `Product Owner decision timeout after ${input.timeout || 60}s`,
+      confidence: 0.0,
+      timestamp: Date.now(),
+      iteration,
+      consensus,
+      threshold,
+      deliverableVerificationRequired: false
+    };
+  }
+
+  // Parse decision using three fallback patterns
+  let decisionType: 'PROCEED' | 'ITERATE' | 'ABORT' | null = null;
+
+  // Pattern 1: Structured format "Decision: PROCEED"
+  const structuredMatch = rawOutput.match(/Decision:\s*(PROCEED|ITERATE|ABORT)/i);
+  if (structuredMatch?.[1]) {
+    decisionType = structuredMatch[1].toUpperCase() as 'PROCEED' | 'ITERATE' | 'ABORT';
+  }
+
+  // Pattern 2: Standalone decision keyword (first occurrence)
+  if (!decisionType) {
+    const standaloneMatch = rawOutput.match(/\b(PROCEED|ITERATE|ABORT)\b/);
+    if (standaloneMatch) {
+      decisionType = standaloneMatch[1] as 'PROCEED' | 'ITERATE' | 'ABORT';
+    }
+  }
+
+  // Pattern 3: Case-insensitive search
+  if (!decisionType) {
+    const caseInsensitiveMatch = rawOutput.match(/\b(proceed|iterate|abort)\b/i);
+    if (caseInsensitiveMatch?.[1]) {
+      decisionType = caseInsensitiveMatch[1].toUpperCase() as 'PROCEED' | 'ITERATE' | 'ABORT';
+    }
+  }
+
+  // Default to ABORT if parsing fails
+  if (!decisionType) {
+    return {
+      decision: 'ABORT',
+      reasoning: 'Failed to parse Product Owner decision from output',
+      confidence: 0.0,
+      timestamp: Date.now(),
+      iteration,
+      consensus,
+      threshold,
+      deliverableVerificationRequired: false
+    };
+  }
+
+  // Parse reasoning
+  const reasoningMatch = rawOutput.match(/Reasoning:\s*(.+?)(?=\n[A-Z]|$)/s);
+  const reasoning = reasoningMatch?.[1]?.trim() ?? 'No reasoning provided';
+
+  // Parse confidence
+  const confidenceMatch = rawOutput.match(/Confidence:\s*([0-9]+\.?[0-9]*)/);
+  const confidence = confidenceMatch?.[1] ? parseFloat(confidenceMatch[1]) : 0.85;
+
+  // Parse audit analysis (optional)
+  const auditAnalysisMatch = rawOutput.match(/Audit Analysis:\s*(.+?)(?=\n[A-Z]|$)/s);
+  const agentPerfMatch = rawOutput.match(/Agent Performance:\s*(.+?)(?=\n[A-Z]|$)/s);
+
+  const result: ProductOwnerDecision = {
+    decision: decisionType,
+    reasoning,
+    confidence,
+    timestamp: Date.now(),
+    iteration,
+    consensus,
+    threshold,
+    deliverableVerificationRequired: decisionType === 'PROCEED'
+  };
+
+  // Add optional fields only if they exist
+  if (auditAnalysisMatch?.[1]) {
+    result.auditAnalysis = auditAnalysisMatch[1].trim();
+  }
+  if (agentPerfMatch?.[1]) {
+    result.agentPerformance = agentPerfMatch[1].trim();
+  }
+
+  return result;
+}
+
+/**
+ * Verify deliverables exist when decision is PROCEED
+ *
+ * Prevents "consensus on vapor" anti-pattern
+ *
+ * Checks:
+ * - Task requires implementation (keywords: create, build, implement, generate)
+ * - Git status shows file changes
+ *
+ * Returns: true if deliverables verified, false otherwise
+ */
+export async function verifyDeliverables(
+  taskContext: string
+): Promise<{ verified: boolean; filesChanged: number; message: string }> {
+  const { execSync } = await import('child_process');
+
+  // Check if task requires implementation
+  const requiresImplementation = /\b(create|build|implement|generate|write|add)\b/i.test(taskContext);
+
+  if (!requiresImplementation) {
+    return {
+      verified: true,
+      filesChanged: 0,
+      message: 'Task does not require implementation (planning/documentation only)'
+    };
+  }
+
+  // Check git status for file changes
+  try {
+    const gitStatus = execSync('git status --short', { encoding: 'utf-8' });
+    const filesChanged = gitStatus.split('\n').filter(line => /^(A|M|\?\?)/.test(line)).length;
+
+    if (filesChanged === 0) {
+      return {
+        verified: false,
+        filesChanged: 0,
+        message: 'No deliverables created despite implementation task (consensus on plans only)'
+      };
+    }
+
+    return {
+      verified: true,
+      filesChanged,
+      message: `Deliverables verified: ${filesChanged} files changed`
+    };
+  } catch (error) {
+    // If git command fails, assume no verification needed
+    return {
+      verified: true,
+      filesChanged: 0,
+      message: 'Git verification skipped (not a git repository or error)'
+    };
+  }
+}
+
+/**
+ * Override PROCEED to ITERATE if deliverables missing
+ *
+ * Implements deliverable verification logic from execute-decision.sh
+ */
+export async function applyDeliverableVerification(
+  decision: ProductOwnerDecision,
+  taskContext: string
+): Promise<ProductOwnerDecision> {
+  if (decision.decision !== 'PROCEED' || !decision.deliverableVerificationRequired) {
+    return decision;
+  }
+
+  const verification = await verifyDeliverables(taskContext);
+
+  if (!verification.verified) {
+    return {
+      ...decision,
+      decision: 'ITERATE',
+      reasoning: `Override PROCEED → ITERATE: ${verification.message}. Validators approved plans without actual code.`,
+      confidence: 0.70,
+      deliverableVerificationPassed: false
+    };
+  }
+
+  return {
+    ...decision,
+    deliverableVerificationPassed: true
+  };
+}
+
+/**
+ * Extract deferred items from Product Owner output
+ *
+ * Looks for sections: "Out of Scope", "Deferred", "Future Work", "Defer:"
+ * Returns list of items to add to backlog
+ */
+export function extractDeferredItems(output: string): string[] {
+  const deferredItems: string[] = [];
+
+  // Find deferred section
+  const deferredSectionMatch = output.match(
+    /(?:out of scope|deferred|future work|defer:).{0,1000}/is
+  );
+
+  if (!deferredSectionMatch) {
+    return deferredItems;
+  }
+
+  const deferredSection = deferredSectionMatch[0];
+
+  // Extract bullet points (lines starting with -, *, or •)
+  const bulletPoints = deferredSection.match(/^\s*[-*•]\s*(.+)$/gm);
+
+  if (!bulletPoints) {
+    return deferredItems;
+  }
+
+  for (const line of bulletPoints) {
+    const item = line.replace(/^\s*[-*•]\s*/, '').trim();
+
+    // Skip empty lines, section headers, and very short items
+    if (
+      item.length >= 10 &&
+      !/^(out of scope|deferred|future work)/i.test(item)
+    ) {
+      deferredItems.push(item);
+    }
+  }
+
+  return deferredItems;
+}
+
+/**
+ * Build enhanced Product Owner context with audit insights
+ *
+ * Replicates context building from execute-decision.sh
+ */
+export function buildProductOwnerContext(input: ProductOwnerDecisionInput): string {
+  const {
+    iteration,
+    maxIterations,
+    consensus,
+    threshold,
+    successCriteria,
+    loop2Feedback,
+    taskContext
+  } = input;
+
+  return `
+You are the Product Owner making a strategic decision for CFN Loop iteration ${iteration} of ${maxIterations}.
+
+CURRENT ITERATION DATA:
+Loop 2 Consensus: ${consensus}
+Threshold: ${threshold}
+Success Criteria: ${successCriteria || 'Not specified'}
+
+Loop 2 Feedback:
+${loop2Feedback || 'No feedback provided'}
+
+Task Context:
+${taskContext || 'No context provided'}
+
+DECISION OPTIONS:
+- PROCEED: Quality threshold met, deliverables complete
+- ITERATE: Improvements needed, iterations remaining
+- ABORT: Max iterations reached or systematic failure
+
+Output format:
+Decision: PROCEED|ITERATE|ABORT
+Reasoning: [your explanation]
+Confidence: [0.0-1.0]
+`.trim();
+}

package/claude-assets/skills/cfn-loop-orchestration/src/helpers/spawn-agents.ts

@@ -0,0 +1,357 @@
+/**
+ * Agent Spawning Helper - TypeScript Implementation
+ *
+ * Spawns Loop 3 and Loop 2 agents with enriched context injection.
+ * Wraps npx claude-flow-novice agent with format validation and dry-run support.
+ *
+ * @module helpers/spawn-agents
+ */
+
+import { spawn } from 'child_process';
+import * as path from 'path';
+import * as fs from 'fs/promises';
+
+/**
+ * Agent spawning result
+ */
+export interface SpawnResult {
+  agentId: string;
+  agentType: string;
+  success: boolean;
+  pid?: number | undefined;
+  error?: string | undefined;
+}
+
+/**
+ * Agent spawning summary
+ */
+export interface SpawnSummary {
+  totalSpawned: number;
+  successCount: number;
+  failureCount: number;
+  results: SpawnResult[];
+  duration: number;
+}
+
+/**
+ * Spawn agents configuration
+ */
+export interface SpawnAgentsConfig {
+  taskId: string;
+  iteration: number;
+  phase: 'loop3' | 'loop2' | 'product-owner';
+  agents: string[];
+  originalContext: string;
+  dryRun?: boolean;
+  logDir?: string;
+  projectRoot?: string;
+}
+
+/**
+ * Validates agent type name format
+ * Allows agent names like: backend-developer, code-reviewer, security-specialist
+ */
+function validateAgentType(agentType: string): boolean {
+  // Allow alphanumeric, hyphens, underscores (agent names)
+  return /^[a-z0-9_-]+$/i.test(agentType);
+}
+
+/**
+ * Sanitizes input to prevent injection attacks
+ * Allows only alphanumeric, dash, underscore, dot, comma, colon
+ */
+function sanitizeInput(input: string): string {
+  return input.replace(/[^a-zA-Z0-9._:,\-]/g, '');
+}
+
+/**
+ * Generates unique agent ID with instance counter
+ */
+function generateAgentId(
+  agentType: string,
+  iteration: number,
+  instanceNum: number
+): string {
+  return `${agentType}-${iteration}-${instanceNum}`;
+}
+
+/**
+ * Formats the agent spawn CLI command
+ * Correct format: npx claude-flow-novice agent <type> --task-id <id> --context <ctx>
+ */
+function formatSpawnCommand(
+  agentType: string,
+  taskId: string,
+  agentId: string,
+  iteration: number,
+  context: string
+): string[] {
+  return [
+    'npx',
+    'claude-flow-novice',
+    'agent',
+    agentType,
+    '--task-id',
+    taskId,
+    '--agent-id',
+    agentId,
+    '--iteration',
+    iteration.toString(),
+    '--context',
+    context,
+  ];
+}
+
+/**
+ * Validates CLI command format
+ */
+function validateCommandFormat(command: string[]): boolean {
+  if (!Array.isArray(command) || command.length === 0) {
+    return false;
+  }
+
+  if (command[0] !== 'npx' || command[1] !== 'claude-flow-novice') {
+    return false;
+  }
+
+  if (command[2] !== 'agent') {
+    return false;
+  }
+
+  // Validate required parameters
+  const hasTaskId = command.includes('--task-id');
+  const hasAgentId = command.includes('--agent-id');
+  const hasIteration = command.includes('--iteration');
+  const hasContext = command.includes('--context');
+
+  return hasTaskId && hasAgentId && hasIteration && hasContext;
+}
+
+/**
+ * Logs message to file and console
+ */
+async function logMessage(
+  logDir: string,
+  taskId: string,
+  level: string,
+  message: string
+): Promise<void> {
+  const timestamp = new Date().toISOString();
+  const logEntry = `[${timestamp}] [${level}] ${message}`;
+
+  // Log to console
+  console.log(logEntry);
+
+  // Log to file
+  try {
+    const logFile = path.join(logDir, `spawn-agents-${taskId}.log`);
+    await fs.appendFile(logFile, `${logEntry}\n`);
+  } catch (error) {
+    console.error(`Failed to write to log file: ${error}`);
+  }
+}
+
+/**
+ * Spawns a single agent
+ */
+async function spawnSingleAgent(
+  config: SpawnAgentsConfig,
+  agentType: string,
+  instanceNum: number,
+  logDir: string
+): Promise<SpawnResult> {
+  const safeAgentType = sanitizeInput(agentType);
+  const safeTaskId = sanitizeInput(config.taskId);
+  const agentId = generateAgentId(safeAgentType, config.iteration, instanceNum);
+  const safeAgentId = sanitizeInput(agentId);
+
+  await logMessage(logDir, config.taskId, 'INFO', `Spawning agent: ${safeAgentType} (ID: ${safeAgentId})`);
+
+  const command = formatSpawnCommand(
+    safeAgentType,
+    safeTaskId,
+    safeAgentId,
+    config.iteration,
+    config.originalContext
+  );
+
+  // Validate command format
+  if (!validateCommandFormat(command)) {
+    const error = `Invalid command format for agent ${safeAgentType}`;
+    await logMessage(logDir, config.taskId, 'ERROR', error);
+    return {
+      agentId: safeAgentId,
+      agentType: safeAgentType,
+      success: false,
+      error,
+    };
+  }
+
+  // Dry-run mode: just log the command without executing
+  if (config.dryRun) {
+    const cmdStr = command.join(' ');
+    await logMessage(logDir, config.taskId, 'INFO', `DRY-RUN: ${cmdStr}`);
+    return {
+      agentId: safeAgentId,
+      agentType: safeAgentType,
+      success: true,
+    };
+  }
+
+  try {
+    // Spawn command in background
+    const cmd = command[0];
+    if (!cmd) {
+      throw new Error('Command is empty');
+    }
+
+    const child = spawn(cmd, command.slice(1), {
+      detached: true,
+      stdio: 'ignore',
+    });
+
+    const pid = child.pid;
+    await logMessage(logDir, config.taskId, 'INFO', `Agent ${safeAgentType} spawned (PID: ${pid || 'unknown'})`);
+
+    // Unref to allow parent process to exit
+    child.unref();
+
+    return {
+      agentId: safeAgentId,
+      agentType: safeAgentType,
+      success: true,
+      pid: pid ?? undefined,
+    };
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    await logMessage(logDir, config.taskId, 'ERROR', `Failed to spawn ${safeAgentType}: ${errorMsg}`);
+    return {
+      agentId: safeAgentId,
+      agentType: safeAgentType,
+      success: false,
+      error: errorMsg,
+    };
+  }
+}
+
+/**
+ * Main agent spawning function
+ *
+ * Spawns multiple agents with enriched context injection.
+ * Returns spawn summary with results and metrics.
+ *
+ * @param config - Spawn configuration
+ * @returns Spawn summary with results
+ * @throws Error if required parameters are missing or invalid
+ */
+export async function spawnAgents(config: SpawnAgentsConfig): Promise<SpawnSummary> {
+  const startTime = Date.now();
+
+  // Validate required parameters
+  if (!config.taskId || typeof config.taskId !== 'string') {
+    throw new Error('Task ID is required and must be a string');
+  }
+
+  if (config.iteration < 0 || !Number.isInteger(config.iteration)) {
+    throw new Error('Iteration must be a non-negative integer');
+  }
+
+  if (!Array.isArray(config.agents) || config.agents.length === 0) {
+    throw new Error('Agents array is required and must not be empty');
+  }
+
+  if (!config.originalContext || typeof config.originalContext !== 'string') {
+    throw new Error('Original context is required and must be a string');
+  }
+
+  // Validate all agents
+  for (const agent of config.agents) {
+    if (!validateAgentType(agent)) {
+      throw new Error(`Invalid agent type: ${agent}. Must be alphanumeric with hyphens/underscores (e.g., backend-developer)`);
+    }
+  }
+
+  // Setup log directory
+  const logDir = config.logDir || '.artifacts/logs';
+  try {
+    await fs.mkdir(logDir, { recursive: true });
+  } catch (error) {
+    console.error(`Failed to create log directory: ${error}`);
+  }
+
+  await logMessage(logDir, config.taskId, 'INFO', `Starting agent spawning (iteration ${config.iteration})`);
+
+  // Spawn agents
+  const results: SpawnResult[] = [];
+  const instanceCounts = new Map<string, number>();
+
+  for (const agent of config.agents) {
+    const trimmedAgent = agent.trim();
+    const instanceNum = (instanceCounts.get(trimmedAgent) || 0) + 1;
+    instanceCounts.set(trimmedAgent, instanceNum);
+
+    const result = await spawnSingleAgent(config, trimmedAgent, instanceNum, logDir);
+    results.push(result);
+  }
+
+  const endTime = Date.now();
+  const duration = endTime - startTime;
+
+  const successCount = results.filter((r) => r.success).length;
+  const failureCount = results.filter((r) => !r.success).length;
+
+  await logMessage(
+    logDir,
+    config.taskId,
+    'INFO',
+    `Agent spawning complete: ${successCount} succeeded, ${failureCount} failed`
+  );
+
+  return {
+    totalSpawned: results.length,
+    successCount,
+    failureCount,
+    results,
+    duration,
+  };
+}
+
+/**
+ * Spawns Loop 3 agents for given iteration
+ */
+export async function spawnLoop3Agents(
+  taskId: string,
+  iteration: number,
+  agentTypes: string[],
+  context: string,
+  dryRun?: boolean
+): Promise<SpawnSummary> {
+  return spawnAgents({
+    taskId,
+    iteration,
+    phase: 'loop3',
+    agents: agentTypes,
+    originalContext: context,
+    dryRun: dryRun ?? false,
+  });
+}
+
+/**
+ * Spawns Loop 2 agents for given iteration
+ */
+export async function spawnLoop2Agents(
+  taskId: string,
+  iteration: number,
+  agentTypes: string[],
+  context: string,
+  dryRun?: boolean
+): Promise<SpawnSummary> {
+  return spawnAgents({
+    taskId,
+    iteration,
+    phase: 'loop2',
+    agents: agentTypes,
+    originalContext: context,
+    dryRun: dryRun ?? false,
+  });
+}