refactor: remove ~70 low-value comments across 13 files

- Remove empty section markers (// === ... ===, // --- ... ---) that duplicate JSDoc or function names
- Remove "what" comments that restate the next line of code (e.g. // Save to disk, // Check for retryable patterns)
- Remove file-level descriptions that restate the filename (e.g. // Pure functions for formatting console output)
- Fix "Added by client" comment referencing implementation history → "Used for audit correlation"
- Preserve all WHY comments: error classification groups, billing/session limit explanations, ESM interop, exactOptionalPropertyTypes, mutex reasoning

src/temporal/activities.ts

@@ -194,8 +194,6 @@ async function runAgentActivity(
   }
 }
 
-// === Individual Agent Activity Exports ===
-
 export async function runPreReconAgent(input: ActivityInput): Promise<AgentMetrics> {
   return runAgentActivity('pre-recon', input);
 }
@@ -248,8 +246,6 @@ export async function runReportAgent(input: ActivityInput): Promise<AgentMetrics
   return runAgentActivity('report', input);
 }
 
-// === Report Assembly Activities ===
-
 /**
  * Assemble the final report by concatenating exploitation evidence files.
  */
@@ -282,8 +278,6 @@ export async function injectReportMetadataActivity(input: ActivityInput): Promis
   }
 }
 
-// === Exploitation Queue Check ===
-
 /**
  * Check if exploitation should run for a given vulnerability type.
  *
@@ -304,8 +298,6 @@ export async function checkExploitationQueue(
   return checker.checkQueue(vulnType, repoPath, logger);
 }
 
-// === Resume Activities ===
-
 interface SessionJson {
   session: {
     id: string;
@@ -511,8 +503,6 @@ export async function recordResumeAttempt(
   });
 }
 
-// === Phase Transition Activities ===
-
 /**
  * Log phase transition to the unified workflow log.
  */

src/temporal/client.ts

@@ -229,7 +229,6 @@ async function startPipeline(): Promise<void> {
       const workspaceExists = await fileExists(sessionPath);
 
       if (workspaceExists) {
-        // === Resume Mode: existing workspace ===
         isResume = true;
         console.log('=== RESUME MODE ===');
         console.log(`Workspace: ${resumeFromWorkspace}\n`);
@@ -255,7 +254,6 @@ async function startPipeline(): Promise<void> {
         workflowId = `${resumeFromWorkspace}_resume_${Date.now()}`;
         sessionId = resumeFromWorkspace;
       } else {
-        // === New Named Workspace ===
         if (!isValidWorkspaceName(resumeFromWorkspace)) {
           console.error(`ERROR: Invalid workspace name: "${resumeFromWorkspace}"`);
           console.error('  Must be 1-128 characters, alphanumeric/hyphens/underscores, starting with alphanumeric');
@@ -269,7 +267,6 @@ async function startPipeline(): Promise<void> {
         sessionId = resumeFromWorkspace;
       }
     } else {
-      // === New Auto-Named Workflow ===
       const hostname = sanitizeHostname(webUrl);
       workflowId = customWorkflowId || `${hostname}_shannon-${Date.now()}`;
       sessionId = workflowId;
@@ -278,8 +275,8 @@ async function startPipeline(): Promise<void> {
     const input: PipelineInput = {
       webUrl,
       repoPath,
-      workflowId, // Add for audit correlation
-      sessionId, // Workspace directory name
+      workflowId,
+      sessionId,
       ...(configPath && { configPath }),
       ...(outputPath && { outputPath }),
       ...(pipelineTestingMode && { pipelineTestingMode }),
@@ -287,7 +284,6 @@ async function startPipeline(): Promise<void> {
       ...(terminatedWorkflows.length > 0 && { terminatedWorkflows }),
     };
 
-    // Determine output directory for display (use sessionId for persistent directory)
     // Use displayOutputPath (host path) if provided, otherwise fall back to outputPath or default
     const effectiveDisplayPath = displayOutputPath || outputPath || './audit-logs';
     const outputDir = `${effectiveDisplayPath}/${sessionId}`;

src/temporal/shared.ts

@@ -3,15 +3,13 @@ import { defineQuery } from '@temporalio/workflow';
 export type { AgentMetrics } from '../types/metrics.js';
 import type { AgentMetrics } from '../types/metrics.js';
 
-// === Types ===
-
 export interface PipelineInput {
   webUrl: string;
   repoPath: string;
   configPath?: string;
   outputPath?: string;
   pipelineTestingMode?: boolean;
-  workflowId?: string; // Added by client, used for audit correlation
+  workflowId?: string; // Used for audit correlation
   sessionId?: string; // Workspace directory name (distinct from workflowId for named workspaces)
   resumeFromWorkspace?: string; // Workspace name to resume from
   terminatedWorkflows?: string[]; // Workflows terminated during resume
@@ -62,6 +60,4 @@ export interface VulnExploitPipelineResult {
   error: string | null;
 }
 
-// === Queries ===
-
 export const getProgress = defineQuery<PipelineProgress>('getProgress');

src/temporal/workflows.ts

@@ -105,11 +105,9 @@ export async function pentestPipelineWorkflow(
 ): Promise<PipelineState> {
   const { workflowId } = workflowInfo();
 
-  // Select activity proxy based on testing mode
   // Pipeline testing uses fast retry intervals (10s) for quick iteration
   const a = input.pipelineTestingMode ? testActs : acts;
 
-  // Workflow state (queryable)
   const state: PipelineState = {
     status: 'running',
     currentPhase: null,
@@ -122,7 +120,6 @@ export async function pentestPipelineWorkflow(
     summary: null,
   };
 
-  // Register query handler for real-time progress inspection
   setHandler(getProgress, (): PipelineProgress => ({
     ...state,
     workflowId,
@@ -147,18 +144,15 @@ export async function pentestPipelineWorkflow(
     }),
   };
 
-  // === RESUME LOGIC ===
   let resumeState: ResumeState | null = null;
 
   if (input.resumeFromWorkspace) {
-    // Load resume state from existing workspace
     resumeState = await a.loadResumeState(
       input.resumeFromWorkspace,
       input.webUrl,
       input.repoPath
     );
 
-    // Restore git checkpoint and clean up partial deliverables
     const incompleteAgents = ALL_AGENTS.filter(
       (agentName) => !resumeState!.completedAgents.includes(agentName)
     ) as AgentName[];
@@ -169,7 +163,6 @@ export async function pentestPipelineWorkflow(
       incompleteAgents
     );
 
-    // Check if all agents are already complete
     if (resumeState.completedAgents.length === ALL_AGENTS.length) {
       log.info(`All ${ALL_AGENTS.length} agents already completed. Nothing to resume.`);
       state.status = 'completed';
@@ -178,7 +171,6 @@ export async function pentestPipelineWorkflow(
       return state;
     }
 
-    // Record resume attempt in session.json and write resume header to workflow.log
     await a.recordResumeAttempt(
       activityInput,
       input.terminatedWorkflows || [],
@@ -190,7 +182,6 @@ export async function pentestPipelineWorkflow(
     log.info('Resume state loaded and workspace restored');
   }
 
-  // Helper to check if an agent should be skipped
   const shouldSkip = (agentName: string): boolean => {
     return resumeState?.completedAgents.includes(agentName) ?? false;
   };
@@ -413,7 +404,6 @@ export async function pentestPipelineWorkflow(
       state.completedAgents.push('report');
     }
 
-    // === Complete ===
     state.status = 'completed';
     state.currentPhase = null;
     state.currentAgent = null;