@kodevibe/harness 0.11.0 → 0.11.1

package/src/init.js

@@ -3,9 +3,13 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const readline = require('node:readline');
+const crypto = require('node:crypto');
 
 const HARNESS_DIR = path.join(__dirname, '..', 'harness');
+const MANIFEST_PATH = '.harness/install-manifest.json';
 let currentBackupTimestamp = null;
+let currentInstallRecords = null;
+let currentInstallPatches = null;
 
 // ─── Template reader ─────────────────────────────────────────
 function readTemplate(name) {
@@ -23,12 +27,77 @@ function getBackupTimestamp() {
   return currentBackupTimestamp;
 }
 
+function toPosixPath(filePath) {
+  return filePath.split(path.sep).join('/');
+}
+
+function hashContent(content) {
+  return `sha256:${crypto.createHash('sha256').update(content).digest('hex')}`;
+}
+
+function hashFile(fullPath) {
+  return hashContent(fs.readFileSync(fullPath));
+}
+
+function isStatePath(relPath) {
+  return STATE_FILES.some(file => relPath === `docs/${file}` || relPath === `.harness/${file}`)
+    || AGENT_MEMORY_FILES.some(file => relPath === `docs/${file}` || relPath === `.harness/${file}`);
+}
+
+function classifyManagedPath(relPath) {
+  if (isStatePath(relPath)) return 'state';
+  if (relPath === '.gitignore' || relPath === '.gitattributes') return 'team-helper';
+  if (relPath === 'CLAUDE.md' || relPath === 'AGENTS.md') return 'root-dispatcher';
+  if (relPath.includes('/skills/')) return 'skill';
+  if (relPath.includes('/agents/') || relPath.includes('/rules/')) return 'agent-or-rule';
+  return 'ide-config';
+}
+
+function isProtectedPath(relPath) {
+  return isStatePath(relPath) || classifyManagedPath(relPath) === 'team-helper';
+}
+
+function fileHasFrameworkMarker(fullPath) {
+  try {
+    const stat = fs.lstatSync(fullPath);
+    if (!stat.isFile() || stat.isSymbolicLink()) return false;
+    return hasFrameworkMarker(fs.readFileSync(fullPath, 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+function startInstallRecording() {
+  currentInstallRecords = [];
+  currentInstallPatches = [];
+}
+
+function stopInstallRecording() {
+  const records = currentInstallRecords || [];
+  const patches = currentInstallPatches || [];
+  currentInstallRecords = null;
+  currentInstallPatches = null;
+  return { records, patches };
+}
+
 // ─── File writer (mkdir -p + conflict check) ─────────────────
 function writeFile(targetDir, relPath, content, overwrite) {
   const fullPath = path.join(targetDir, relPath);
   const exists = fs.existsSync(fullPath);
+  const hashBefore = exists ? hashFile(fullPath) : null;
   if (exists && !overwrite) {
     console.log(`  ⏭  Skipped (exists): ${relPath}`);
+    if (currentInstallRecords && relPath !== MANIFEST_PATH) {
+      currentInstallRecords.push({
+        path: toPosixPath(relPath),
+        type: classifyManagedPath(relPath),
+        action: 'skipped',
+        protected: isProtectedPath(relPath),
+        hashBefore,
+        hashAfter: hashBefore,
+        backupPath: null,
+      });
+    }
     return false;
   }
   let backupRelPath = null;
@@ -42,8 +111,20 @@ function writeFile(targetDir, relPath, content, overwrite) {
   }
   fs.mkdirSync(path.dirname(fullPath), { recursive: true });
   fs.writeFileSync(fullPath, content, 'utf8');
+  const hashAfter = hashFile(fullPath);
   const backupNote = backupRelPath ? ` (backup: ${backupRelPath})` : '';
   console.log(`  ${exists ? '↻' : '✓'}  ${relPath}${backupNote}`);
+  if (currentInstallRecords && relPath !== MANIFEST_PATH) {
+    currentInstallRecords.push({
+      path: toPosixPath(relPath),
+      type: classifyManagedPath(relPath),
+      action: exists ? 'overwritten' : 'created',
+      protected: isProtectedPath(relPath),
+      hashBefore,
+      hashAfter,
+      backupPath: backupRelPath ? toPosixPath(backupRelPath) : null,
+    });
+  }
   return true;
 }
 
@@ -55,6 +136,7 @@ const SKILLS = [
   { id: 'debug', desc: 'Investigate and diagnose issues. Use when debugging or analyzing unexpected behavior.' },
   { id: 'check-impact', desc: 'Assess change blast radius. Use when modifying shared modules or interfaces.' },
   { id: 'breakdown', desc: 'Break down features into implementable stories. Use when planning new features.' },
+  { id: 'docs-bridge', desc: 'Connect project-local documentation to a wiki or docs hub through a safe local index while preserving original sources and visibility boundaries.' },
   { id: 'setup', desc: 'Onboard project into kode:harness. Scans codebase and fills state files. Use after harness init or when state files are empty.' },
   { id: 'wrap-up', desc: 'Capture session lessons and update state files. Use at the end of every session.' },
   { id: 'pivot', desc: 'Propagate direction changes across all state files. Use when project goals, technology, scope, or architecture changes.' },
@@ -90,6 +172,11 @@ const PERSONAL_DIRS = ['agent-memory/'];
 
 const STATE_DEST_DIR = 'docs';
 const PERSONAL_DEST_DIR = '.harness';
+const TEAM_GITIGNORE_ENTRY = '\n# kode:harness personal state (Team mode)\n.harness/\n';
+const TEAM_GITATTRIBUTES_CONTENT =
+  '# kode:harness Team mode — merge strategy for shared state files\n' +
+  'docs/features.md merge=union\n' +
+  'docs/dependency-map.md merge=union\n';
 
 function hasFrameworkMarker(content) {
   return content.includes('kode:harness')
@@ -451,16 +538,47 @@ async function promptMode() {
 // ─── Team mode helpers ───────────────────────────────────────
 function appendGitignore(targetDir) {
   const gitignorePath = path.join(targetDir, '.gitignore');
-  const entry = '\n# kode:harness personal state (Team mode)\n.harness/\n';
+  const entry = TEAM_GITIGNORE_ENTRY;
   if (fs.existsSync(gitignorePath)) {
     const content = fs.readFileSync(gitignorePath, 'utf8');
     if (content.includes('.harness/')) {
       console.log('  ⏭  Skipped (exists): .gitignore entry');
+      if (currentInstallPatches) {
+        currentInstallPatches.push({
+          path: '.gitignore',
+          action: 'skipped',
+          type: 'team-helper',
+          block: entry,
+          hashBefore: hashFile(gitignorePath),
+          hashAfter: hashFile(gitignorePath),
+        });
+      }
       return;
     }
     fs.appendFileSync(gitignorePath, entry);
+    if (currentInstallPatches) {
+      currentInstallPatches.push({
+        path: '.gitignore',
+        action: 'appended',
+        type: 'team-helper',
+        block: entry,
+        hashBefore: hashContent(content),
+        hashAfter: hashFile(gitignorePath),
+      });
+    }
   } else {
     fs.writeFileSync(gitignorePath, entry.trimStart());
+    if (currentInstallRecords) {
+      currentInstallRecords.push({
+        path: '.gitignore',
+        type: 'team-helper',
+        action: 'created',
+        protected: true,
+        hashBefore: null,
+        hashAfter: hashFile(gitignorePath),
+        backupPath: null,
+      });
+    }
   }
   console.log('  ✓  .gitignore — added .harness/');
 }
@@ -500,11 +618,72 @@ function detectExistingInstall(targetDir) {
 }
 
 function writeGitattributes(targetDir) {
-  const content =
-    '# kode:harness Team mode — merge strategy for shared state files\n' +
-    'docs/features.md merge=union\n' +
-    'docs/dependency-map.md merge=union\n';
-  writeFile(targetDir, '.gitattributes', content, false);
+  writeFile(targetDir, '.gitattributes', TEAM_GITATTRIBUTES_CONTENT, false);
+}
+
+function readPackageVersion() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+  return pkg.version;
+}
+
+function readManifest(targetDir) {
+  const manifestFile = path.join(targetDir, MANIFEST_PATH);
+  if (!fs.existsSync(manifestFile)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeManifest(targetDir, manifest) {
+  const manifestFile = path.join(targetDir, MANIFEST_PATH);
+  fs.mkdirSync(path.dirname(manifestFile), { recursive: true });
+  fs.writeFileSync(manifestFile, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+}
+
+function saveInstallManifest(targetDir, runRecord) {
+  const manifest = readManifest(targetDir) || {
+    schemaVersion: 1,
+    tool: '@kodevibe/harness',
+    packageVersion: readPackageVersion(),
+    runs: [],
+  };
+  manifest.schemaVersion = 1;
+  manifest.tool = '@kodevibe/harness';
+  manifest.packageVersion = readPackageVersion();
+  manifest.updatedAt = new Date().toISOString();
+  manifest.runs = Array.isArray(manifest.runs) ? manifest.runs : [];
+  manifest.runs.push(runRecord);
+  writeManifest(targetDir, manifest);
+  console.log(`  ✓  ${MANIFEST_PATH}`);
+}
+
+function isSafeRelativePath(relPath) {
+  if (!relPath || path.isAbsolute(relPath)) return false;
+  const parts = relPath.split(/[\\/]+/);
+  return !parts.includes('..') && !parts.includes('');
+}
+
+function safeResolve(targetDir, relPath) {
+  const normalized = toPosixPath(relPath);
+  if (!isSafeRelativePath(normalized)) {
+    throw new Error(`Unsafe path in manifest: ${relPath}`);
+  }
+  const root = path.resolve(targetDir);
+  const resolved = path.resolve(root, normalized);
+  if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+    throw new Error(`Path escapes target directory: ${relPath}`);
+  }
+  return resolved;
+}
+
+function isDirectoryEmpty(dirPath) {
+  try {
+    return fs.readdirSync(dirPath).length === 0;
+  } catch {
+    return false;
+  }
 }
 
 // ─── Post-install guide ──────────────────────────────────────
@@ -686,6 +865,516 @@ function runValidate(targetDir) {
   return warnings === 0;
 }
 
+function getKnownIdeFiles(ide) {
+  const skillIds = SKILLS.map(skill => skill.id);
+  const agentIds = AGENTS.map(agent => agent.id);
+  const skillFiles = (base) => skillIds.map(id => `${base}/${id}/SKILL.md`);
+  const filesByIde = {
+    vscode: [
+      '.github/copilot-instructions.md',
+      ...skillFiles('.github/skills'),
+      ...agentIds.map(id => `.github/agents/${id}.agent.md`),
+    ],
+    claude: [
+      'CLAUDE.md',
+      '.claude/rules/core.md',
+      ...skillFiles('.claude/skills'),
+      ...agentIds.map(id => `.claude/agents/${id}.md`),
+    ],
+    cursor: [
+      '.cursor/rules/core.mdc',
+      'AGENTS.md',
+      ...skillFiles('.agents/skills'),
+      ...agentIds.map(id => `.cursor/rules/${id}.mdc`),
+    ],
+    codex: [
+      'AGENTS.md',
+      ...skillFiles('.agents/skills'),
+      ...agentIds.map(id => `.codex/agents/${id}.toml`),
+    ],
+    windsurf: [
+      '.windsurf/rules/core.md',
+      ...skillFiles('.windsurf/skills'),
+      ...agentIds.map(id => `.windsurf/skills/${id}/SKILL.md`),
+    ],
+    antigravity: [
+      'AGENTS.md',
+      '.agents/rules/core.md',
+      ...skillFiles('.agents/skills'),
+      ...agentIds.map(id => `.agents/rules/${id}.md`),
+    ],
+  };
+  return filesByIde[ide] || [];
+}
+
+function getLegacyRuns(targetDir, ideFilter) {
+  const ides = Object.keys(GENERATORS).filter(ide => (ideFilter ? ide === ideFilter : hasIdeLayout(targetDir, ide)));
+  return ides
+    .filter(ide => hasIdeLayout(targetDir, ide))
+    .map(ide => ({
+      runId: `legacy-${ide}`,
+      ide,
+      mode: 'unknown',
+      crew: false,
+      status: 'installed',
+      legacy: true,
+      files: getKnownIdeFiles(ide)
+        .filter(relPath => fs.existsSync(path.join(targetDir, relPath)))
+        .filter(relPath => fileHasFrameworkMarker(path.join(targetDir, relPath)))
+        .map(relPath => {
+          const fullPath = path.join(targetDir, relPath);
+          return {
+            path: relPath,
+            type: classifyManagedPath(relPath),
+            action: 'legacy',
+            protected: false,
+            hashBefore: null,
+            hashAfter: hashFile(fullPath),
+            backupPath: null,
+          };
+        }),
+      patches: [],
+    }));
+}
+
+function getInstalledRuns(targetDir, manifest) {
+  const manifestRuns = manifest && Array.isArray(manifest.runs)
+    ? manifest.runs.filter(run => run && run.status !== 'uninstalled')
+    : [];
+  const manifestIdes = new Set(manifestRuns.map(run => run.ide).filter(Boolean));
+  const legacyRuns = getLegacyRuns(targetDir, null).filter(run => !manifestIdes.has(run.ide));
+  return [...manifestRuns, ...legacyRuns];
+}
+
+function mergeSelectedFileRecords(records) {
+  let candidate = null;
+  let restoreBackupPath = null;
+  let previousManagedHash = null;
+  let fallbackSkipped = null;
+  let sawManagedRecord = false;
+
+  for (const record of records) {
+    if (record.action === 'skipped') {
+      fallbackSkipped = record;
+      continue;
+    }
+
+    if (!sawManagedRecord) {
+      if (record.action === 'overwritten' && record.backupPath) {
+        restoreBackupPath = record.backupPath;
+      }
+      sawManagedRecord = true;
+    } else if (record.action === 'overwritten' && record.backupPath && record.hashBefore && previousManagedHash && record.hashBefore !== previousManagedHash) {
+      restoreBackupPath = record.backupPath;
+    }
+
+    previousManagedHash = record.hashAfter || previousManagedHash;
+    candidate = { ...record };
+  }
+
+  if (!candidate) return fallbackSkipped || records[records.length - 1];
+  candidate.backupPath = restoreBackupPath;
+  if (restoreBackupPath) candidate.action = 'overwritten';
+  else if (candidate.action === 'overwritten') candidate.action = 'created';
+  return candidate;
+}
+
+function getSelectedFiles(selectedRuns) {
+  const filesByPath = new Map();
+  for (const run of selectedRuns) {
+    for (const file of (run.files || [])) {
+      const relPath = toPosixPath(file.path);
+      if (!filesByPath.has(relPath)) filesByPath.set(relPath, []);
+      filesByPath.get(relPath).push({ ...file, path: relPath });
+    }
+  }
+  return [...filesByPath.values()].map(mergeSelectedFileRecords);
+}
+
+function getHistoricalFileRecord(manifest, relPath) {
+  if (!manifest || !Array.isArray(manifest.runs)) return null;
+  const records = [];
+  for (const run of manifest.runs) {
+    for (const file of (run.files || [])) {
+      if (toPosixPath(file.path) === relPath) records.push({ ...file, path: relPath });
+    }
+  }
+  return records.length > 0 ? mergeSelectedFileRecords(records) : null;
+}
+
+function getOtherOwnerRecords(activeRuns, selectedRunIds, relPath, includeProtected = false) {
+  const owners = [];
+  for (const run of activeRuns) {
+    if (selectedRunIds.has(run.runId)) continue;
+    const files = Array.isArray(run.files) ? run.files : [];
+    for (const file of files) {
+      const skippedProtectedOwner = includeProtected && file.protected && file.action === 'skipped';
+      if (toPosixPath(file.path) === relPath && (file.action !== 'skipped' || skippedProtectedOwner) && (includeProtected || !file.protected)) {
+        owners.push({ ...file, path: relPath, runId: run.runId, ide: run.ide });
+      }
+    }
+  }
+  return owners;
+}
+
+function findLatestUserBackupPath(targetDir, manifest, relPath) {
+  if (!manifest || !Array.isArray(manifest.runs)) return null;
+  let backupPath = null;
+  for (const run of manifest.runs) {
+    for (const file of (run.files || [])) {
+      if (toPosixPath(file.path) !== relPath || !file.backupPath) continue;
+      let fullPath;
+      try {
+        fullPath = safeResolve(targetDir, file.backupPath);
+      } catch {
+        continue;
+      }
+      if (fs.existsSync(fullPath) && !fileHasFrameworkMarker(fullPath)) {
+        backupPath = file.backupPath;
+      }
+    }
+  }
+  return backupPath;
+}
+
+function getRestoreBackupPath(targetDir, manifest, file) {
+  if (!file.backupPath) return null;
+  const backupPath = safeResolve(targetDir, file.backupPath);
+  if (!fs.existsSync(backupPath)) return null;
+  if (!fileHasFrameworkMarker(backupPath)) return file.backupPath;
+  return findLatestUserBackupPath(targetDir, manifest, toPosixPath(file.path));
+}
+
+function shouldKeepFile(file, options) {
+  if (file.action === 'skipped') return true;
+  if (file.protected && !options.purgeState) return true;
+  return false;
+}
+
+function buildUninstallPlan(targetDir, options) {
+  const manifest = readManifest(targetDir);
+  const activeRuns = getInstalledRuns(targetDir, manifest);
+  const activeIdes = [...new Set(activeRuns.map(run => run.ide))].filter(Boolean);
+
+  if (activeIdes.length === 0) {
+    return { manifest, selectedRuns: [], actions: [], conflicts: [], keeps: [], warnings: ['No kode:harness install manifest or known IDE layout found.'] };
+  }
+
+  let selectedIde = options.ide;
+  if (selectedIde === 'all') selectedIde = null;
+  if (selectedIde && !GENERATORS[selectedIde]) {
+    throw new Error(`Unknown IDE: ${selectedIde}`);
+  }
+
+  if (!options.all && !selectedIde) {
+    if (activeIdes.length > 1) {
+      throw new Error(`Multiple IDE installs detected (${activeIdes.join(', ')}). Pass --ide <name> or --all.`);
+    }
+    selectedIde = activeIdes[0];
+  }
+
+  const selectedRuns = activeRuns.filter(run => options.all || run.ide === selectedIde);
+  const selectedRunIds = new Set(selectedRuns.map(run => run.runId));
+  const hasUnselectedRuns = activeRuns.some(run => !selectedRunIds.has(run.runId));
+  const actions = [];
+  const keeps = [];
+  const conflicts = [];
+  const warnings = [];
+
+  if (selectedRuns.length === 0) {
+    warnings.push(selectedIde ? `No active ${selectedIde} install found.` : 'No active install selected.');
+  }
+
+  for (let file of getSelectedFiles(selectedRuns)) {
+    const relPath = toPosixPath(file.path);
+
+    if (file.protected && options.purgeState && hasUnselectedRuns) {
+      keeps.push({ path: relPath, reason: 'shared-with-other-install' });
+      continue;
+    }
+
+    if (file.protected && options.purgeState && file.action === 'skipped' && !hasUnselectedRuns) {
+      const historicalFile = getHistoricalFileRecord(manifest, relPath);
+      if (historicalFile && historicalFile.action !== 'skipped') file = historicalFile;
+    }
+
+    if (shouldKeepFile(file, options)) {
+      keeps.push({ path: relPath, reason: file.protected ? 'state-preserved' : 'not-owned' });
+      continue;
+    }
+
+    const fullPath = safeResolve(targetDir, relPath);
+    if (!fs.existsSync(fullPath)) {
+      keeps.push({ path: relPath, reason: 'already-missing' });
+      continue;
+    }
+
+    const stat = fs.lstatSync(fullPath);
+    if (stat.isDirectory()) {
+      keeps.push({ path: relPath, reason: 'directory-entry-skipped' });
+      continue;
+    }
+    if (stat.isSymbolicLink()) {
+      conflicts.push({ path: relPath, reason: 'symlink-skipped' });
+      continue;
+    }
+
+    const currentHash = hashFile(fullPath);
+    const otherOwners = getOtherOwnerRecords(activeRuns, selectedRunIds, relPath, file.protected && options.purgeState);
+    if (otherOwners.length > 0) {
+      const latestOtherOwner = otherOwners[otherOwners.length - 1];
+      if (file.protected) {
+        keeps.push({ path: relPath, reason: `shared-with-${otherOwners.length}-other-install${otherOwners.length > 1 ? 's' : ''}` });
+        continue;
+      }
+      if (!latestOtherOwner.hashAfter || currentHash === latestOtherOwner.hashAfter) {
+        keeps.push({ path: relPath, reason: `shared-with-${otherOwners.length}-other-install${otherOwners.length > 1 ? 's' : ''}` });
+        continue;
+      }
+      if (file.backupPath) {
+        const backupPath = safeResolve(targetDir, file.backupPath);
+        if (fs.existsSync(backupPath) && hashFile(backupPath) === latestOtherOwner.hashAfter) {
+          actions.push({ type: 'restore', path: relPath, backupPath: file.backupPath });
+          continue;
+        }
+      }
+      conflicts.push({ path: relPath, reason: 'shared-content-mismatch' });
+      continue;
+    }
+
+    const unchanged = !file.hashAfter || currentHash === file.hashAfter;
+    const canUseLegacyMarker = file.action === 'legacy' && hasFrameworkMarker(fs.readFileSync(fullPath, 'utf8'));
+    if (!unchanged && !options.force && !canUseLegacyMarker) {
+      conflicts.push({ path: relPath, reason: 'modified-since-install' });
+      continue;
+    }
+
+    if (file.action === 'overwritten' && file.backupPath) {
+      const backupPath = getRestoreBackupPath(targetDir, manifest, file);
+      if (backupPath) {
+        actions.push({ type: 'restore', path: relPath, backupPath });
+        continue;
+      }
+      const originalBackupPath = safeResolve(targetDir, file.backupPath);
+      if (!fs.existsSync(originalBackupPath)) {
+        warnings.push(`Backup missing for ${relPath}; deleting generated file instead.`);
+      }
+    }
+
+    actions.push({ type: 'delete', path: relPath });
+  }
+
+  if (options.purgeState) {
+    if (hasUnselectedRuns) {
+      warnings.push('State and team helper patches are preserved because other active installs remain. Use --all to purge them together.');
+    }
+    for (const run of selectedRuns) {
+      for (const patch of (run.patches || [])) {
+        if (patch.action !== 'appended') continue;
+        if (hasUnselectedRuns) {
+          keeps.push({ path: patch.path, reason: 'shared-with-other-install' });
+          continue;
+        }
+        const fullPath = safeResolve(targetDir, patch.path);
+        if (fs.existsSync(fullPath)) {
+          actions.push({ type: 'remove-block', path: patch.path, block: patch.block });
+        }
+      }
+    }
+    if (!hasUnselectedRuns) {
+      const helperBlocks = [
+        { path: '.gitignore', block: TEAM_GITIGNORE_ENTRY },
+        { path: '.gitattributes', block: TEAM_GITATTRIBUTES_CONTENT },
+      ];
+      for (const helper of helperBlocks) {
+        if (actions.some(action => action.path === helper.path)) continue;
+        const fullPath = safeResolve(targetDir, helper.path);
+        if (!fs.existsSync(fullPath)) continue;
+        const content = fs.readFileSync(fullPath, 'utf8');
+        if (content.includes(helper.block) || content.includes(helper.block.trimStart())) {
+          actions.push({ type: 'remove-block', path: helper.path, block: helper.block });
+        }
+      }
+    }
+  }
+
+  if (options.purgeBackups) {
+    if (hasUnselectedRuns) {
+      warnings.push('Backup purge skipped because other active installs remain. Use --all to purge backups after all installs are removed.');
+    } else {
+      for (const relPath of ['.harness/init-backups', '.harness/uninstall-backups']) {
+        actions.push({ type: 'delete-tree', path: relPath });
+      }
+    }
+  }
+
+  return { manifest, selectedRuns, actions, conflicts, keeps, warnings };
+}
+
+function backupBeforeUninstall(targetDir, backupRoot, relPath) {
+  const source = safeResolve(targetDir, relPath);
+  if (!fs.existsSync(source)) return null;
+  const stat = fs.lstatSync(source);
+  if (!stat.isFile()) return null;
+  const backupPath = path.join(backupRoot, relPath);
+  fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+  fs.copyFileSync(source, backupPath);
+  return toPosixPath(path.relative(targetDir, backupPath));
+}
+
+function removeEmptyParents(targetDir, relPath) {
+  let current = path.dirname(safeResolve(targetDir, relPath));
+  const root = path.resolve(targetDir);
+  while (current !== root && current.startsWith(root + path.sep)) {
+    if (!fs.existsSync(current) || !isDirectoryEmpty(current)) break;
+    fs.rmdirSync(current);
+    current = path.dirname(current);
+  }
+}
+
+function applyUninstallPlan(targetDir, plan, options) {
+  const uninstallRunId = getBackupTimestamp();
+  const backupRoot = path.join(targetDir, '.harness', 'uninstall-backups', uninstallRunId);
+  const applied = [];
+
+  for (const action of plan.actions) {
+    if (action.type === 'delete') {
+      const fullPath = safeResolve(targetDir, action.path);
+      if (!fs.existsSync(fullPath)) continue;
+      backupBeforeUninstall(targetDir, backupRoot, action.path);
+      fs.unlinkSync(fullPath);
+      removeEmptyParents(targetDir, action.path);
+      applied.push(action);
+    } else if (action.type === 'restore') {
+      const fullPath = safeResolve(targetDir, action.path);
+      const backupPath = safeResolve(targetDir, action.backupPath);
+      backupBeforeUninstall(targetDir, backupRoot, action.path);
+      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+      fs.copyFileSync(backupPath, fullPath);
+      applied.push(action);
+    } else if (action.type === 'remove-block') {
+      const fullPath = safeResolve(targetDir, action.path);
+      if (!fs.existsSync(fullPath)) continue;
+      const content = fs.readFileSync(fullPath, 'utf8');
+      let updated = content;
+      if (updated.includes(action.block)) updated = updated.replace(action.block, '');
+      else if (updated.includes(action.block.trimStart())) updated = updated.replace(action.block.trimStart(), '');
+      else continue;
+      backupBeforeUninstall(targetDir, backupRoot, action.path);
+      if (updated.trim() === '') {
+        fs.unlinkSync(fullPath);
+        removeEmptyParents(targetDir, action.path);
+      } else {
+        fs.writeFileSync(fullPath, updated, 'utf8');
+      }
+      applied.push(action);
+    } else if (action.type === 'delete-tree') {
+      const fullPath = safeResolve(targetDir, action.path);
+      if (!fs.existsSync(fullPath)) continue;
+      fs.rmSync(fullPath, { recursive: true, force: true });
+      applied.push(action);
+    }
+  }
+
+  if (plan.manifest && Array.isArray(plan.manifest.runs)) {
+    const selectedRunIds = new Set(plan.selectedRuns.map(run => run.runId));
+    const purgesUninstallBackups = plan.actions.some(action => action.type === 'delete-tree' && action.path === '.harness/uninstall-backups');
+    for (const run of plan.manifest.runs) {
+      if (selectedRunIds.has(run.runId)) {
+        run.status = 'uninstalled';
+        run.uninstalledAt = new Date().toISOString();
+        run.uninstallBackupPath = purgesUninstallBackups ? null : toPosixPath(path.relative(targetDir, backupRoot));
+      }
+    }
+    plan.manifest.updatedAt = new Date().toISOString();
+    const hasActiveRuns = plan.manifest.runs.some(run => run.status !== 'uninstalled');
+    if (options.purgeState && options.purgeBackups && !hasActiveRuns) {
+      const manifestPath = safeResolve(targetDir, MANIFEST_PATH);
+      if (fs.existsSync(manifestPath)) fs.unlinkSync(manifestPath);
+      removeEmptyParents(targetDir, MANIFEST_PATH);
+    } else {
+      writeManifest(targetDir, plan.manifest);
+    }
+  }
+
+  if (fs.existsSync(backupRoot) && isDirectoryEmpty(backupRoot)) {
+    fs.rmdirSync(backupRoot);
+  }
+
+  return applied;
+}
+
+function printUninstallPlan(plan, options) {
+  const mode = options.dryRun ? 'dry-run' : 'apply';
+  console.log(`\n  kode:harness uninstall plan (${mode})\n`);
+  for (const warning of plan.warnings) console.log(`  WARN   ${warning}`);
+  for (const keep of plan.keeps) console.log(`  KEEP   ${keep.path} — ${keep.reason}`);
+  for (const conflict of plan.conflicts) console.log(`  SKIP   ${conflict.path} — ${conflict.reason}`);
+  for (const action of plan.actions) {
+    const verb = action.type === 'restore' ? 'RESTORE' : action.type === 'remove-block' ? 'PATCH' : 'REMOVE';
+    console.log(`  ${verb.padEnd(7)}${action.path}`);
+  }
+  console.log(`\n  Summary: ${plan.actions.length} action(s), ${plan.keeps.length} kept, ${plan.conflicts.length} conflict(s)\n`);
+}
+
+async function runUninstall(args) {
+  const options = {
+    ide: args.ide,
+    all: args.all,
+    dryRun: args.dryRun,
+    yes: args.yes,
+    purgeState: args.purgeState,
+    purgeBackups: args.purgeBackups,
+    force: args.force,
+  };
+
+  let plan;
+  try {
+    plan = buildUninstallPlan(args.dir, options);
+  } catch (error) {
+    console.error(`  ${error.message}`);
+    process.exit(1);
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(plan, null, 2));
+  } else {
+    printUninstallPlan(plan, options);
+  }
+
+  if (options.dryRun || plan.actions.length === 0) return true;
+
+  if (!options.yes) {
+    if (!process.stdin.isTTY) {
+      console.error('  Refusing to uninstall non-interactively without --yes. Re-run with --dry-run to preview or --yes to apply.');
+      process.exit(1);
+    }
+    const answer = await askQuestion('  Apply this uninstall plan? (y/N): ');
+    if (!['y', 'yes'].includes(answer.toLowerCase())) {
+      console.log('  Uninstall cancelled.');
+      process.exit(2);
+    }
+  }
+
+  if (options.purgeState && !options.yes && process.stdin.isTTY) {
+    const answer = await askQuestion('  Type "delete state" to confirm state deletion: ');
+    if (answer !== 'delete state') {
+      console.log('  State purge cancelled.');
+      process.exit(2);
+    }
+  }
+
+  try {
+    const applied = applyUninstallPlan(args.dir, plan, options);
+    if (!args.json) console.log(`  Applied ${applied.length} action(s).`);
+    if (plan.conflicts.length > 0) process.exit(3);
+    return true;
+  } catch (error) {
+    console.error(`  Uninstall failed: ${error.message}`);
+    process.exit(3);
+  }
+}
+
 // ─── CLI entry ───────────────────────────────────────────────
 function showHelp() {
   console.log(`
@@ -695,17 +1384,26 @@ function showHelp() {
     npx @kodevibe/harness init [options]
     npx @kodevibe/harness doctor [--dir <path>]
     npx @kodevibe/harness validate [--dir <path>]
+    npx @kodevibe/harness uninstall [options]
 
   Commands:
     init             Install kode:harness files for your IDE
     doctor           Check if kode:harness files are installed and healthy
     validate         Verify state files have content (not just placeholders)
+    uninstall        Safely remove kode:harness IDE files (state preserved by default)
 
   Options:
     --ide <name>     IDE target: vscode, claude, cursor, codex, windsurf, antigravity
+    --all            Uninstall all detected IDE layouts
     --mode <mode>    Project mode: solo (default) or team
     --dir <path>     Target directory (default: current directory)
     --overwrite      Overwrite existing files (including state files)
+    --dry-run        Print uninstall plan without changing files
+    --yes            Confirm uninstall non-interactively
+    --purge-state    Also remove generated state files when unchanged
+    --purge-backups  Also remove kode:harness backup directories
+    --force          Apply despite changed managed files
+    --json           Print machine-readable uninstall plan
     --batch          Non-interactive mode (requires --ide; defaults to solo mode)
     --version        Show version number
     --help           Show this help
@@ -717,16 +1415,36 @@ function showHelp() {
     npx @kodevibe/harness init --ide claude --dir ./my-project
     npx @kodevibe/harness doctor
     npx @kodevibe/harness validate
+    npx @kodevibe/harness uninstall --ide claude --dry-run
+    npx @kodevibe/harness uninstall --ide claude --yes
 `);
 }
 
 function parseArgs(argv) {
-  const args = { command: null, ide: null, mode: null, dir: process.cwd(), overwrite: false, help: false, batch: false, version: false, crew: false };
+  const args = {
+    command: null,
+    ide: null,
+    mode: null,
+    dir: process.cwd(),
+    overwrite: false,
+    help: false,
+    batch: false,
+    version: false,
+    crew: false,
+    all: false,
+    dryRun: false,
+    yes: false,
+    purgeState: false,
+    purgeBackups: false,
+    force: false,
+    json: false,
+  };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === 'init') args.command = 'init';
     else if (arg === 'doctor') args.command = 'doctor';
     else if (arg === 'validate') args.command = 'validate';
+    else if (arg === 'uninstall') args.command = 'uninstall';
     else if (arg === '--ide' && argv[i + 1]) { args.ide = argv[++i]; }
     else if (arg === '--mode' && argv[i + 1]) { args.mode = argv[++i]; }
     else if (arg === '--team') { args.mode = 'team'; }
@@ -734,6 +1452,13 @@ function parseArgs(argv) {
     else if (arg === '--dir' && argv[i + 1]) { args.dir = path.resolve(argv[++i]); }
     else if (arg === '--overwrite') args.overwrite = true;
     else if (arg === '--batch') args.batch = true;
+    else if (arg === '--all') args.all = true;
+    else if (arg === '--dry-run') args.dryRun = true;
+    else if (arg === '--yes' || arg === '-y') args.yes = true;
+    else if (arg === '--purge-state' || arg === '--include-state') args.purgeState = true;
+    else if (arg === '--purge-backups') args.purgeBackups = true;
+    else if (arg === '--force') args.force = true;
+    else if (arg === '--json') args.json = true;
     else if (arg === '--help' || arg === '-h') args.help = true;
     else if (arg === '--version') args.version = true;
   }
@@ -764,6 +1489,11 @@ async function run(argv) {
     process.exit(ok ? 0 : 1);
   }
 
+  if (args.command === 'uninstall') {
+    await runUninstall(args);
+    return;
+  }
+
   if (args.command === 'init') {
     console.log('\n  kode:harness — Harness Engineering\n');
 
@@ -833,6 +1563,8 @@ async function run(argv) {
     const modeDesc = crew ? `${mode} + crew` : mode;
     console.log(`\n  Installing for ${gen.name} (${modeDesc} mode)... (detected language: ${lang})\n`);
     resetBackupTimestamp();
+    const runId = getBackupTimestamp();
+    startInstallRecording();
     gen.fn(args.dir, overwrite, mode, crew);
 
     // Team mode extras
@@ -841,8 +1573,22 @@ async function run(argv) {
       writeGitattributes(args.dir);
     }
 
+    const { records, patches } = stopInstallRecording();
+    saveInstallManifest(args.dir, {
+      runId,
+      command: 'init',
+      ide,
+      mode,
+      crew,
+      status: 'installed',
+      packageVersion: readPackageVersion(),
+      createdAt: new Date().toISOString(),
+      files: records,
+      patches,
+    });
+
     showPostInstallGuide(gen.name, mode);
   }
 }
 
-module.exports = { run, detectLanguage, runDoctor, runValidate };
+module.exports = { run, detectLanguage, runDoctor, runValidate, buildUninstallPlan };