agentsys 5.1.0 → 5.2.1

package/plugins/audit-project/lib/perf/investigation-state.js

@@ -1,874 +0,0 @@
-/**
- * Performance investigation state management
- *
- * Stores investigation state and logs under the platform-aware state directory:
- * - {state-dir}/perf/investigation.json
- * - {state-dir}/perf/investigations/{id}.md
- *
- * @module lib/perf/investigation-state
- */
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-const { getStateDir } = require('../platform/state-dir');
-const { validateInvestigationState, assertValid } = require('./schemas');
-const { writeJsonAtomic, writeFileAtomic } = require('../utils/atomic-write');
-const { isPlainObject, updatesApplied, sleepForRetry } = require('../utils/state-helpers');
-
-const SCHEMA_VERSION = 1;
-const INVESTIGATION_FILE = 'investigation.json';
-const LOG_DIR = 'investigations';
-const BASELINE_DIR = 'baselines';
-const PHASES = [
-  'setup',
-  'baseline',
-  'breaking-point',
-  'constraints',
-  'hypotheses',
-  'code-paths',
-  'profiling',
-  'optimization',
-  'decision',
-  'consolidation'
-];
-
-/**
- * Validate and resolve path to prevent path traversal attacks
- * @param {string} basePath - Base directory path
- * @returns {string} Validated absolute path
- */
-function validatePath(basePath) {
-  if (typeof basePath !== 'string' || basePath.length === 0) {
-    throw new Error('Path must be a non-empty string');
-  }
-  const resolved = path.resolve(basePath);
-  if (resolved.includes('\0')) {
-    throw new Error('Path contains invalid null byte');
-  }
-  return resolved;
-}
-
-/**
- * Validate that target path is within base directory
- * @param {string} targetPath - Target file path
- * @param {string} basePath - Base directory
- */
-function validatePathWithinBase(targetPath, basePath) {
-  const resolvedTarget = path.resolve(targetPath);
-  const resolvedBase = path.resolve(basePath);
-  if (!resolvedTarget.startsWith(resolvedBase + path.sep) && resolvedTarget !== resolvedBase) {
-    throw new Error('Path traversal detected');
-  }
-}
-
-function assertSafeInvestigationId(id) {
-  if (!id || typeof id !== 'string') {
-    throw new Error('Investigation id is required');
-  }
-  if (id.includes('..') || id.includes('/') || id.includes('\\') || id.includes('\0')) {
-    throw new Error('Investigation id contains invalid characters');
-  }
-  if (!/^[a-zA-Z0-9._-]+$/.test(id)) {
-    throw new Error('Investigation id contains invalid characters');
-  }
-  return id;
-}
-
-/**
- * Generate a unique investigation ID
- * @returns {string}
- */
-function generateInvestigationId() {
-  const now = new Date();
-  const date = now.toISOString().slice(0, 10).replace(/-/g, '');
-  const time = now.toISOString().slice(11, 19).replace(/:/g, '');
-  const random = crypto.randomBytes(4).toString('hex');
-  return `perf-${date}-${time}-${random}`;
-}
-
-/**
- * Get perf state directory path
- * @param {string} basePath
- * @returns {string}
- */
-function getPerfDir(basePath = process.cwd()) {
-  const validatedBase = validatePath(basePath);
-  const perfDir = path.join(validatedBase, getStateDir(basePath), 'perf');
-  validatePathWithinBase(perfDir, validatedBase);
-  return perfDir;
-}
-
-/**
- * Ensure perf directories exist
- * @param {string} basePath
- * @returns {{ perfDir: string, logDir: string, baselineDir: string }}
- */
-function ensurePerfDirs(basePath = process.cwd()) {
-  const perfDir = getPerfDir(basePath);
-  const logDir = path.join(perfDir, LOG_DIR);
-  const baselineDir = path.join(perfDir, BASELINE_DIR);
-
-  if (!fs.existsSync(perfDir)) {
-    fs.mkdirSync(perfDir, { recursive: true });
-  }
-  if (!fs.existsSync(logDir)) {
-    fs.mkdirSync(logDir, { recursive: true });
-  }
-  if (!fs.existsSync(baselineDir)) {
-    fs.mkdirSync(baselineDir, { recursive: true });
-  }
-
-  return { perfDir, logDir, baselineDir };
-}
-
-/**
- * Get path to investigation.json
- * @param {string} basePath
- * @returns {string}
- */
-function getInvestigationPath(basePath = process.cwd()) {
-  const perfDir = getPerfDir(basePath);
-  return path.join(perfDir, INVESTIGATION_FILE);
-}
-
-/**
- * Get path to investigation log
- * @param {string} id
- * @param {string} basePath
- * @returns {string}
- */
-function getInvestigationLogPath(id, basePath = process.cwd()) {
-  const safeId = assertSafeInvestigationId(id);
-  const { logDir } = ensurePerfDirs(basePath);
-  return path.join(logDir, `${safeId}.md`);
-}
-
-/**
- * Read investigation.json
- * @param {string} basePath
- * @returns {object|null}
- */
-function readInvestigation(basePath = process.cwd()) {
-  const investigationPath = getInvestigationPath(basePath);
-  if (!fs.existsSync(investigationPath)) {
-    return null;
-  }
-  try {
-    const parsed = JSON.parse(fs.readFileSync(investigationPath, 'utf8'));
-    const validation = validateInvestigationState(parsed);
-    if (!validation.ok) {
-      console.error(`[CRITICAL] Invalid investigation state at ${investigationPath}: ${validation.errors.join(', ')}`);
-      return null;
-    }
-    return parsed;
-  } catch (error) {
-    console.error(`[CRITICAL] Corrupted investigation.json at ${investigationPath}: ${error.message}`);
-    return null;
-  }
-}
-
-/**
- * Write investigation.json
- * Increments version for optimistic locking
- * @param {object} state
- * @param {string} basePath
- * @returns {boolean}
- */
-function writeInvestigation(state, basePath = process.cwd()) {
-  ensurePerfDirs(basePath);
-  const investigationPath = getInvestigationPath(basePath);
-  const nextState = {
-    ...state,
-    updatedAt: new Date().toISOString(),
-    _version: (state._version || 0) + 1
-  };
-  assertValid(validateInvestigationState(nextState), 'Invalid investigation state');
-  writeJsonAtomic(investigationPath, nextState);
-  return true;
-}
-
-/**
- * Update investigation.json with partial updates
- * Uses optimistic locking with version check and retry
- * @param {object} updates
- * @param {string} basePath
- * @returns {object|null}
- */
-function updateInvestigation(updates, basePath = process.cwd()) {
-  const MAX_RETRIES = 5;
-  let fallbackState = null;
-
-  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
-    const current = readInvestigation(basePath) || {};
-    fallbackState = current;
-    const initialVersion = current._version || 0;
-    const nextState = { ...current };
-
-    for (const [key, value] of Object.entries(updates)) {
-      // Skip internal version field from updates
-      if (key === '_version') continue;
-
-      if (value === null) {
-        nextState[key] = null;
-      } else if (isPlainObject(value) && isPlainObject(nextState[key])) {
-        nextState[key] = { ...nextState[key], ...value };
-      } else {
-        nextState[key] = value;
-      }
-    }
-
-    // Preserve version for write (writeInvestigation will increment it)
-    nextState._version = initialVersion;
-
-    writeInvestigation(nextState, basePath);
-
-    // Re-read to verify our write succeeded
-    const afterWrite = readInvestigation(basePath);
-    if (afterWrite) {
-      fallbackState = afterWrite;
-    }
-    if (afterWrite && afterWrite._version >= initialVersion + 1 && updatesApplied(afterWrite, updates)) {
-      return afterWrite; // Success
-    }
-
-    // Version conflict - retry after brief delay
-    if (attempt < MAX_RETRIES - 1) {
-      const delay = Math.floor(Math.random() * 50) + 10;
-      sleepForRetry(delay);
-    }
-  }
-
-  // All retries exhausted
-  console.error('[ERROR] updateInvestigation: failed to apply updates after max retries');
-  return readInvestigation(basePath) || fallbackState || { ...updates };
-}
-
-/**
- * Initialize a new investigation
- * @param {object} options
- * @param {string} basePath
- * @returns {object}
- */
-function initializeInvestigation(options = {}, basePath = process.cwd()) {
-  const id = options.id || generateInvestigationId();
-  const phase = options.phase || PHASES[0];
-
-  if (!PHASES.includes(phase)) {
-    throw new Error(`Invalid perf phase: ${phase}`);
-  }
-
-  const state = {
-    schemaVersion: SCHEMA_VERSION,
-    id,
-    status: 'in_progress',
-    phase,
-    createdAt: new Date().toISOString(),
-    updatedAt: new Date().toISOString(),
-    scenario: {
-      description: options.scenario || '',
-      metrics: options.metrics || [],
-      successCriteria: options.successCriteria || '',
-      scenarios: Array.isArray(options.scenarios) ? options.scenarios : []
-    },
-    baselines: [],
-    hypotheses: [],
-    codePaths: [],
-    experiments: [],
-    results: [],
-    breakingPoint: null,
-    breakingPointHistory: [],
-    constraintResults: [],
-    profilingResults: [],
-    decision: null
-  };
-
-  assertValid(validateInvestigationState(state), 'Invalid initial investigation state');
-  writeInvestigation(state, basePath);
-  return state;
-}
-
-/**
- * Append a line to the investigation log
- * @param {string} id
- * @param {string} content
- * @param {string} basePath
- */
-function appendInvestigationLog(id, content, basePath = process.cwd()) {
-  if (!content) return;
-  const logPath = getInvestigationLogPath(id, basePath);
-  const entry = content.endsWith('\n') ? content : `${content}\n`;
-  fs.appendFileSync(logPath, entry, 'utf8');
-}
-
-/**
- * Append a baseline section to the investigation log
- * @param {object} input
- * @param {string} input.id
- * @param {string} input.userQuote
- * @param {string} input.command
- * @param {object} input.metrics
- * @param {string} input.baselinePath
- * @param {number} [input.duration]
- * @param {number} [input.runs]
- * @param {string} [input.aggregate]
- * @param {string} [input.date]
- * @param {string} basePath
- */
-function appendBaselineLog(input, basePath = process.cwd()) {
-  if (!input || typeof input !== 'object') {
-    throw new Error('appendBaselineLog requires an input object');
-  }
-
-  const { id, userQuote, command, metrics, baselinePath, date, scenarios, duration, runs, aggregate } = input;
-
-  if (!id || typeof id !== 'string') {
-    throw new Error('appendBaselineLog requires a valid investigation id');
-  }
-  if (!userQuote || typeof userQuote !== 'string') {
-    throw new Error('appendBaselineLog requires a non-empty userQuote');
-  }
-  if (!command || typeof command !== 'string') {
-    throw new Error('appendBaselineLog requires a non-empty command');
-  }
-  if (!metrics || typeof metrics !== 'object' || Array.isArray(metrics)) {
-    throw new Error('appendBaselineLog requires a metrics object');
-  }
-  if (!baselinePath || typeof baselinePath !== 'string') {
-    throw new Error('appendBaselineLog requires a baselinePath');
-  }
-
-  const logDate = date || new Date().toISOString().slice(0, 10);
-  const metricsText = JSON.stringify(metrics);
-  const scenarioText = Array.isArray(scenarios) && scenarios.length > 0
-    ? scenarios.map((scenario) => scenario.name).filter(Boolean).join(', ')
-    : '';
-  const durationLine = Number.isFinite(duration) ? `- Duration: ${duration}s` : null;
-  const runsLine = Number.isFinite(runs) ? `- Runs: ${runs}` : null;
-  const aggregateLine = aggregate ? `- Aggregate: ${aggregate}` : null;
-
-  const entry = [
-    `## Baseline - ${logDate}`,
-    '',
-    `**User Quote:** "${userQuote}"`,
-    '',
-    '**Summary**',
-    scenarioText ? `- Scenarios: ${scenarioText}` : null,
-    `- Baseline command: \`${command}\``,
-    durationLine,
-    runsLine,
-    aggregateLine,
-    `- Metrics: ${metricsText}`,
-    '',
-    '**Evidence**',
-    `- Baseline file: ${baselinePath}`,
-    ''
-  ].filter(Boolean).join('\n');
-
-  appendInvestigationLog(id, entry, basePath);
-}
-
-/**
- * Append a profiling section to the investigation log
- * @param {object} input
- * @param {string} input.id
- * @param {string} input.userQuote
- * @param {string} input.tool
- * @param {string} input.command
- * @param {string[]} input.artifacts
- * @param {string[]} input.hotspots
- * @param {string} [input.date]
- * @param {string} basePath
- */
-function appendProfilingLog(input, basePath = process.cwd()) {
-  if (!input || typeof input !== 'object') {
-    throw new Error('appendProfilingLog requires an input object');
-  }
-
-  const { id, userQuote, tool, command, artifacts, hotspots, date } = input;
-
-  if (!id || typeof id !== 'string') {
-    throw new Error('appendProfilingLog requires a valid investigation id');
-  }
-  if (!userQuote || typeof userQuote !== 'string') {
-    throw new Error('appendProfilingLog requires a non-empty userQuote');
-  }
-  if (!tool || typeof tool !== 'string') {
-    throw new Error('appendProfilingLog requires a tool');
-  }
-  if (!command || typeof command !== 'string') {
-    throw new Error('appendProfilingLog requires a command');
-  }
-
-  const logDate = date || new Date().toISOString().slice(0, 10);
-  const artifactList = Array.isArray(artifacts) ? artifacts : [];
-  const hotspotList = Array.isArray(hotspots) ? hotspots : [];
-
-  const entry = [
-    `## Profiling - ${logDate}`,
-    '',
-    `**User Quote:** "${userQuote}"`,
-    '',
-    '**Summary**',
-    `- Tool: ${tool}`,
-    `- Command: \`${command}\``,
-    '',
-    '**Evidence**',
-    artifactList.length ? `- Artifacts: ${artifactList.join(', ')}` : '- Artifacts: n/a',
-    hotspotList.length ? `- Hotspots: ${hotspotList.join(', ')}` : '- Hotspots: n/a',
-    ''
-  ].join('\n');
-
-  appendInvestigationLog(id, entry, basePath);
-}
-
-/**
- * Append a decision section to the investigation log
- * @param {object} input
- * @param {string} input.id
- * @param {string} input.userQuote
- * @param {string} input.verdict
- * @param {string} input.rationale
- * @param {string} [input.date]
- * @param {string} basePath
- */
-function appendDecisionLog(input, basePath = process.cwd()) {
-  if (!input || typeof input !== 'object') {
-    throw new Error('appendDecisionLog requires an input object');
-  }
-
-  const { id, userQuote, verdict, rationale, date, resultsCount } = input;
-
-  if (!id || typeof id !== 'string') {
-    throw new Error('appendDecisionLog requires a valid investigation id');
-  }
-  if (!userQuote || typeof userQuote !== 'string') {
-    throw new Error('appendDecisionLog requires a non-empty userQuote');
-  }
-  if (!verdict || typeof verdict !== 'string') {
-    throw new Error('appendDecisionLog requires a verdict');
-  }
-  if (!rationale || typeof rationale !== 'string') {
-    throw new Error('appendDecisionLog requires a rationale');
-  }
-
-  const logDate = date || new Date().toISOString().slice(0, 10);
-  const resultCountText = typeof resultsCount === 'number' ? String(resultsCount) : 'n/a';
-
-  const entry = [
-    `## Decision - ${logDate}`,
-    '',
-    `**User Quote:** "${userQuote}"`,
-    '',
-    '**Summary**',
-    `- Verdict: ${verdict}`,
-    `- Rationale: ${rationale}`,
-    '',
-    '**Evidence**',
-    `- Results count: ${resultCountText}`,
-    ''
-  ].join('\n');
-
-  appendInvestigationLog(id, entry, basePath);
-}
-
-/**
- * Append a setup section to the investigation log
- * @param {object} input
- * @param {string} input.id
- * @param {string} input.userQuote
- * @param {string} input.scenario
- * @param {string} input.command
- * @param {string} input.version
- * @param {number} [input.duration]
- * @param {number} [input.runs]
- * @param {string} [input.aggregate]
- * @param {string} [input.date]
- * @param {string} basePath
- */
-function appendSetupLog(input, basePath = process.cwd()) {
-  if (!input || typeof input !== 'object') {
-    throw new Error('appendSetupLog requires an input object');
-  }
-
-  const { id, userQuote, scenario, command, version, duration, runs, aggregate, date } = input;
-
-  if (!id || typeof id !== 'string') {
-    throw new Error('appendSetupLog requires a valid investigation id');
-  }
-  if (!userQuote || typeof userQuote !== 'string') {
-    throw new Error('appendSetupLog requires a non-empty userQuote');
-  }
-  if (!scenario || typeof scenario !== 'string') {
-    throw new Error('appendSetupLog requires a scenario');
-  }
-  if (!command || typeof command !== 'string') {
-    throw new Error('appendSetupLog requires a command');
-  }
-  if (!version || typeof version !== 'string') {
-    throw new Error('appendSetupLog requires a version');
-  }
-
-  const logDate = date || new Date().toISOString().slice(0, 10);
-  const durationLine = Number.isFinite(duration) ? `- Duration: ${duration}s` : null;
-  const runsLine = Number.isFinite(runs) ? `- Runs: ${runs}` : null;
-  const aggregateLine = aggregate ? `- Aggregate: ${aggregate}` : null;
-  const entry = [
-    `## Setup - ${logDate}`,
-    '',
-    `**User Quote:** "${userQuote}"`,
-    '',
-    '**Summary**',
-    `- Scenario: ${scenario}`,
-    `- Command: \`${command}\``,
-    `- Version: ${version}`,
-    durationLine,
-    runsLine,
-    aggregateLine,
-    '',
-    '**Evidence**',
-    `- Command: \`${command}\``,
-    `- Version: ${version}`,
-    ''
-  ].filter(Boolean).join('\n');
-
-  appendInvestigationLog(id, entry, basePath);
-}
-
-/**
- * Append a breaking point section to the investigation log
- * @param {object} input
- * @param {string} input.id
- * @param {string} input.userQuote
- * @param {string} input.paramEnv
- * @param {number} input.min
- * @param {number} input.max
- * @param {number|null} input.breakingPoint
- * @param {string} [input.date]
- * @param {string} basePath
- */
-function appendBreakingPointLog(input, basePath = process.cwd()) {
-  if (!input || typeof input !== 'object') {
-    throw new Error('appendBreakingPointLog requires an input object');
-  }
-  const { id, userQuote, paramEnv, min, max, breakingPoint, history, date } = input;
-
-  if (!id || typeof id !== 'string') {
-    throw new Error('appendBreakingPointLog requires a valid investigation id');
-  }
-  if (!userQuote || typeof userQuote !== 'string') {
-    throw new Error('appendBreakingPointLog requires a non-empty userQuote');
-  }
-  if (!paramEnv || typeof paramEnv !== 'string') {
-    throw new Error('appendBreakingPointLog requires a paramEnv');
-  }
-  if (typeof min !== 'number' || typeof max !== 'number') {
-    throw new Error('appendBreakingPointLog requires numeric min/max');
-  }
-
-  const logDate = date || new Date().toISOString().slice(0, 10);
-  const historyText = Array.isArray(history) ? JSON.stringify(history) : 'n/a';
-  const entry = [
-    `## Breaking Point - ${logDate}`,
-    '',
-    `**User Quote:** "${userQuote}"`,
-    '',
-    '**Summary**',
-    `- Param env: ${paramEnv}`,
-    `- Range: ${min}..${max}`,
-    `- Breaking point: ${breakingPoint ?? 'n/a'}`,
-    '',
-    '**Evidence**',
-    `- History: ${historyText}`,
-    ''
-  ].join('\n');
-
-  appendInvestigationLog(id, entry, basePath);
-}
-
-/**
- * Append a constraints section to the investigation log
- * @param {object} input
- * @param {string} input.id
- * @param {string} input.userQuote
- * @param {object} input.constraints
- * @param {object} input.delta
- * @param {string} [input.date]
- * @param {string} basePath
- */
-function appendConstraintLog(input, basePath = process.cwd()) {
-  if (!input || typeof input !== 'object') {
-    throw new Error('appendConstraintLog requires an input object');
-  }
-  const { id, userQuote, constraints, delta, date } = input;
-
-  if (!id || typeof id !== 'string') {
-    throw new Error('appendConstraintLog requires a valid investigation id');
-  }
-  if (!userQuote || typeof userQuote !== 'string') {
-    throw new Error('appendConstraintLog requires a non-empty userQuote');
-  }
-  if (!constraints || typeof constraints !== 'object') {
-    throw new Error('appendConstraintLog requires constraints');
-  }
-  if (!delta || typeof delta !== 'object') {
-    throw new Error('appendConstraintLog requires delta');
-  }
-
-  const logDate = date || new Date().toISOString().slice(0, 10);
-  const entry = [
-    `## Constraints - ${logDate}`,
-    '',
-    `**User Quote:** "${userQuote}"`,
-    '',
-    '**Summary**',
-    `- CPU: ${constraints.cpu || 'n/a'}`,
-    `- Memory: ${constraints.memory || 'n/a'}`,
-    '',
-    '**Evidence**',
-    `- Delta: ${JSON.stringify(delta.metrics || {})}`,
-    ''
-  ].join('\n');
-
-  appendInvestigationLog(id, entry, basePath);
-}
-
-/**
- * Append a hypotheses section to the investigation log
- * @param {object} input
- * @param {string} input.id
- * @param {string} input.userQuote
- * @param {Array} input.hypotheses
- * @param {string} [input.date]
- * @param {string} basePath
- */
-function appendHypothesesLog(input, basePath = process.cwd()) {
-  if (!input || typeof input !== 'object') {
-    throw new Error('appendHypothesesLog requires an input object');
-  }
-  const { id, userQuote, hypotheses, date, gitHistory, hypothesesFile } = input;
-
-  if (!id || typeof id !== 'string') {
-    throw new Error('appendHypothesesLog requires a valid investigation id');
-  }
-  if (!userQuote || typeof userQuote !== 'string') {
-    throw new Error('appendHypothesesLog requires a non-empty userQuote');
-  }
-  if (!Array.isArray(hypotheses)) {
-    throw new Error('appendHypothesesLog requires hypotheses array');
-  }
-
-  const logDate = date || new Date().toISOString().slice(0, 10);
-  const lines = hypotheses.map((item) => {
-    if (!item) return null;
-    const label = item.id ? `${item.id}: ` : '';
-    const evidence = item.evidence ? ` (evidence: ${item.evidence})` : '';
-    const confidence = item.confidence ? ` [${item.confidence}]` : '';
-    return `- ${label}${item.hypothesis || 'n/a'}${confidence}${evidence}`;
-  }).filter(Boolean);
-
-  const entry = [
-    `## Hypotheses - ${logDate}`,
-    '',
-    `**User Quote:** "${userQuote}"`,
-    '',
-    '**Summary**',
-    lines.length > 0 ? lines.join('\n') : '- n/a',
-    '',
-    '**Evidence**',
-    `- Git history: ${Array.isArray(gitHistory) && gitHistory.length ? gitHistory.join(' | ') : 'n/a'}`,
-    hypothesesFile ? `- Hypotheses file: ${hypothesesFile}` : null,
-    ''
-  ].join('\n');
-
-  appendInvestigationLog(id, entry, basePath);
-}
-
-/**
- * Append a code-paths section to the investigation log
- * @param {object} input
- * @param {string} input.id
- * @param {string} input.userQuote
- * @param {string[]} input.keywords
- * @param {Array} input.paths
- * @param {string} [input.date]
- * @param {string} basePath
- */
-function appendCodePathsLog(input, basePath = process.cwd()) {
-  if (!input || typeof input !== 'object') {
-    throw new Error('appendCodePathsLog requires an input object');
-  }
-  const { id, userQuote, keywords, paths, date, repoMapStatus } = input;
-
-  if (!id || typeof id !== 'string') {
-    throw new Error('appendCodePathsLog requires a valid investigation id');
-  }
-  if (!userQuote || typeof userQuote !== 'string') {
-    throw new Error('appendCodePathsLog requires a non-empty userQuote');
-  }
-  if (!Array.isArray(paths)) {
-    throw new Error('appendCodePathsLog requires paths array');
-  }
-
-  const logDate = date || new Date().toISOString().slice(0, 10);
-  const keywordText = Array.isArray(keywords) && keywords.length > 0 ? keywords.join(', ') : 'n/a';
-  const pathLines = paths.map((pathEntry) => {
-    const file = pathEntry.file || 'n/a';
-    const score = typeof pathEntry.score === 'number' ? ` (score: ${pathEntry.score})` : '';
-    const symbols = Array.isArray(pathEntry.symbols) && pathEntry.symbols.length > 0
-      ? ` [${pathEntry.symbols.join(', ')}]`
-      : '';
-    return `- ${file}${score}${symbols}`;
-  });
-
-  const entry = [
-    `## Code Paths - ${logDate}`,
-    '',
-    `**User Quote:** "${userQuote}"`,
-    '',
-    '**Summary**',
-    `- Keywords: ${keywordText}`,
-    pathLines.length > 0 ? pathLines.join('\n') : '- n/a',
-    '',
-    '**Evidence**',
-    `- Repo map: ${repoMapStatus || 'n/a'}`,
-    `- Paths count: ${pathLines.length}`,
-    ''
-  ].join('\n');
-
-  appendInvestigationLog(id, entry, basePath);
-}
-
-/**
- * Append an optimization section to the investigation log
- * @param {object} input
- * @param {string} input.id
- * @param {string} input.userQuote
- * @param {string} input.change
- * @param {object} input.delta
- * @param {string} input.verdict
- * @param {number} [input.runs]
- * @param {string} [input.aggregate]
- * @param {string} [input.date]
- * @param {string} basePath
- */
-function appendOptimizationLog(input, basePath = process.cwd()) {
-  if (!input || typeof input !== 'object') {
-    throw new Error('appendOptimizationLog requires an input object');
-  }
-  const { id, userQuote, change, delta, verdict, date, gitHistory, runs, aggregate } = input;
-
-  if (!id || typeof id !== 'string') {
-    throw new Error('appendOptimizationLog requires a valid investigation id');
-  }
-  if (!userQuote || typeof userQuote !== 'string') {
-    throw new Error('appendOptimizationLog requires a non-empty userQuote');
-  }
-  if (!change || typeof change !== 'string') {
-    throw new Error('appendOptimizationLog requires a change summary');
-  }
-  if (!delta || typeof delta !== 'object') {
-    throw new Error('appendOptimizationLog requires delta');
-  }
-  if (!verdict || typeof verdict !== 'string') {
-    throw new Error('appendOptimizationLog requires a verdict');
-  }
-
-  const logDate = date || new Date().toISOString().slice(0, 10);
-  const gitHistoryText = Array.isArray(gitHistory) && gitHistory.length
-    ? gitHistory.join(' | ')
-    : 'n/a';
-  const runsLine = Number.isFinite(runs) ? `- Runs: ${runs}` : null;
-  const aggregateLine = aggregate ? `- Aggregate: ${aggregate}` : null;
-  const entry = [
-    `## Optimization - ${logDate}`,
-    '',
-    `**User Quote:** "${userQuote}"`,
-    '',
-    '**Summary**',
-    `- Change: ${change}`,
-    `- Verdict: ${verdict}`,
-    runsLine,
-    aggregateLine,
-    '',
-    '**Evidence**',
-    `- Delta: ${JSON.stringify(delta.metrics || {})}`,
-    `- Git history: ${gitHistoryText}`,
-    ''
-  ].join('\n');
-
-  appendInvestigationLog(id, entry, basePath);
-}
-
-/**
- * Append a consolidation section to the investigation log
- * @param {object} input
- * @param {string} input.id
- * @param {string} input.userQuote
- * @param {string} input.version
- * @param {string} input.path
- * @param {string} [input.date]
- * @param {string} basePath
- */
-function appendConsolidationLog(input, basePath = process.cwd()) {
-  if (!input || typeof input !== 'object') {
-    throw new Error('appendConsolidationLog requires an input object');
-  }
-
-  const { id, userQuote, version, path, date } = input;
-
-  if (!id || typeof id !== 'string') {
-    throw new Error('appendConsolidationLog requires a valid investigation id');
-  }
-  if (!userQuote || typeof userQuote !== 'string') {
-    throw new Error('appendConsolidationLog requires a non-empty userQuote');
-  }
-  if (!version || typeof version !== 'string') {
-    throw new Error('appendConsolidationLog requires a version');
-  }
-  if (!path || typeof path !== 'string') {
-    throw new Error('appendConsolidationLog requires a path');
-  }
-
-  const logDate = date || new Date().toISOString().slice(0, 10);
-  const entry = [
-    `## Consolidation - ${logDate}`,
-    '',
-    `**User Quote:** "${userQuote}"`,
-    '',
-    '**Summary**',
-    `- Version: ${version}`,
-    `- Baseline file: ${path}`,
-    '',
-    '**Evidence**',
-    `- Baseline file: ${path}`,
-    ''
-  ].join('\n');
-
-  appendInvestigationLog(id, entry, basePath);
-}
-
-module.exports = {
-  SCHEMA_VERSION,
-  PHASES,
-  generateInvestigationId,
-  getPerfDir,
-  ensurePerfDirs,
-  getInvestigationPath,
-  getInvestigationLogPath,
-  readInvestigation,
-  writeInvestigation,
-  updateInvestigation,
-  initializeInvestigation,
-  appendInvestigationLog,
-  appendBaselineLog,
-  appendProfilingLog,
-  appendDecisionLog,
-  appendSetupLog,
-  appendBreakingPointLog,
-  appendConstraintLog,
-  appendHypothesesLog,
-  appendCodePathsLog,
-  appendOptimizationLog,
-  appendConsolidationLog
-};