depa-codument 0.4.1

package/src/cli/commands/status.ts

@@ -0,0 +1,140 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { getTracks, getSpecs, codumentExists, formatStatus, CODUMENT_DIR, walkTrackTasks } from '../utils';
+
+export async function statusCommand(args: string[]) {
+  if (!codumentExists()) {
+    console.error('Codument is not initialized. Run codument init first.');
+    process.exit(1);
+  }
+
+  const tracks = getTracks();
+  const specs = getSpecs();
+
+  // Calculate statistics
+  const totalTracks = tracks.length;
+  const completedTracks = tracks.filter(t => t.metadata.status === 'completed').length;
+  const inProgressTracks = tracks.filter(t => t.metadata.status === 'in_progress').length;
+  const newTracks = tracks.filter(t => t.metadata.status === 'new').length;
+
+  let totalTasks = 0;
+  let completedTasks = 0;
+  let inProgressTasks = 0;
+  let todoTasks = 0;
+  let blockedTasks = 0;
+
+  for (const track of tracks) {
+    if (track.taskSummary) {
+      totalTasks += track.taskSummary.total_tasks;
+      completedTasks += track.taskSummary.completed;
+      inProgressTasks += track.taskSummary.in_progress;
+      todoTasks += track.taskSummary.todo;
+      blockedTasks += track.taskSummary.blocked;
+    }
+  }
+
+  const overallProgress = totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0;
+
+  // Find current track and task
+  const currentTrack = tracks.find(t => t.metadata.status === 'in_progress');
+  let currentPhase = '';
+  let currentTask = '';
+  let nextTask = '';
+
+  if (currentTrack) {
+    const file = path.join(CODUMENT_DIR, 'tracks', currentTrack.id, 'track.xml');
+    if (fs.existsSync(file)) {
+      for (const task of walkTrackTasks(file)) {
+        if (!currentTask && task.status === 'ACTIVE') {
+          currentPhase = task.phaseName;
+          currentTask = task.name;
+        }
+        if (!nextTask && task.status === 'NOT_STARTED') {
+          nextTask = task.name;
+        }
+        if (currentTask && nextTask) {
+          break;
+        }
+      }
+    }
+  }
+
+  // Determine project status
+  let projectStatus = 'On Track';
+  if (blockedTasks > 0) {
+    projectStatus = 'Blocked';
+  } else if (totalTracks === 0) {
+    projectStatus = 'No Tracks';
+  } else if (completedTracks === totalTracks) {
+    projectStatus = 'Complete';
+  }
+
+  // Print status
+  const now = new Date().toISOString().replace('T', ' ').split('.')[0];
+
+  console.log('\n' + '═'.repeat(60));
+  console.log('                    Codument Project Status');
+  console.log('═'.repeat(60));
+
+  console.log(`\n📅 Time: ${now}`);
+  console.log(`📊 Status: ${projectStatus}`);
+
+  console.log('\n' + '─'.repeat(60));
+  console.log('                       Tracks Overview');
+  console.log('─'.repeat(60));
+
+  if (tracks.length === 0) {
+    console.log('\n  No tracks found. Use "codument track" to create one.\n');
+  } else {
+    console.log('\n  Status  Track                              Progress');
+    console.log('  ' + '-'.repeat(56));
+
+    for (const track of tracks) {
+      const status = formatStatus(track.metadata.status);
+      const id = track.id.length > 32 ? track.id.slice(0, 29) + '...' : track.id.padEnd(32);
+
+      let progress = '-';
+      if (track.taskSummary) {
+        const { completed, total_tasks } = track.taskSummary;
+        const pct = total_tasks > 0 ? Math.round((completed / total_tasks) * 100) : 0;
+        progress = `${completed}/${total_tasks} (${pct}%)`;
+      }
+
+      console.log(`  ${status}   ${id}  ${progress}`);
+    }
+  }
+
+  console.log('\n' + '─'.repeat(60));
+  console.log('                       Current Progress');
+  console.log('─'.repeat(60));
+
+  if (currentTrack) {
+    console.log(`\n🎯 Current Track: ${currentTrack.id}`);
+    if (currentPhase) console.log(`   Current Phase: ${currentPhase}`);
+    if (currentTask) console.log(`   Current Task: ${currentTask}`);
+    if (nextTask) console.log(`\n📋 Next: ${nextTask}`);
+  } else {
+    console.log('\n  No track in progress.');
+  }
+
+  if (blockedTasks > 0) {
+    console.log(`\n⚠️  Blocked: ${blockedTasks} task(s)`);
+  }
+
+  console.log('\n' + '─'.repeat(60));
+  console.log('                        Statistics');
+  console.log('─'.repeat(60));
+
+  console.log(`\nTracks:  ${totalTracks} total | ${inProgressTracks} in progress | ${newTracks} new | ${completedTracks} completed`);
+  console.log(`Tasks:   ${totalTasks} total | ${completedTasks} done | ${inProgressTasks} in progress | ${todoTasks} todo`);
+
+  // Progress bar
+  const barWidth = 20;
+  const filled = Math.round((overallProgress / 100) * barWidth);
+  const empty = barWidth - filled;
+  const bar = '█'.repeat(filled) + '░'.repeat(empty);
+
+  console.log(`Progress: ${bar} ${overallProgress}%`);
+
+  console.log('\n' + '═'.repeat(60) + '\n');
+}

