claude-flow-novice 2.15.10 → 2.16.0

package/.claude/skills/cfn-loop-orchestration/src/helpers/context-injector.ts

@@ -0,0 +1,349 @@
+/**
+ * Context Injector - Broadcast Message Builder
+ * Constructs context messages for agent execution in CFN Loop
+ * Implements iteration tracking, phase awareness, and success criteria injection
+ *
+ * Used by: cfn-loop-orchestration to broadcast agent context across Redis
+ * Reference: helpers/context-injection.sh (142 LOC) - shell predecessor
+ */
+
+import { ExecutionMode } from '../types';
+
+/**
+ * Loop phase enumeration
+ */
+export type LoopPhase = 'loop3' | 'loop2' | 'product-owner' | 'iteration-prep';
+
+/**
+ * Success criteria for task execution
+ */
+export interface SuccessCriteria {
+  criteria: string[];
+  testPassRate: number;
+  consensusThreshold: number;
+}
+
+/**
+ * Broadcast context message for agent execution
+ */
+export interface BroadcastContext {
+  taskId: string;
+  iteration: number;
+  phase: LoopPhase;
+  mode: ExecutionMode;
+  agentIds?: string[] | undefined;
+  successCriteria?: SuccessCriteria | undefined;
+  taskDescription?: string | undefined;
+  timestamp: string;
+  contextVersion: string;
+}
+
+/**
+ * Result of successful broadcast context construction
+ */
+export interface BroadcastResult {
+  context: BroadcastContext;
+  json: string;
+  messageCount: number;
+}
+
+/**
+ * Build broadcast context for agent execution
+ *
+ * @param params Context parameters
+ * @returns BroadcastResult with JSON-formatted message
+ * @throws Error if required fields are missing
+ *
+ * @example
+ * ```typescript
+ * const result = buildBroadcastContext({
+ *   taskId: 'task-123',
+ *   iteration: 1,
+ *   phase: 'loop3',
+ *   mode: 'standard',
+ *   agentIds: ['agent-1', 'agent-2']
+ * });
+ *
+ * console.log(result.json); // JSON string for Redis broadcast
+ * ```
+ */
+export function buildBroadcastContext(params: {
+  taskId: string;
+  iteration: number;
+  phase: LoopPhase;
+  mode: ExecutionMode;
+  agentIds?: string[] | undefined;
+  successCriteria?: SuccessCriteria | undefined;
+  taskDescription?: string | undefined;
+}): BroadcastResult {
+  // Validate required fields
+  if (!params.taskId) {
+    throw new Error('taskId is required for broadcast context');
+  }
+
+  if (typeof params.iteration !== 'number' || params.iteration < 1) {
+    throw new Error('iteration must be a positive number');
+  }
+
+  if (!params.phase) {
+    throw new Error('phase is required for broadcast context');
+  }
+
+  if (!params.mode) {
+    throw new Error('mode is required for broadcast context');
+  }
+
+  // Validate phase value
+  const validPhases: LoopPhase[] = ['loop3', 'loop2', 'product-owner', 'iteration-prep'];
+  if (!validPhases.includes(params.phase)) {
+    throw new Error(`Invalid phase: ${params.phase}. Must be one of: ${validPhases.join(', ')}`);
+  }
+
+  // Construct broadcast context
+  const context: BroadcastContext = {
+    taskId: params.taskId,
+    iteration: params.iteration,
+    phase: params.phase,
+    mode: params.mode,
+    timestamp: new Date().toISOString(),
+    contextVersion: '3.0',
+  };
+
+  // Add optional fields if provided
+  if (params.agentIds && Array.isArray(params.agentIds) && params.agentIds.length > 0) {
+    context.agentIds = params.agentIds;
+  }
+
+  if (params.successCriteria) {
+    validateSuccessCriteria(params.successCriteria);
+    context.successCriteria = params.successCriteria;
+  }
+
+  if (params.taskDescription) {
+    context.taskDescription = params.taskDescription;
+  }
+
+  // Serialize to JSON
+  const json = JSON.stringify(context, null, 2);
+
+  return {
+    context,
+    json,
+    messageCount: params.agentIds ? params.agentIds.length : 1,
+  };
+}
+
+/**
+ * Build multiple broadcast messages for different agents
+ *
+ * @param baseContext Base context parameters
+ * @param agentContexts Per-agent context overrides
+ * @returns Array of broadcast contexts
+ *
+ * @example
+ * ```typescript
+ * const messages = buildBroadcastMessages(
+ *   { taskId: 'task-1', iteration: 1, phase: 'loop3', mode: 'standard' },
+ *   [
+ *     { agentId: 'loop3-backend-1', agentType: 'backend-engineer' },
+ *     { agentId: 'loop3-frontend-1', agentType: 'react-frontend-engineer' }
+ *   ]
+ * );
+ * ```
+ */
+export function buildBroadcastMessages(
+  baseContext: {
+    taskId: string;
+    iteration: number;
+    phase: LoopPhase;
+    mode: ExecutionMode;
+    successCriteria?: SuccessCriteria;
+    taskDescription?: string;
+  },
+  agentContexts: Array<{
+    agentId: string;
+    agentType: string;
+  }>
+): BroadcastContext[] {
+  if (!Array.isArray(agentContexts) || agentContexts.length === 0) {
+    throw new Error('agentContexts must be a non-empty array');
+  }
+
+  // Validate base context by building it
+  buildBroadcastContext({
+    ...baseContext,
+    agentIds: agentContexts.map(ac => ac.agentId),
+  });
+
+  // Build individual context for each agent
+  return agentContexts.map(agentCtx => ({
+    taskId: baseContext.taskId,
+    iteration: baseContext.iteration,
+    phase: baseContext.phase,
+    mode: baseContext.mode,
+    agentIds: [agentCtx.agentId] as string[] | undefined,
+    successCriteria: baseContext.successCriteria ?? undefined,
+    taskDescription: baseContext.taskDescription ?? undefined,
+    timestamp: new Date().toISOString(),
+    contextVersion: '3.0',
+  }));
+}
+
+/**
+ * Build iteration-specific broadcast context for agent wake operations
+ *
+ * @param taskId Unique task identifier
+ * @param iteration Current iteration number
+ * @param mode Execution mode
+ * @param feedback Optional feedback for next iteration
+ * @returns BroadcastContext for iteration prep
+ */
+export function buildIterationContext(
+  taskId: string,
+  iteration: number,
+  mode: ExecutionMode,
+  feedback?: unknown
+): BroadcastContext {
+  const taskDescription: string | undefined = feedback ? JSON.stringify(feedback) : undefined;
+  return buildBroadcastContext({
+    taskId,
+    iteration,
+    phase: 'iteration-prep',
+    mode,
+    taskDescription,
+  }).context;
+}
+
+/**
+ * Format context as JSON for Redis broadcast
+ *
+ * @param context Broadcast context
+ * @param compact If true, removes whitespace
+ * @returns JSON string
+ */
+export function formatContextJson(context: BroadcastContext, compact: boolean = false): string {
+  if (compact) {
+    return JSON.stringify(context);
+  }
+  return JSON.stringify(context, null, 2);
+}
+
+/**
+ * Parse broadcast context from JSON
+ *
+ * @param json JSON string containing broadcast context
+ * @returns Parsed BroadcastContext
+ * @throws Error if JSON is invalid or missing required fields
+ */
+export function parseBroadcastContext(json: string): BroadcastContext {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(json);
+  } catch (e) {
+    throw new Error(`Invalid JSON for broadcast context: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  if (typeof parsed !== 'object' || parsed === null) {
+    throw new Error('Broadcast context must be a JSON object');
+  }
+
+  const context = parsed as Record<string, unknown>;
+
+  // Validate required fields
+  if (!context.taskId || typeof context.taskId !== 'string') {
+    throw new Error('taskId must be a non-empty string');
+  }
+
+  if (typeof context.iteration !== 'number') {
+    throw new Error('iteration must be a number');
+  }
+
+  if (!context.phase || typeof context.phase !== 'string') {
+    throw new Error('phase must be a non-empty string');
+  }
+
+  if (!context.mode || typeof context.mode !== 'string') {
+    throw new Error('mode must be a non-empty string');
+  }
+
+  const agentIds: string[] | undefined = context.agentIds ? (context.agentIds as string[]) : undefined;
+  const successCriteria: SuccessCriteria | undefined = context.successCriteria ? (context.successCriteria as SuccessCriteria) : undefined;
+  const taskDescription: string | undefined = context.taskDescription ? (context.taskDescription as string) : undefined;
+
+  return {
+    taskId: context.taskId,
+    iteration: context.iteration,
+    phase: context.phase as LoopPhase,
+    mode: context.mode as ExecutionMode,
+    timestamp: (context.timestamp as string) || new Date().toISOString(),
+    contextVersion: (context.contextVersion as string) || '3.0',
+    agentIds,
+    successCriteria,
+    taskDescription,
+  };
+}
+
+/**
+ * Validate success criteria structure
+ *
+ * @param criteria Success criteria to validate
+ * @throws Error if structure is invalid
+ */
+function validateSuccessCriteria(criteria: SuccessCriteria): void {
+  if (!Array.isArray(criteria.criteria) || criteria.criteria.length === 0) {
+    throw new Error('successCriteria.criteria must be a non-empty array');
+  }
+
+  if (typeof criteria.testPassRate !== 'number' || criteria.testPassRate < 0 || criteria.testPassRate > 1) {
+    throw new Error('successCriteria.testPassRate must be a number between 0 and 1');
+  }
+
+  if (typeof criteria.consensusThreshold !== 'number' || criteria.consensusThreshold < 0 || criteria.consensusThreshold > 1) {
+    throw new Error('successCriteria.consensusThreshold must be a number between 0 and 1');
+  }
+}
+
+/**
+ * Merge multiple broadcast contexts for multi-phase execution
+ *
+ * @param contexts Array of broadcast contexts
+ * @returns Merged context with combined agentIds
+ */
+export function mergeBroadcastContexts(contexts: BroadcastContext[]): BroadcastContext {
+  if (!Array.isArray(contexts) || contexts.length === 0) {
+    throw new Error('contexts must be a non-empty array');
+  }
+
+  const first = contexts[0];
+  if (!first) {
+    throw new Error('First context is undefined');
+  }
+
+  // Validate all contexts have same base properties
+  for (const context of contexts) {
+    if (context.taskId !== first.taskId) {
+      throw new Error('All contexts must have the same taskId for merging');
+    }
+    if (context.iteration !== first.iteration) {
+      throw new Error('All contexts must have the same iteration for merging');
+    }
+  }
+
+  // Merge agent IDs from all contexts
+  const mergedAgentIds = Array.from(
+    new Set(contexts.flatMap(c => c.agentIds || []))
+  );
+
+  return {
+    taskId: first.taskId,
+    iteration: first.iteration,
+    phase: first.phase,
+    mode: first.mode,
+    timestamp: new Date().toISOString(),
+    contextVersion: first.contextVersion,
+    agentIds: mergedAgentIds.length > 0 ? mergedAgentIds : undefined,
+    successCriteria: first.successCriteria ?? undefined,
+    taskDescription: first.taskDescription ?? undefined,
+  };
+}