refactor: add numbered step comments to 20 complex sequential functions

- Add // N. Description steps to temporal layer (client, activities, workflows)
- Add steps to AI layer (claude-executor: runClaudePrompt, buildMcpServers)
- Add steps to services layer (prompt-manager, config-parser, git-manager)
- Add steps to audit layer (metrics-tracker, audit-session)
- Update CLAUDE.md comment guidelines with clearer numbered-step vs section-divider guidance

src/audit/audit-session.ts

@@ -107,18 +107,20 @@ export class AuditSession {
   ): Promise<void> {
     await this.ensureInitialized();
 
-    // Save prompt snapshot (only on first attempt)
+    // 1. Save prompt snapshot (only on first attempt)
     if (attemptNumber === 1) {
       await AgentLogger.savePrompt(this.sessionMetadata, agentName, promptContent);
     }
 
+    // 2. Create and initialize the per-agent logger
     this.currentAgentName = agentName;
-
     this.currentLogger = new AgentLogger(this.sessionMetadata, agentName, attemptNumber);
     await this.currentLogger.initialize();
 
+    // 3. Start metrics timer
     this.metricsTracker.startAgent(agentName, attemptNumber);
 
+    // 4. Log start event to both agent log and workflow log
     await this.currentLogger.logEvent('agent_start', {
       agentName,
       attemptNumber,
@@ -172,6 +174,7 @@ export class AuditSession {
    * End agent execution (mutex-protected)
    */
   async endAgent(agentName: string, result: AgentEndResult): Promise<void> {
+    // 1. Finalize agent log and close the stream
     if (this.currentLogger) {
       await this.currentLogger.logEvent('agent_end', {
         agentName,
@@ -185,6 +188,7 @@ export class AuditSession {
       this.currentLogger = null;
     }
 
+    // 2. Log completion to the unified workflow log
     this.currentAgentName = null;
 
     const agentLogDetails: AgentLogDetails = {
@@ -196,12 +200,11 @@ export class AuditSession {
     };
     await this.workflowLogger.logAgent(agentName, 'end', agentLogDetails);
 
-    // Mutex-protected update to session.json
+    // 3. Acquire mutex before touching session.json
     const unlock = await sessionMutex.lock(this.sessionId);
     try {
-      // Reload inside mutex to prevent lost updates during parallel exploitation phase
+      // 4. Reload-then-write inside mutex to prevent lost updates during parallel phases
       await this.metricsTracker.reload();
-
       await this.metricsTracker.endAgent(agentName, result);
     } finally {
       unlock();

src/audit/metrics-tracker.ts

@@ -170,7 +170,7 @@ export class MetricsTracker {
       );
     }
 
-    // Initialize agent metrics if not exists
+    // 1. Initialize agent metrics if first time seeing this agent
     const existingAgent = this.data.metrics.agents[agentName];
     const agent = existingAgent ?? {
       status: 'in-progress' as const,
@@ -180,7 +180,7 @@ export class MetricsTracker {
     };
     this.data.metrics.agents[agentName] = agent;
 
-    // Add attempt to array
+    // 2. Build attempt record with optional model/error fields
     const attempt: AttemptData = {
       attempt_number: result.attemptNumber,
       duration_ms: result.duration_ms,
@@ -197,16 +197,18 @@ export class MetricsTracker {
       attempt.error = result.error;
     }
 
+    // 3. Append attempt to history
     agent.attempts.push(attempt);
 
-    // Update total cost (includes failed attempts)
+    // 4. Recalculate total cost across all attempts (includes failures)
     agent.total_cost_usd = agent.attempts.reduce((sum, a) => sum + a.cost_usd, 0);
 
-    // If successful, update final metrics and status
+    // 5. Update agent status based on outcome
     if (result.success) {
       agent.status = 'success';
       agent.final_duration_ms = result.duration_ms;
 
+      // 6. Attach model and checkpoint metadata on success
       if (result.model) {
         agent.model = result.model;
       }
@@ -215,18 +217,18 @@ export class MetricsTracker {
         agent.checkpoint = result.checkpoint;
       }
     } else {
-      // If this was the last attempt, mark as failed
       if (result.isFinalAttempt) {
         agent.status = 'failed';
       }
     }
 
-    // Clear active timer
+    // 7. Clear active timer
     this.activeTimers.delete(agentName);
 
-    // Recalculate aggregations
+    // 8. Recalculate phase and session-level aggregations
     this.recalculateAggregations();
 
+    // 9. Persist to session.json
     await this.save();
   }