package/src/cli/commands/upgrade-track.ts

@@ -0,0 +1,385 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import {
+  ARCHIVE_DIR,
+  CODUMENT_DIR,
+  TRACKS_DIR,
+  codumentExists,
+  parseOptions,
+} from '../utils';
+
+type ExecutionMode = 'wave' | 'sequential';
+
+function safeTimestamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function ensureDir(dirPath: string): void {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function ensureParentDir(filePath: string): void {
+  ensureDir(path.dirname(filePath));
+}
+
+function copyRecursive(src: string, dest: string): void {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    ensureDir(dest);
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+      const s = path.join(src, entry.name);
+      const d = path.join(dest, entry.name);
+      if (entry.isDirectory()) {
+        copyRecursive(s, d);
+      } else if (entry.isFile()) {
+        ensureParentDir(d);
+        fs.copyFileSync(s, d);
+      }
+    }
+    return;
+  }
+  ensureParentDir(dest);
+  fs.copyFileSync(src, dest);
+}
+
+function backupPath(backupRoot: string, relativePath: string): string {
+  const normalized = relativePath.replace(/^\/+/, '');
+  return path.join(backupRoot, normalized);
+}
+
+function backupIfExists(src: string, backupRoot: string): void {
+  if (!fs.existsSync(src)) {
+    return;
+  }
+  copyRecursive(src, backupPath(backupRoot, src));
+}
+
+function findTrackDir(identifier: string): { kind: 'track' | 'archive'; dir: string; id: string } | null {
+  const trackDir = path.join(TRACKS_DIR, identifier);
+  if (fs.existsSync(trackDir) && fs.statSync(trackDir).isDirectory()) {
+    return { kind: 'track', dir: trackDir, id: identifier };
+  }
+
+  // Identifier may be an archive id (YYYY-MM-DD-<track-id>) or a track id inside archive.
+  if (!fs.existsSync(ARCHIVE_DIR)) {
+    return null;
+  }
+
+  const archiveCandidates: Array<{ id: string; dir: string }> = [];
+  const visitArchiveDir = (dir: string, depth: number): void => {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      const entryDir = path.join(dir, entry.name);
+      const name = entry.name;
+      if (fs.existsSync(path.join(entryDir, 'plan.xml')) && isArchiveIdMatch(identifier, name)) {
+        archiveCandidates.push({ id: name, dir: entryDir });
+        continue;
+      }
+
+      // New archive layout nests archive IDs one level under YYYY-MM buckets.
+      if (depth < 1 && /^\d{4}-\d{2}$/.test(name)) {
+        visitArchiveDir(entryDir, depth + 1);
+      }
+    }
+  };
+
+  visitArchiveDir(ARCHIVE_DIR, 0);
+
+  if (archiveCandidates.length === 1) {
+    const archive = archiveCandidates[0];
+    return { kind: 'archive', dir: archive.dir, id: archive.id };
+  }
+
+  return null;
+}
+
+function isArchiveIdMatch(identifier: string, name: string): boolean {
+  return name === identifier || name.endsWith(`-${identifier}`);
+}
+
+function escapeXmlText(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function ensureExecutionMode(content: string, mode: ExecutionMode): string {
+  if (content.match(/<execution_mode>[^<]*<\/execution_mode>/)) {
+    return content.replace(/<execution_mode>[^<]*<\/execution_mode>/, `<execution_mode>${mode}</execution_mode>`);
+  }
+
+  // Insert under <metadata> (preferred: after <commit_mode> if present)
+  const commitModeIdx = content.indexOf('</commit_mode>');
+  if (commitModeIdx !== -1) {
+    const insertAt = commitModeIdx + '</commit_mode>'.length;
+    return content.slice(0, insertAt) + `\n    <execution_mode>${mode}</execution_mode>` + content.slice(insertAt);
+  }
+
+  const metadataEndIdx = content.indexOf('</metadata>');
+  if (metadataEndIdx !== -1) {
+    return content.slice(0, metadataEndIdx) + `    <execution_mode>${mode}</execution_mode>\n` + content.slice(metadataEndIdx);
+  }
+
+  return content;
+}
+
+function stripDependenciesTag(taskInner: string): { inner: string; dependencies: string[] } {
+  const deps: string[] = [];
+  const depRegex = /<dependencies>([\s\S]*?)<\/dependencies>/g;
+  let match;
+  while ((match = depRegex.exec(taskInner)) !== null) {
+    const raw = match[1].trim();
+    if (raw) {
+      deps.push(...raw.split(',').map((s) => s.trim()).filter(Boolean));
+    }
+  }
+  const without = taskInner.replace(depRegex, '');
+  return { inner: without, dependencies: deps };
+}
+
+function wrapTaskDescriptionIfNeeded(taskInner: string): string {
+  if (taskInner.includes('<description>')) {
+    // If a <description> already exists, strip any leading mixed text before the first tag.
+    const firstTagIdx = taskInner.indexOf('<');
+    if (firstTagIdx <= 0) {
+      return taskInner;
+    }
+    const prefix = taskInner.slice(0, firstTagIdx);
+    if (prefix.trim().length === 0) {
+      return taskInner.slice(firstTagIdx);
+    }
+    return taskInner.slice(firstTagIdx);
+  }
+
+  const firstTagIdx = taskInner.indexOf('<');
+  const prefix = firstTagIdx === -1 ? taskInner : taskInner.slice(0, firstTagIdx);
+  const rest = firstTagIdx === -1 ? '' : taskInner.slice(firstTagIdx);
+  const descText = prefix.trim();
+  if (!descText) {
+    return taskInner;
+  }
+
+  // Use indentation of the next tag if available
+  const indentMatch = rest.match(/\n(\s*)</);
+  const indent = indentMatch ? indentMatch[1] : '          ';
+
+  const descLine = `\n${indent}<description>${escapeXmlText(descText)}</description>\n`;
+  return descLine + rest;
+}
+
+function upgradePhaseToWaves(phaseId: string, phaseInner: string): { phaseInner: string } {
+  if (phaseInner.includes('<waves>')) {
+    return { phaseInner };
+  }
+
+  // Parse tasks within this phase
+  const taskRegex = /<task\s+([^>]+)>([\s\S]*?)<\/task>/g;
+  type TaskInfo = {
+    attrs: string;
+    inner: string;
+    taskId: string;
+    dependencies: string[];
+  };
+  const tasks: TaskInfo[] = [];
+
+  let match;
+  while ((match = taskRegex.exec(phaseInner)) !== null) {
+    const attrs = match[1];
+    const inner = match[2];
+    const taskId = attrs.match(/id="([^"]+)"/)?.[1] ?? '';
+    const { inner: withoutDeps, dependencies } = stripDependenciesTag(inner);
+    tasks.push({ attrs, inner: withoutDeps, taskId, dependencies });
+  }
+
+  // If no tasks, nothing to do
+  if (tasks.length === 0) {
+    return { phaseInner };
+  }
+
+  // One wave per task, deterministic order
+  const taskToWave = new Map<string, string>();
+  tasks.forEach((t, idx) => {
+    const seq = String(idx + 1).padStart(2, '0');
+    taskToWave.set(t.taskId, `WAVE-${phaseId}-${seq}`);
+  });
+
+  const waveLines: string[] = [];
+  for (const t of tasks) {
+    const waveId = taskToWave.get(t.taskId) || `WAVE-${phaseId}-01`;
+    const depWaves = t.dependencies
+      .map((depTaskId) => taskToWave.get(depTaskId))
+      .filter((w): w is string => Boolean(w));
+    const dependsAttr = depWaves.length > 0 ? ` depends_on="${depWaves.join(',')}"` : ' depends_on=""';
+    waveLines.push(`        <wave id="${waveId}"${dependsAttr} />`);
+  }
+
+  const wavesBlock = `\n      <waves>\n${waveLines.join('\n')}\n      </waves>\n`;
+
+  // Insert waves after </context_files> if present, else after </goal>
+  const ctxEndIdx = phaseInner.indexOf('</context_files>');
+  if (ctxEndIdx !== -1) {
+    const insertAt = ctxEndIdx + '</context_files>'.length;
+    phaseInner = phaseInner.slice(0, insertAt) + wavesBlock + phaseInner.slice(insertAt);
+  } else {
+    const goalEndIdx = phaseInner.indexOf('</goal>');
+    if (goalEndIdx !== -1) {
+      const insertAt = goalEndIdx + '</goal>'.length;
+      phaseInner = phaseInner.slice(0, insertAt) + wavesBlock + phaseInner.slice(insertAt);
+    } else {
+      phaseInner = wavesBlock + phaseInner;
+    }
+  }
+
+  // Rewrite tasks: add wave attr + wrap description + ensure dependencies removed
+  phaseInner = phaseInner.replace(taskRegex, (_full, attrs: string, inner: string) => {
+    const taskId = attrs.match(/id="([^"]+)"/)?.[1] ?? '';
+    const waveId = taskToWave.get(taskId);
+    let newAttrs = attrs;
+    if (waveId && !newAttrs.includes('wave=')) {
+      newAttrs = `${newAttrs} wave="${waveId}"`;
+    }
+
+    const { inner: withoutDeps } = stripDependenciesTag(inner);
+    const wrapped = wrapTaskDescriptionIfNeeded(withoutDeps);
+    return `<task ${newAttrs}>${wrapped}</task>`;
+  });
+
+  return { phaseInner };
+}
+
+function upgradePlanXml(original: string, mode: ExecutionMode): string {
+  let content = original;
+
+  // Convert references -> context_files (best-effort)
+  content = content
+    .replace(/<references>/g, '<context_files>')
+    .replace(/<\/references>/g, '</context_files>')
+    .replace(/<reference>/g, '<file>')
+    .replace(/<\/reference>/g, '</file>');
+
+  // Ensure execution_mode
+  content = ensureExecutionMode(content, mode);
+
+  // Phase-level upgrade
+  const phaseRegex = /<phase\s+id="([^"]+)"\s+name="([^"]+)"(?:\s+milestone="([^"]+)")?[^>]*>([\s\S]*?)<\/phase>/g;
+  content = content.replace(phaseRegex, (full, phaseId: string, name: string, milestone: string | undefined, inner: string) => {
+    void name;
+    void milestone;
+    if (mode !== 'wave') {
+      // Still remove <dependencies> and wrap <description> in sequential mode
+      const taskRegex = /<task\s+([^>]+)>([\s\S]*?)<\/task>/g;
+      const upgradedInner = inner.replace(taskRegex, (_tFull, attrs: string, taskInner: string) => {
+        const { inner: withoutDeps } = stripDependenciesTag(taskInner);
+        const wrapped = wrapTaskDescriptionIfNeeded(withoutDeps);
+        return `<task ${attrs}>${wrapped}</task>`;
+      });
+      return full.replace(inner, upgradedInner);
+    }
+
+    const { phaseInner } = upgradePhaseToWaves(phaseId, inner);
+    return full.replace(inner, phaseInner);
+  });
+
+  // As a final pass, strip any remaining <dependencies>
+  content = content.replace(/\s*<dependencies>[\s\S]*?<\/dependencies>\s*/g, '\n');
+
+  return content;
+}
+
+function ensureWaveSupportFiles(trackDir: string, waveMode: boolean): void {
+  if (!waveMode) {
+    return;
+  }
+  const contextPath = path.join(trackDir, 'context.md');
+  const statePath = path.join(trackDir, 'state.md');
+  if (!fs.existsSync(contextPath)) {
+    fs.writeFileSync(contextPath, '# Context\n', 'utf-8');
+  }
+  if (!fs.existsSync(statePath)) {
+    fs.writeFileSync(statePath, '# State\n', 'utf-8');
+  }
+  ensureDir(path.join(trackDir, 'phases'));
+  ensureDir(path.join(trackDir, 'waves'));
+}
+
+export async function upgradeTrackCommand(args: string[]): Promise<void> {
+  if (!codumentExists()) {
+    console.error('Codument is not initialized. Run codument init first.');
+    process.exit(1);
+  }
+
+  const { positional, options } = parseOptions(args);
+  const identifier = positional[0];
+  if (!identifier) {
+    console.error('Please specify a track-id or archive-id.');
+    console.log('Usage: codument upgrade-track <track-id|archive-id> [--mode wave|sequential] [--backup-dir <path>] [--no-backup]');
+    process.exit(1);
+  }
+
+  const mode = (typeof options['mode'] === 'string' ? String(options['mode']) : 'wave') as ExecutionMode;
+  if (mode !== 'wave' && mode !== 'sequential') {
+    console.error(`Invalid --mode: ${mode}`);
+    process.exit(1);
+  }
+
+  const noBackup = options['no-backup'] === true;
+  const backupRoot = typeof options['backup-dir'] === 'string'
+    ? path.resolve(String(options['backup-dir']))
+    : path.join('.tmp', 'codument', `upgrade-track-${safeTimestamp()}`);
+
+  const found = findTrackDir(identifier);
+  if (!found) {
+    console.error(`Track not found: ${identifier}`);
+    console.log('Searched:');
+    console.log(`- ${path.join(TRACKS_DIR, identifier)}`);
+    console.log(`- ${path.join(ARCHIVE_DIR, `*-${identifier}`)}`);
+    process.exit(1);
+  }
+
+  const trackDir = found.dir;
+  const planPath = path.join(trackDir, 'plan.xml');
+  if (!fs.existsSync(planPath)) {
+    console.error(`plan.xml not found in: ${trackDir}`);
+    process.exit(1);
+  }
+
+  console.log('🔧 Codument Upgrade Track');
+  console.log(`Workspace: ${process.cwd()}`);
+  console.log(`Target:    ${trackDir}`);
+  console.log(`Mode:      ${mode}`);
+  if (!noBackup) {
+    console.log(`Backup:    ${backupRoot}`);
+  }
+  console.log('');
+
+  if (!noBackup) {
+    // Backup the entire track directory for rollback
+    backupIfExists(trackDir, backupRoot);
+  }
+
+  const original = fs.readFileSync(planPath, 'utf-8');
+  const upgraded = upgradePlanXml(original, mode);
+  fs.writeFileSync(planPath, upgraded, 'utf-8');
+  console.log('✓ Updated plan.xml');
+
+  ensureWaveSupportFiles(trackDir, mode === 'wave');
+  if (mode === 'wave') {
+    console.log('✓ Ensured wave support files (context.md, state.md, phases/, waves/)');
+  }
+
+  console.log('');
+  if (!noBackup) {
+    console.log(`Done. Backup saved at: ${backupRoot}`);
+  } else {
+    console.log('Done. (no backup)');
+  }
+}

