@jojonax/codex-copilot 1.5.5 → 1.6.0

package/src/commands/fix.js

@@ -1,447 +1,447 @@
-/**
- * codex-copilot fix - Repair corrupted or malformed project files
- *
- * Scans and repairs all JSON files in .codex-copilot/:
- *   - tasks.json:  validates structure, fixes missing fields, re-indexes
- *   - state.json:  validates checkpoint schema, resets if unrecoverable
- *   - config.json: validates required fields
- *   - rounds.json: validates round history structure
- *
- * Can also be invoked programmatically via autoFix() for self-healing.
- */
-
-import { existsSync, readdirSync } from 'fs';
-import { resolve, basename } from 'path';
-import { log } from '../utils/logger.js';
-import { readJSON, writeJSON, repairRawJSON } from '../utils/json.js';
-
-// ─── Schema Validators & Fixers ───────────────────────────
-
-const TASK_REQUIRED_FIELDS = ['id', 'title', 'description', 'branch', 'status'];
-const VALID_TASK_STATUSES = ['pending', 'in_progress', 'completed', 'blocked', 'skipped', 'developed'];
-
-const DEFAULT_STATE = {
-  current_task: 0,
-  phase: null,
-  phase_step: null,
-  current_pr: null,
-  review_round: 0,
-  branch: null,
-  status: 'initialized',
-  last_updated: new Date().toISOString(),
-};
-
-/**
- * Fix a single JSON file: parse → validate → repair → write back.
- * Returns { fixed, errors, warnings } report.
- */
-function fixFile(filePath, validator) {
-  const report = { file: basename(filePath), fixed: false, repairs: [], errors: [] };
-
-  if (!existsSync(filePath)) {
-    report.errors.push('File does not exist');
-    return report;
-  }
-
-  // Step 1: Try to parse (with auto-repair in readJSON)
-  let data;
-  try {
-    data = readJSON(filePath);
-    // readJSON already does basic corruption repair (BOM, trailing commas, etc.)
-  } catch (parseErr) {
-    // readJSON's auto-repair failed — try our deeper repair
-    try {
-      data = repairRawJSON(filePath);
-      report.repairs.push('Recovered from deep corruption via raw repair');
-    } catch {
-      report.errors.push(`Unrecoverable parse error: ${parseErr.message}`);
-      return report;
-    }
-  }
-
-  // Step 2: Run schema validator/fixer
-  if (validator) {
-    const { data: fixedData, repairs } = validator(data);
-    if (repairs.length > 0) {
-      data = fixedData;
-      report.repairs.push(...repairs);
-    }
-  }
-
-  // Step 3: Write back if any repairs were made
-  if (report.repairs.length > 0) {
-    try {
-      writeJSON(filePath, data);
-      report.fixed = true;
-    } catch (writeErr) {
-      report.errors.push(`Failed to write repaired file: ${writeErr.message}`);
-    }
-  }
-
-  return report;
-}
-
-// ─── Validators ───────────────────────────────────────────
-
-function validateTasks(data) {
-  const repairs = [];
-
-  // Ensure top-level structure
-  if (!data || typeof data !== 'object') {
-    return { data: { project: 'unknown', total: 0, tasks: [] }, repairs: ['Rebuilt empty tasks structure'] };
-  }
-
-  if (!Array.isArray(data.tasks)) {
-    if (data.tasks && typeof data.tasks === 'object') {
-      data.tasks = Object.values(data.tasks);
-      repairs.push('Converted tasks from object to array');
-    } else {
-      data.tasks = [];
-      repairs.push('Missing tasks array — initialized empty');
-    }
-  }
-
-  // Validate each task
-  for (let i = 0; i < data.tasks.length; i++) {
-    const task = data.tasks[i];
-
-    // Ensure task is an object
-    if (!task || typeof task !== 'object') {
-      data.tasks[i] = { id: i + 1, title: `Task ${i + 1}`, description: '', branch: `feature/${String(i + 1).padStart(3, '0')}-unknown`, status: 'pending' };
-      repairs.push(`Task at index ${i}: rebuilt from invalid value`);
-      continue;
-    }
-
-    // Fix missing ID
-    if (task.id === undefined || task.id === null) {
-      task.id = i + 1;
-      repairs.push(`Task at index ${i}: assigned missing id=${task.id}`);
-    }
-
-    // Fix missing required fields
-    if (!task.title) { task.title = `Untitled Task ${task.id}`; repairs.push(`Task #${task.id}: added missing title`); }
-    if (!task.description) { task.description = task.title; repairs.push(`Task #${task.id}: added missing description`); }
-    if (!task.branch) {
-      const slug = task.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 30);
-      task.branch = `feature/${String(task.id).padStart(3, '0')}-${slug}`;
-      repairs.push(`Task #${task.id}: generated missing branch name`);
-    }
-
-    // Fix invalid status
-    if (!task.status || !VALID_TASK_STATUSES.includes(task.status)) {
-      const oldStatus = task.status;
-      task.status = 'pending';
-      repairs.push(`Task #${task.id}: invalid status '${oldStatus}' → 'pending'`);
-    }
-
-    // Ensure depends_on is an array
-    if (task.depends_on && !Array.isArray(task.depends_on)) {
-      task.depends_on = [];
-      repairs.push(`Task #${task.id}: fixed invalid depends_on`);
-    }
-
-    // Ensure acceptance is an array
-    if (task.acceptance && !Array.isArray(task.acceptance)) {
-      if (typeof task.acceptance === 'string') {
-        task.acceptance = [task.acceptance];
-        repairs.push(`Task #${task.id}: converted acceptance string to array`);
-      } else {
-        task.acceptance = [];
-        repairs.push(`Task #${task.id}: fixed invalid acceptance`);
-      }
-    }
-  }
-
-  // Check for duplicate IDs
-  const idMap = new Map();
-  for (const task of data.tasks) {
-    if (idMap.has(task.id)) {
-      // Reassign duplicate ID
-      const newId = Math.max(...data.tasks.map(t => t.id)) + 1;
-      repairs.push(`Task #${task.id}: duplicate ID → reassigned to #${newId}`);
-      task.id = newId;
-    }
-    idMap.set(task.id, true);
-  }
-
-  // Fix total count
-  if (data.total !== data.tasks.length) {
-    repairs.push(`total: ${data.total} → ${data.tasks.length}`);
-    data.total = data.tasks.length;
-  }
-
-  // Ensure project name exists
-  if (!data.project) {
-    data.project = 'Unknown Project';
-    repairs.push('Added missing project name');
-  }
-
-  return { data, repairs };
-}
-
-function validateState(data) {
-  const repairs = [];
-
-  if (!data || typeof data !== 'object') {
-    return { data: { ...DEFAULT_STATE }, repairs: ['Rebuilt from scratch — was not an object'] };
-  }
-
-  // Check and fix each expected field
-  if (typeof data.current_task !== 'number') {
-    data.current_task = parseInt(data.current_task, 10) || 0;
-    repairs.push(`current_task: fixed type → ${data.current_task}`);
-  }
-  if (typeof data.review_round !== 'number') {
-    data.review_round = parseInt(data.review_round, 10) || 0;
-    repairs.push(`review_round: fixed type → ${data.review_round}`);
-  }
-
-  // Validate phase
-  const validPhases = ['develop', 'pr', 'review', 'merge', null];
-  if (!validPhases.includes(data.phase)) {
-    repairs.push(`phase: invalid '${data.phase}' → null`);
-    data.phase = null;
-    data.phase_step = null;
-  }
-
-  // Ensure last_updated exists
-  if (!data.last_updated) {
-    data.last_updated = new Date().toISOString();
-    repairs.push('Added missing last_updated');
-  }
-
-  return { data, repairs };
-}
-
-function validateConfig(data) {
-  const repairs = [];
-
-  if (!data || typeof data !== 'object') {
-    return { data: {}, repairs: ['Config was not an object — replaced with empty'] };
-  }
-
-  // Validate provider
-  if (data.provider && typeof data.provider !== 'string') {
-    data.provider = 'codex-cli';
-    repairs.push('Invalid provider — reset to codex-cli');
-  }
-
-  // Validate numeric fields
-  for (const field of ['max_review_rounds', 'review_poll_interval', 'review_wait_timeout']) {
-    if (data[field] !== undefined && typeof data[field] !== 'number') {
-      const parsed = parseInt(data[field], 10);
-      if (!isNaN(parsed)) {
-        data[field] = parsed;
-        repairs.push(`${field}: converted string to number`);
-      } else {
-        delete data[field];
-        repairs.push(`${field}: removed invalid value`);
-      }
-    }
-  }
-
-  return { data, repairs };
-}
-
-function validateRounds(data) {
-  const repairs = [];
-
-  if (!data || typeof data !== 'object') {
-    return { data: { current_round: 0, rounds: [] }, repairs: ['Rebuilt rounds structure'] };
-  }
-
-  if (typeof data.current_round !== 'number') {
-    data.current_round = parseInt(data.current_round, 10) || 0;
-    repairs.push(`current_round: fixed type → ${data.current_round}`);
-  }
-
-  if (!Array.isArray(data.rounds)) {
-    data.rounds = [];
-    repairs.push('Missing rounds array — initialized empty');
-  }
-
-  return { data, repairs };
-}
-
-// ─── File → Validator mapping ─────────────────────────────
-
-const FILE_VALIDATORS = {
-  'tasks.json': validateTasks,
-  'state.json': validateState,
-  'config.json': validateConfig,
-  'rounds.json': validateRounds,
-};
-
-// ─── Public API ───────────────────────────────────────────
-
-/**
- * Interactive fix command — scans and repairs all project files.
- * Called when user runs: codex-copilot fix
- */
-export async function fix(projectDir) {
-  log.title('🔧 Codex-Copilot File Repair');
-  log.blank();
-
-  const copilotDir = resolve(projectDir, '.codex-copilot');
-  if (!existsSync(copilotDir)) {
-    log.error('Project not initialized. Run: codex-copilot init');
-    process.exit(1);
-  }
-
-  // Phase 1: JSON file repair
-  log.info('Scanning .codex-copilot/ for JSON issues...');
-  log.blank();
-
-  const results = runRepairs(copilotDir);
-  printReport(results);
-
-  // Phase 2: Git state self-healing
-  log.info('Checking git state...');
-  log.blank();
-
-  try {
-    const { git } = await import('../utils/git.js');
-
-    // Lock files
-    const locks = git.clearStaleLocks(projectDir);
-    if (locks.length > 0) {
-      log.info(`🔧 Removed ${locks.length} stale lock file(s)`);
-    } else {
-      log.info('✅ No stale lock files');
-    }
-
-    // Index state (merge/rebase/cherry-pick)
-    git.resolveIndex(projectDir);
-
-    // Detached HEAD
-    const recovered = git.recoverDetachedHead(projectDir);
-    if (recovered) {
-      log.info(`🔧 Recovered from detached HEAD → ${recovered}`);
-    } else {
-      log.info('✅ HEAD is attached to a branch');
-    }
-
-    // Stash check
-    const stash = git.checkOrphanedStash(projectDir);
-    if (stash.found) {
-      log.warn(`⚠ Found ${stash.count} stash entry(s) — run 'git stash list' to review`);
-    } else {
-      log.info('✅ No orphaned stashes');
-    }
-
-    // Repo integrity
-    const integrity = git.verifyRepo(projectDir);
-    if (integrity.ok) {
-      log.info('✅ Git repository integrity OK');
-    }
-
-    log.blank();
-  } catch (err) {
-    log.warn(`Git state check failed: ${err.message}`);
-    log.blank();
-  }
-}
-
-
-/**
- * Auto-fix — called programmatically by other commands when errors are detected.
- * Returns true if all files are healthy (either clean or successfully repaired).
- * @param {string} projectDir - Project root directory
- * @param {object} [options]
- * @param {boolean} [options.silent] - Suppress non-error output
- * @param {string[]} [options.files] - Only fix specific files (e.g. ['tasks.json'])
- * @returns {{ ok: boolean, repaired: string[] }}
- */
-export function autoFix(projectDir, options = {}) {
-  const copilotDir = resolve(projectDir, '.codex-copilot');
-  if (!existsSync(copilotDir)) {
-    return { ok: false, repaired: [] };
-  }
-
-  if (!options.silent) {
-    log.info('🔧 Auto-repairing project files...');
-  }
-
-  const results = runRepairs(copilotDir, options.files);
-  const repaired = results.filter(r => r.fixed).map(r => r.file);
-  const failed = results.filter(r => r.errors.length > 0).map(r => r.file);
-
-  if (!options.silent) {
-    for (const r of results) {
-      if (r.fixed) {
-        log.info(`  ✅ ${r.file}: ${r.repairs.length} issue(s) repaired`);
-      }
-      for (const err of r.errors) {
-        log.error(`  ❌ ${r.file}: ${err}`);
-      }
-    }
-  }
-
-  return { ok: failed.length === 0, repaired };
-}
-
-// ─── Internal helpers ─────────────────────────────────────
-
-function runRepairs(copilotDir, filterFiles) {
-  const results = [];
-
-  for (const [fileName, validator] of Object.entries(FILE_VALIDATORS)) {
-    if (filterFiles && !filterFiles.includes(fileName)) continue;
-    const filePath = resolve(copilotDir, fileName);
-    if (!existsSync(filePath)) continue;
-    results.push(fixFile(filePath, validator));
-  }
-
-  // Also scan for any other .json files (e.g. tasks_round_N.json)
-  if (!filterFiles) {
-    try {
-      const files = readdirSync(copilotDir).filter(f =>
-        f.endsWith('.json') &&
-        !f.endsWith('.tmp') &&
-        !f.endsWith('.bak') &&
-        !Object.keys(FILE_VALIDATORS).includes(f)
-      );
-      for (const fileName of files) {
-        const filePath = resolve(copilotDir, fileName);
-        results.push(fixFile(filePath, null)); // Parse-only repair, no schema validation
-      }
-    } catch { /* ignore directory read errors */ }
-  }
-
-  return results;
-}
-
-function printReport(results) {
-  const totalFixed = results.filter(r => r.fixed).length;
-  const totalErrors = results.filter(r => r.errors.length > 0).length;
-  const totalClean = results.filter(r => !r.fixed && r.errors.length === 0).length;
-
-  for (const r of results) {
-    if (r.errors.length > 0) {
-      log.error(`❌ ${r.file}:`);
-      for (const err of r.errors) {
-        log.error(`   ${err}`);
-      }
-    } else if (r.fixed) {
-      log.info(`🔧 ${r.file}: ${r.repairs.length} issue(s) repaired`);
-      for (const repair of r.repairs) {
-        log.dim(`   ↳ ${repair}`);
-      }
-    } else {
-      log.info(`✅ ${r.file}: OK`);
-    }
-    log.blank();
-  }
-
-  // Summary
-  log.blank();
-  if (totalErrors > 0) {
-    log.error(`Summary: ${totalFixed} file(s) repaired, ${totalErrors} file(s) have unrecoverable errors`);
-    log.warn('For unrecoverable files, try: codex-copilot reset');
-  } else if (totalFixed > 0) {
-    log.title(`✅ Repaired ${totalFixed} file(s), ${totalClean} file(s) were already OK`);
-  } else {
-    log.title('✅ All files are healthy — no repairs needed');
-  }
-  log.blank();
-}
+/**
+ * codex-copilot fix - Repair corrupted or malformed project files
+ *
+ * Scans and repairs all JSON files in .codex-copilot/:
+ *   - tasks.json:  validates structure, fixes missing fields, re-indexes
+ *   - state.json:  validates checkpoint schema, resets if unrecoverable
+ *   - config.json: validates required fields
+ *   - rounds.json: validates round history structure
+ *
+ * Can also be invoked programmatically via autoFix() for self-healing.
+ */
+
+import { existsSync, readdirSync } from 'fs';
+import { resolve, basename } from 'path';
+import { log } from '../utils/logger.js';
+import { readJSON, writeJSON, repairRawJSON } from '../utils/json.js';
+
+// ─── Schema Validators & Fixers ───────────────────────────
+
+const TASK_REQUIRED_FIELDS = ['id', 'title', 'description', 'branch', 'status'];
+const VALID_TASK_STATUSES = ['pending', 'in_progress', 'completed', 'blocked', 'skipped', 'developed'];
+
+const DEFAULT_STATE = {
+  current_task: 0,
+  phase: null,
+  phase_step: null,
+  current_pr: null,
+  review_round: 0,
+  branch: null,
+  status: 'initialized',
+  last_updated: new Date().toISOString(),
+};
+
+/**
+ * Fix a single JSON file: parse → validate → repair → write back.
+ * Returns { fixed, errors, warnings } report.
+ */
+function fixFile(filePath, validator) {
+  const report = { file: basename(filePath), fixed: false, repairs: [], errors: [] };
+
+  if (!existsSync(filePath)) {
+    report.errors.push('File does not exist');
+    return report;
+  }
+
+  // Step 1: Try to parse (with auto-repair in readJSON)
+  let data;
+  try {
+    data = readJSON(filePath);
+    // readJSON already does basic corruption repair (BOM, trailing commas, etc.)
+  } catch (parseErr) {
+    // readJSON's auto-repair failed — try our deeper repair
+    try {
+      data = repairRawJSON(filePath);
+      report.repairs.push('Recovered from deep corruption via raw repair');
+    } catch {
+      report.errors.push(`Unrecoverable parse error: ${parseErr.message}`);
+      return report;
+    }
+  }
+
+  // Step 2: Run schema validator/fixer
+  if (validator) {
+    const { data: fixedData, repairs } = validator(data);
+    if (repairs.length > 0) {
+      data = fixedData;
+      report.repairs.push(...repairs);
+    }
+  }
+
+  // Step 3: Write back if any repairs were made
+  if (report.repairs.length > 0) {
+    try {
+      writeJSON(filePath, data);
+      report.fixed = true;
+    } catch (writeErr) {
+      report.errors.push(`Failed to write repaired file: ${writeErr.message}`);
+    }
+  }
+
+  return report;
+}
+
+// ─── Validators ───────────────────────────────────────────
+
+function validateTasks(data) {
+  const repairs = [];
+
+  // Ensure top-level structure
+  if (!data || typeof data !== 'object') {
+    return { data: { project: 'unknown', total: 0, tasks: [] }, repairs: ['Rebuilt empty tasks structure'] };
+  }
+
+  if (!Array.isArray(data.tasks)) {
+    if (data.tasks && typeof data.tasks === 'object') {
+      data.tasks = Object.values(data.tasks);
+      repairs.push('Converted tasks from object to array');
+    } else {
+      data.tasks = [];
+      repairs.push('Missing tasks array — initialized empty');
+    }
+  }
+
+  // Validate each task
+  for (let i = 0; i < data.tasks.length; i++) {
+    const task = data.tasks[i];
+
+    // Ensure task is an object
+    if (!task || typeof task !== 'object') {
+      data.tasks[i] = { id: i + 1, title: `Task ${i + 1}`, description: '', branch: `feature/${String(i + 1).padStart(3, '0')}-unknown`, status: 'pending' };
+      repairs.push(`Task at index ${i}: rebuilt from invalid value`);
+      continue;
+    }
+
+    // Fix missing ID
+    if (task.id === undefined || task.id === null) {
+      task.id = i + 1;
+      repairs.push(`Task at index ${i}: assigned missing id=${task.id}`);
+    }
+
+    // Fix missing required fields
+    if (!task.title) { task.title = `Untitled Task ${task.id}`; repairs.push(`Task #${task.id}: added missing title`); }
+    if (!task.description) { task.description = task.title; repairs.push(`Task #${task.id}: added missing description`); }
+    if (!task.branch) {
+      const slug = task.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 30);
+      task.branch = `feature/${String(task.id).padStart(3, '0')}-${slug}`;
+      repairs.push(`Task #${task.id}: generated missing branch name`);
+    }
+
+    // Fix invalid status
+    if (!task.status || !VALID_TASK_STATUSES.includes(task.status)) {
+      const oldStatus = task.status;
+      task.status = 'pending';
+      repairs.push(`Task #${task.id}: invalid status '${oldStatus}' → 'pending'`);
+    }
+
+    // Ensure depends_on is an array
+    if (task.depends_on && !Array.isArray(task.depends_on)) {
+      task.depends_on = [];
+      repairs.push(`Task #${task.id}: fixed invalid depends_on`);
+    }
+
+    // Ensure acceptance is an array
+    if (task.acceptance && !Array.isArray(task.acceptance)) {
+      if (typeof task.acceptance === 'string') {
+        task.acceptance = [task.acceptance];
+        repairs.push(`Task #${task.id}: converted acceptance string to array`);
+      } else {
+        task.acceptance = [];
+        repairs.push(`Task #${task.id}: fixed invalid acceptance`);
+      }
+    }
+  }
+
+  // Check for duplicate IDs
+  const idMap = new Map();
+  for (const task of data.tasks) {
+    if (idMap.has(task.id)) {
+      // Reassign duplicate ID
+      const newId = Math.max(...data.tasks.map(t => t.id)) + 1;
+      repairs.push(`Task #${task.id}: duplicate ID → reassigned to #${newId}`);
+      task.id = newId;
+    }
+    idMap.set(task.id, true);
+  }
+
+  // Fix total count
+  if (data.total !== data.tasks.length) {
+    repairs.push(`total: ${data.total} → ${data.tasks.length}`);
+    data.total = data.tasks.length;
+  }
+
+  // Ensure project name exists
+  if (!data.project) {
+    data.project = 'Unknown Project';
+    repairs.push('Added missing project name');
+  }
+
+  return { data, repairs };
+}
+
+function validateState(data) {
+  const repairs = [];
+
+  if (!data || typeof data !== 'object') {
+    return { data: { ...DEFAULT_STATE }, repairs: ['Rebuilt from scratch — was not an object'] };
+  }
+
+  // Check and fix each expected field
+  if (typeof data.current_task !== 'number') {
+    data.current_task = parseInt(data.current_task, 10) || 0;
+    repairs.push(`current_task: fixed type → ${data.current_task}`);
+  }
+  if (typeof data.review_round !== 'number') {
+    data.review_round = parseInt(data.review_round, 10) || 0;
+    repairs.push(`review_round: fixed type → ${data.review_round}`);
+  }
+
+  // Validate phase
+  const validPhases = ['develop', 'pr', 'review', 'merge', null];
+  if (!validPhases.includes(data.phase)) {
+    repairs.push(`phase: invalid '${data.phase}' → null`);
+    data.phase = null;
+    data.phase_step = null;
+  }
+
+  // Ensure last_updated exists
+  if (!data.last_updated) {
+    data.last_updated = new Date().toISOString();
+    repairs.push('Added missing last_updated');
+  }
+
+  return { data, repairs };
+}
+
+function validateConfig(data) {
+  const repairs = [];
+
+  if (!data || typeof data !== 'object') {
+    return { data: {}, repairs: ['Config was not an object — replaced with empty'] };
+  }
+
+  // Validate provider
+  if (data.provider && typeof data.provider !== 'string') {
+    data.provider = 'codex-cli';
+    repairs.push('Invalid provider — reset to codex-cli');
+  }
+
+  // Validate numeric fields
+  for (const field of ['max_review_rounds', 'review_poll_interval', 'review_wait_timeout']) {
+    if (data[field] !== undefined && typeof data[field] !== 'number') {
+      const parsed = parseInt(data[field], 10);
+      if (!isNaN(parsed)) {
+        data[field] = parsed;
+        repairs.push(`${field}: converted string to number`);
+      } else {
+        delete data[field];
+        repairs.push(`${field}: removed invalid value`);
+      }
+    }
+  }
+
+  return { data, repairs };
+}
+
+function validateRounds(data) {
+  const repairs = [];
+
+  if (!data || typeof data !== 'object') {
+    return { data: { current_round: 0, rounds: [] }, repairs: ['Rebuilt rounds structure'] };
+  }
+
+  if (typeof data.current_round !== 'number') {
+    data.current_round = parseInt(data.current_round, 10) || 0;
+    repairs.push(`current_round: fixed type → ${data.current_round}`);
+  }
+
+  if (!Array.isArray(data.rounds)) {
+    data.rounds = [];
+    repairs.push('Missing rounds array — initialized empty');
+  }
+
+  return { data, repairs };
+}
+
+// ─── File → Validator mapping ─────────────────────────────
+
+const FILE_VALIDATORS = {
+  'tasks.json': validateTasks,
+  'state.json': validateState,
+  'config.json': validateConfig,
+  'rounds.json': validateRounds,
+};
+
+// ─── Public API ───────────────────────────────────────────
+
+/**
+ * Interactive fix command — scans and repairs all project files.
+ * Called when user runs: codex-copilot fix
+ */
+export async function fix(projectDir) {
+  log.title('🔧 Codex-Copilot File Repair');
+  log.blank();
+
+  const copilotDir = resolve(projectDir, '.codex-copilot');
+  if (!existsSync(copilotDir)) {
+    log.error('Project not initialized. Run: codex-copilot init');
+    process.exit(1);
+  }
+
+  // Phase 1: JSON file repair
+  log.info('Scanning .codex-copilot/ for JSON issues...');
+  log.blank();
+
+  const results = runRepairs(copilotDir);
+  printReport(results);
+
+  // Phase 2: Git state self-healing
+  log.info('Checking git state...');
+  log.blank();
+
+  try {
+    const { git } = await import('../utils/git.js');
+
+    // Lock files
+    const locks = git.clearStaleLocks(projectDir);
+    if (locks.length > 0) {
+      log.info(`🔧 Removed ${locks.length} stale lock file(s)`);
+    } else {
+      log.info('✅ No stale lock files');
+    }
+
+    // Index state (merge/rebase/cherry-pick)
+    git.resolveIndex(projectDir);
+
+    // Detached HEAD
+    const recovered = git.recoverDetachedHead(projectDir);
+    if (recovered) {
+      log.info(`🔧 Recovered from detached HEAD → ${recovered}`);
+    } else {
+      log.info('✅ HEAD is attached to a branch');
+    }
+
+    // Stash check
+    const stash = git.checkOrphanedStash(projectDir);
+    if (stash.found) {
+      log.warn(`⚠ Found ${stash.count} stash entry(s) — run 'git stash list' to review`);
+    } else {
+      log.info('✅ No orphaned stashes');
+    }
+
+    // Repo integrity
+    const integrity = git.verifyRepo(projectDir);
+    if (integrity.ok) {
+      log.info('✅ Git repository integrity OK');
+    }
+
+    log.blank();
+  } catch (err) {
+    log.warn(`Git state check failed: ${err.message}`);
+    log.blank();
+  }
+}
+
+
+/**
+ * Auto-fix — called programmatically by other commands when errors are detected.
+ * Returns true if all files are healthy (either clean or successfully repaired).
+ * @param {string} projectDir - Project root directory
+ * @param {object} [options]
+ * @param {boolean} [options.silent] - Suppress non-error output
+ * @param {string[]} [options.files] - Only fix specific files (e.g. ['tasks.json'])
+ * @returns {{ ok: boolean, repaired: string[] }}
+ */
+export function autoFix(projectDir, options = {}) {
+  const copilotDir = resolve(projectDir, '.codex-copilot');
+  if (!existsSync(copilotDir)) {
+    return { ok: false, repaired: [] };
+  }
+
+  if (!options.silent) {
+    log.info('🔧 Auto-repairing project files...');
+  }
+
+  const results = runRepairs(copilotDir, options.files);
+  const repaired = results.filter(r => r.fixed).map(r => r.file);
+  const failed = results.filter(r => r.errors.length > 0).map(r => r.file);
+
+  if (!options.silent) {
+    for (const r of results) {
+      if (r.fixed) {
+        log.info(`  ✅ ${r.file}: ${r.repairs.length} issue(s) repaired`);
+      }
+      for (const err of r.errors) {
+        log.error(`  ❌ ${r.file}: ${err}`);
+      }
+    }
+  }
+
+  return { ok: failed.length === 0, repaired };
+}
+
+// ─── Internal helpers ─────────────────────────────────────
+
+function runRepairs(copilotDir, filterFiles) {
+  const results = [];
+
+  for (const [fileName, validator] of Object.entries(FILE_VALIDATORS)) {
+    if (filterFiles && !filterFiles.includes(fileName)) continue;
+    const filePath = resolve(copilotDir, fileName);
+    if (!existsSync(filePath)) continue;
+    results.push(fixFile(filePath, validator));
+  }
+
+  // Also scan for any other .json files (e.g. tasks_round_N.json)
+  if (!filterFiles) {
+    try {
+      const files = readdirSync(copilotDir).filter(f =>
+        f.endsWith('.json') &&
+        !f.endsWith('.tmp') &&
+        !f.endsWith('.bak') &&
+        !Object.keys(FILE_VALIDATORS).includes(f)
+      );
+      for (const fileName of files) {
+        const filePath = resolve(copilotDir, fileName);
+        results.push(fixFile(filePath, null)); // Parse-only repair, no schema validation
+      }
+    } catch { /* ignore directory read errors */ }
+  }
+
+  return results;
+}
+
+function printReport(results) {
+  const totalFixed = results.filter(r => r.fixed).length;
+  const totalErrors = results.filter(r => r.errors.length > 0).length;
+  const totalClean = results.filter(r => !r.fixed && r.errors.length === 0).length;
+
+  for (const r of results) {
+    if (r.errors.length > 0) {
+      log.error(`❌ ${r.file}:`);
+      for (const err of r.errors) {
+        log.error(`   ${err}`);
+      }
+    } else if (r.fixed) {
+      log.info(`🔧 ${r.file}: ${r.repairs.length} issue(s) repaired`);
+      for (const repair of r.repairs) {
+        log.dim(`   ↳ ${repair}`);
+      }
+    } else {
+      log.info(`✅ ${r.file}: OK`);
+    }
+    log.blank();
+  }
+
+  // Summary
+  log.blank();
+  if (totalErrors > 0) {
+    log.error(`Summary: ${totalFixed} file(s) repaired, ${totalErrors} file(s) have unrecoverable errors`);
+    log.warn('For unrecoverable files, try: codex-copilot reset');
+  } else if (totalFixed > 0) {
+    log.title(`✅ Repaired ${totalFixed} file(s), ${totalClean} file(s) were already OK`);
+  } else {
+    log.title('✅ All files are healthy — no repairs needed');
+  }
+  log.blank();
+}