Improve type safety and documentation in helper functions

- Add ExecutionResultData interface for type safety
- Add comprehensive JSDoc comments with @param and @returns tags
- Remove unused checkMcpProfile function
- Update function signatures to use proper types instead of any

Co-authored-by: clduab11 <185000089+clduab11@users.noreply.github.com>

Author: Copilot

src/cli/doctor-helpers.ts

@@ -79,32 +79,6 @@ export function checkCodexAuth(): HealthCheck {
   };
 }
 
-/**
- * Check MCP profile health
- * Note: This function is not used in the refactored code as the doctor command
- * handles MCP checks directly using serviceManager from env/service-manager.ts
- */
-export async function checkMcpProfile(
-  profileName: string
-): Promise<HealthCheck> {
-  try {
-    // This function is kept for potential future use but not currently called
-    return {
-      id: `mcp.${profileName}`,
-      ok: false,
-      details: `Profile checking not implemented in this helper`,
-      remediation: `Use serviceManager.status(${profileName}) directly`
-    };
-  } catch (error) {
-    return {
-      id: `mcp.${profileName}`,
-      ok: false,
-      details: `Error checking profile ${profileName}: ${error instanceof Error ? error.message : String(error)}`,
-      remediation: `Verify profile ${profileName} exists and is configured correctly.`
-    };
-  }
-}
-
 /**
  * Render health check results
  */

src/cli/hive-mind-helpers.ts

@@ -9,6 +9,43 @@ import type {
   CodexContext
 } from '../types/codex-context.js';
 
+/**
+ * Execution result data structure
+ */
+export interface ExecutionResultData {
+  executionId: string;
+  status: string;
+  duration: number;
+  originalPrompt: string;
+  summary?: string;
+  artifacts: Record<string, any>;
+  stages: any[];
+  agentCount: number;
+  taskCount: number;
+  meshStatus: {
+    nodeCount: number;
+    connectionCount: number;
+  };
+  consensusStatus: {
+    performed: boolean;
+    proposalId?: string;
+    accepted?: boolean;
+    votes?: any;
+    timedOut?: boolean;
+    error?: string;
+  };
+  swarmStatus: {
+    algorithm: string;
+    isOptimizing: boolean;
+  };
+  totPlan?: any;
+  codexContext: {
+    enabled: boolean;
+    contextHash?: string;
+    sizeBytes?: number;
+  };
+}
+
 /**
  * Execute GOAP workflow
  */
@@ -49,6 +86,14 @@ export async function executeGoapWorkflow(
 
 /**
  * Execute task with timeout and consensus
+ * @param system - The Codex Synaptic system instance
+ * @param prompt - The task prompt to execute
+ * @param originalPrompt - The original user prompt before enrichment
+ * @param config - The hive-mind configuration
+ * @param startTime - The execution start timestamp
+ * @param shouldRequireConsensus - Function to check if consensus is needed
+ * @param orchestrateConsensus - Function to orchestrate consensus voting
+ * @returns Object containing outcome, consensusResult, and totalTime
  */
 export async function executeTaskWithConsensus(
   system: CodexSynapticSystem,
@@ -90,6 +135,13 @@ export async function executeTaskWithConsensus(
 
 /**
  * Collect and format execution results
+ * @param outcome - The task execution outcome
+ * @param consensusResult - The consensus voting result
+ * @param totalTime - Total execution time in milliseconds
+ * @param originalPrompt - The original user prompt
+ * @param system - The Codex Synaptic system instance
+ * @param codexContext - Optional Codex context if enabled
+ * @returns Structured execution result data
  */
 export function collectExecutionResults(
   outcome: any,
@@ -98,7 +150,7 @@ export function collectExecutionResults(
   originalPrompt: string,
   system: CodexSynapticSystem,
   codexContext?: CodexContext
-): any {
+): ExecutionResultData {
   const swarmStatus = system.getSwarmCoordinator().getStatus();
   const meshStatus = system.getNeuralMesh().getStatus();
   const agentRegistry = system.getAgentRegistry().getStatus();
@@ -143,9 +195,11 @@ export function collectExecutionResults(
 
 /**
  * Render execution summary
+ * @param resultData - Structured execution result data
+ * @param options - Rendering options (yaml and debug flags)
  */
 export async function renderExecutionSummary(
-  resultData: any,
+  resultData: ExecutionResultData,
   options: { yaml?: boolean; debug?: boolean }
 ): Promise<void> {
   console.log(chalk.green(`\n🎉 Hive-mind execution completed in ${resultData.duration}ms`));