package/src/cli/commands/upgrade-workspace.ts

@@ -0,0 +1,138 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { parseOptions, codumentExists } from '../utils';
+import {
+  installSkillTemplates,
+  installTemplates,
+  ensureCodumentGitignoreRules,
+  injectAgentsBlock,
+  parseAgents,
+  readCliToolsConfig,
+  resolveSkillsTargets,
+  writeCliToolsConfig,
+  type CLITool,
+} from '../utils/install';
+
+/**
+ * `codument upgrade-workspace` — refresh the embedded templates in place.
+ *
+ * Pure text copy: overwrites the managed codument/std/** subtree and the agent
+ * skill shells with the latest embedded templates; leaves user-owned files
+ * (attractors content, config values, tracks, behaviors, backlog/memory) intact.
+ * Creates a timestamped backup under .tmp/codument/ before touching workspace
+ * files. No per-agent generators, no interactive prompts.
+ *
+ * Options: same --agent / --skills-dir as `init`.
+ */
+export async function upgradeWorkspaceCommand(args: string[]): Promise<void> {
+  if (!codumentExists()) {
+    console.error('Codument is not initialized. Run codument init first.');
+    process.exit(1);
+  }
+
+  const { options } = parseOptions(args);
+  const hasExplicitAgent = options['agent'] !== undefined;
+  const hasExplicitSkillsDir = options['skills-dir'] !== undefined;
+  const backupRoot = createWorkspaceBackup();
+  const stateTools = readCliToolsConfig();
+  const fallbackTools: CLITool[] = stateTools.length > 0 ? stateTools : ['claude'];
+  const selectedTools = hasExplicitAgent
+    ? parseAgents(typeof options['agent'] === 'string' ? String(options['agent']) : undefined, fallbackTools)
+    : fallbackTools;
+  const shouldWriteCliToolsConfig = stateTools.length > 0 || hasExplicitAgent;
+  if (shouldWriteCliToolsConfig) {
+    writeCliToolsConfig(selectedTools);
+  }
+  const removedLegacyPaths = removeLegacyWorkspacePaths(backupRoot);
+  const targets = resolveSkillsTargets(options, selectedTools);
+  const [firstTarget, ...additionalTargets] = targets;
+
+  const result = installTemplates({ skillsDir: firstTarget.skillsDir, overwriteStd: true });
+  const skillResults = [{ ...firstTarget, skillsWritten: result.skillsWritten, skillsRemoved: result.skillsRemoved }];
+  for (const target of additionalTargets) {
+    skillResults.push({ ...target, ...installSkillTemplates(target.skillsDir) });
+  }
+  injectAgentsBlock();
+  const gitignoreRulesAdded = ensureCodumentGitignoreRules();
+
+  console.log('Codument workspace upgraded.');
+  console.log(`  backup    : ${backupRoot}`);
+  console.log(`  codument/ : ${result.workspaceWritten} written (std refreshed), ${result.workspaceSkipped} kept`);
+  for (const skillResult of skillResults) {
+    const removed = skillResult.skillsRemoved ? `, ${skillResult.skillsRemoved} deprecated removed` : '';
+    console.log(`  skills    : ${skillResult.skillsWritten} → ${skillResult.skillsDir} (agent: ${skillResult.agent}${removed})`);
+  }
+  if (shouldWriteCliToolsConfig) {
+    console.log('  config/cli-tools.json: tools updated');
+  }
+  if (removedLegacyPaths > 0) {
+    console.log(`  cleanup   : ${removedLegacyPaths} legacy path(s) removed`);
+  }
+  if (gitignoreRulesAdded > 0) {
+    console.log(`  .gitignore: ${gitignoreRulesAdded} codument rule(s) added`);
+  }
+  console.log('  AGENTS.md : managed block refreshed');
+}
+
+function safeTimestamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function copyRecursive(src: string, dest: string): void {
+  if (!fs.existsSync(src)) {
+    return;
+  }
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+      copyRecursive(path.join(src, entry.name), path.join(dest, entry.name));
+    }
+    return;
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+function createWorkspaceBackup(): string {
+  const backupRoot = path.join('.tmp', 'codument', `upgrade-workspace-${safeTimestamp()}`);
+  const paths = ['codument', 'AGENTS.md'];
+  for (const source of paths) {
+    if (fs.existsSync(source)) {
+      copyRecursive(source, path.join(backupRoot, source));
+    }
+  }
+  return backupRoot;
+}
+
+function removeLegacyWorkspacePaths(backupRoot: string): number {
+  const legacyPaths = [
+    'codument/state.json',
+    'codument/config/feature.json',
+    'codument/workflows/workflow.md',
+    'codument/workflows/bun-dev-cmds.md',
+    'codument/legacy',
+    'codument/specs',
+    'codument/std/workflow.md',
+    'codument/std/protocols.md',
+    'codument/std/operations/init.md',
+    'codument/std/operations/status.md',
+    'codument/std/plan-xml-spec.md',
+    'codument/std/track-impl-gap-report-1.md',
+    'codument/attractors/knowledge-tiers.md',
+    'codument/attractors/model-driven-docs.md',
+    'codument/attractors/project-memory.md',
+  ];
+
+  let removed = 0;
+  for (const legacyPath of legacyPaths) {
+    if (!fs.existsSync(legacyPath)) {
+      continue;
+    }
+    copyRecursive(legacyPath, path.join(backupRoot, legacyPath));
+    fs.rmSync(legacyPath, { recursive: true, force: true });
+    removed++;
+  }
+  return removed;
+}