dw-kit 1.3.6 → 1.6.0-rc.1

package/src/commands/review-render.mjs

@@ -0,0 +1,255 @@
+import { createRequire } from 'node:module';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { performance } from 'node:perf_hooks';
+import chalk from 'chalk';
+import { header, ok, info, log, warn, err } from '../lib/ui.mjs';
+import { loadConfigWithLocal, getReviewRendererConfig } from '../lib/config.mjs';
+import { readManifest } from '../lib/review/manifest-validator.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+const RENDER_PACKAGE = 'dw-kit-render';
+const INSTALL_HINT = `  Install renderer with: ${chalk.cyan('npm install -g dw-kit-render')}\n  Or run: ${chalk.cyan('dw doctor')} for environment check.`;
+
+/**
+ * `dw review render <manifest>` — invoked by /dw:review --visual after writing manifest.
+ * See ADR-0007 for architecture.
+ *
+ * @param {string} manifestPath - path to manifest.json (relative or absolute)
+ * @param {{format?: string, strategy?: string, quiet?: boolean}} opts
+ */
+export async function reviewRenderCommand(manifestPath, opts = {}) {
+  const projectDir = process.cwd();
+  const absManifest = isAbsolute(manifestPath) ? manifestPath : resolve(projectDir, manifestPath);
+  const startedAt = performance.now();
+
+  if (!opts.quiet) header('dw review render');
+
+  // 1. Load + validate manifest.
+  const parseResult = readManifest(absManifest);
+  if (!parseResult.ok) {
+    err(`Manifest invalid: ${absManifest}`);
+    for (const e of parseResult.errors.slice(0, 10)) {
+      log(`  ${chalk.dim(e.path || '/')} — ${e.message}`);
+    }
+    logEvent({ event: 'review_render', action: 'fail', fallback_reason: 'invalid-manifest' }, projectDir);
+    process.exit(1);
+  }
+  const manifest = parseResult.manifest;
+
+  // 2. Resolve config + strategy.
+  const config = loadConfigWithLocal(join(projectDir, '.dw', 'config')) || {};
+  const rendererCfg = getReviewRendererConfig(config);
+  const strategy = opts.strategy || rendererCfg.strategy;
+  const formats = parseFormats(opts.format) || rendererCfg.formats;
+
+  // 3. Resolve output directory.
+  const outDir = resolveOutputDir(rendererCfg.output_dir, manifest, projectDir);
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+
+  if (!opts.quiet) {
+    info('Render context');
+    log(`  Manifest    : ${absManifest}`);
+    log(`  Scope       : ${manifest.scope} (slug: ${manifest.scope_slug || '—'})`);
+    log(`  Findings    : ${manifest.findings.length}`);
+    log(`  Strategy    : ${strategy}`);
+    log(`  Formats     : ${formats.join(', ')}`);
+    log(`  Output dir  : ${outDir}`);
+  }
+
+  // 4. Resolve renderer (dw-kit-render package).
+  const rendererResolved = strategy === 'markdown-only' ? null : await tryResolveRenderer(projectDir);
+  const finalStrategy = strategy === 'markdown-only'
+    ? 'markdown-only'
+    : (rendererResolved ? 'plugin' : (strategy === 'plugin' ? 'plugin-missing' : 'fallback-markdown'));
+
+  // Plugin strategy was requested but package is missing — fail loudly.
+  if (strategy === 'plugin' && !rendererResolved) {
+    err(`Strategy 'plugin' requested but '${RENDER_PACKAGE}' is not installed.`);
+    log(INSTALL_HINT);
+    logEvent({ event: 'review_render', action: 'fail', fallback_reason: 'no-renderer', strategy, formats }, projectDir);
+    process.exit(1);
+  }
+
+  let artifacts = { svg: [], png: [] };
+  let renderErrors = [];
+
+  if (rendererResolved) {
+    try {
+      if (!opts.quiet) info('Rendering with dw-kit-render');
+      const result = await rendererResolved.render({
+        manifest,
+        outDir,
+        formats,
+        theme: rendererCfg.theme,
+        font: rendererCfg.font,
+      });
+      artifacts = {
+        svg: Array.isArray(result?.svgPaths) ? result.svgPaths : [],
+        png: Array.isArray(result?.pngPaths) ? result.pngPaths : [],
+      };
+    } catch (e) {
+      renderErrors.push(e.message || String(e));
+      warn(`Renderer error: ${e.message || e}`);
+      warn('Falling back to markdown-only summary.');
+    }
+  } else if (strategy !== 'markdown-only') {
+    if (!opts.quiet) {
+      warn(`'${RENDER_PACKAGE}' not found — emitting markdown summary only.`);
+      log(INSTALL_HINT);
+    }
+  }
+
+  // 5. Write summary.md (always — works without renderer too).
+  const summaryPath = join(outDir, 'summary.md');
+  writeFileSync(summaryPath, buildSummaryMarkdown(manifest, artifacts, { outDir, projectDir }), 'utf-8');
+
+  const durationMs = Math.round(performance.now() - startedAt);
+
+  if (!opts.quiet) {
+    console.log();
+    info('Artifacts');
+    log(`  Summary     : ${summaryPath}`);
+    if (artifacts.svg.length) log(`  SVG         : ${artifacts.svg.length} file(s)`);
+    if (artifacts.png.length) log(`  PNG         : ${artifacts.png.length} file(s)`);
+    if (!artifacts.svg.length && !artifacts.png.length) log(`  ${chalk.dim('(markdown only — install dw-kit-render for images)')}`);
+    console.log();
+    if (renderErrors.length) {
+      warn(`${renderErrors.length} render error(s) — see above`);
+    } else {
+      ok(`Done in ${durationMs}ms`);
+    }
+  }
+
+  logEvent({
+    event: 'review_render',
+    action: renderErrors.length ? 'partial' : 'success',
+    strategy: finalStrategy,
+    formats,
+    findings: manifest.findings.length,
+    duration_ms: durationMs,
+    fallback_reason: rendererResolved ? null : (strategy === 'markdown-only' ? 'config-markdown-only' : 'no-renderer'),
+  }, projectDir);
+
+  process.exit(0);
+}
+
+function parseFormats(value) {
+  if (!value) return null;
+  if (value === 'both') return ['svg', 'png'];
+  if (value === 'svg' || value === 'png') return [value];
+  return null;
+}
+
+function resolveOutputDir(configDir, manifest, projectDir) {
+  const baseDir = isAbsolute(configDir) ? configDir : join(projectDir, configDir);
+  const slug = manifest.scope_slug || manifest.scope || 'review';
+  return join(baseDir, slug);
+}
+
+async function tryResolveRenderer(projectDir) {
+  // Test-only escape hatch: tests use this to force the markdown fallback even
+  // when a local renderer is dev-linked from a sibling packages/ dir.
+  if (process.env.DW_REVIEW_NO_RENDERER === '1') return null;
+
+  // Resolution order: project node_modules → CLI's own node_modules (global -g case).
+  // We use createRequire to get a *resolution* path, then dynamic-import that URL
+  // so the renderer can be ESM-only (Phase 1 ships ESM only).
+  for (const anchor of [join(projectDir, 'package.json'), import.meta.url]) {
+    try {
+      const req = createRequire(anchor);
+      const entry = req.resolve(RENDER_PACKAGE);
+      const mod = await import(pathToFileURL(entry).href);
+      const render = mod?.render || mod?.default?.render;
+      if (typeof render !== 'function') {
+        throw new Error("dw-kit-render module did not export a 'render' function");
+      }
+      return { render };
+    } catch {
+      // try next anchor
+    }
+  }
+  return null;
+}
+
+function buildSummaryMarkdown(manifest, artifacts, { outDir, projectDir }) {
+  const lines = [];
+  const counts = countBySeverity(manifest.findings);
+  const slug = manifest.scope_slug || manifest.scope;
+
+  lines.push(`# Review summary — ${manifest.scope}`);
+  lines.push('');
+  lines.push(`- Generated: ${manifest.generated_at}`);
+  if (manifest.review_meta?.diff_base) lines.push(`- Diff base: ${manifest.review_meta.diff_base}`);
+  if (manifest.review_meta?.files_reviewed != null) lines.push(`- Files reviewed: ${manifest.review_meta.files_reviewed}`);
+  if (manifest.task_id) lines.push(`- Task: \`${manifest.task_id}\``);
+  lines.push('');
+  lines.push(`**Severity counts:** critical=${counts.critical}, warning=${counts.warning}, suggestion=${counts.suggestion}`);
+  lines.push('');
+
+  if (!manifest.findings.length) {
+    lines.push('No findings.');
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  lines.push('## Findings');
+  lines.push('');
+  for (const f of manifest.findings) {
+    const loc = formatLocation(f.location);
+    lines.push(`### [${f.severity.toUpperCase()}] ${f.title}`);
+    lines.push('');
+    lines.push(`- File: \`${loc}\``);
+    if (f.rule_ref) lines.push(`- Rule: ${f.rule_ref}`);
+
+    const svg = artifacts.svg.find((p) => p.endsWith(`finding-${f.id}.svg`));
+    const png = artifacts.png.find((p) => p.endsWith(`finding-${f.id}.png`));
+    if (svg) lines.push(`- SVG: \`${relativeTo(svg, outDir)}\``);
+    if (png) lines.push(`- PNG: \`${relativeTo(png, outDir)}\``);
+    lines.push('');
+    lines.push(f.body);
+    lines.push('');
+    if (f.code_snippet) {
+      const lang = f.language || '';
+      lines.push('```' + lang);
+      lines.push(f.code_snippet);
+      lines.push('```');
+      lines.push('');
+    }
+    if (f.fix) {
+      lines.push(`**Fix:** ${f.fix}`);
+      lines.push('');
+    }
+    lines.push('---');
+    lines.push('');
+  }
+
+  lines.push(`*Manifest: \`${relativeTo(join(outDir, 'manifest.json'), projectDir)}\`*`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+function countBySeverity(findings) {
+  const out = { critical: 0, warning: 0, suggestion: 0 };
+  for (const f of findings) {
+    if (out[f.severity] != null) out[f.severity]++;
+  }
+  return out;
+}
+
+function formatLocation(loc) {
+  if (!loc) return '?';
+  if (loc.line_start && loc.line_end && loc.line_start !== loc.line_end) {
+    return `${loc.file}:${loc.line_start}-${loc.line_end}`;
+  }
+  if (loc.line_start) return `${loc.file}:${loc.line_start}`;
+  return loc.file;
+}
+
+function relativeTo(target, base) {
+  const t = target.replace(/\\/g, '/');
+  const b = base.replace(/\\/g, '/').replace(/\/$/, '');
+  if (t.startsWith(b + '/')) return t.slice(b.length + 1);
+  return t;
+}

package/src/commands/task-migrate.mjs

@@ -0,0 +1,366 @@
+import { readFileSync, writeFileSync, existsSync, copyFileSync, readdirSync, statSync, renameSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { parseFrontmatter, stringifyFrontmatter } from '../lib/frontmatter.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+const TASKS_DIR = '.dw/tasks';
+
+function todayIso() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function readSection(content, headingPattern) {
+  const startRe = new RegExp(`^##\\s+${headingPattern}\\s*$`, 'm');
+  const startMatch = content.match(startRe);
+  if (!startMatch) return '';
+  const startIdx = startMatch.index + startMatch[0].length;
+  const rest = content.slice(startIdx);
+  const endMatch = rest.match(/^##\s+/m);
+  const sectionText = endMatch ? rest.slice(0, endMatch.index) : rest;
+  return sectionText.trim();
+}
+
+function stripFrontmatter(content) {
+  return content.replace(/^---\n[\s\S]*?\n---\n?/, '');
+}
+
+function stripStatusMarkers(text) {
+  return text
+    .replace(/\s*✅\s*COMPLETED\s*\d{4}-\d{2}-\d{2}/g, '')
+    .replace(/\s*✅\s*DONE\s*\d{4}-\d{2}-\d{2}/g, '')
+    .replace(/\s*🟡\s*[A-Z\s]+\s*\d{4}-\d{2}-\d{2}/g, '')
+    .replace(/\s*←\s*START HERE/g, '');
+}
+
+// Priority order matters: more specific / higher-severity statuses win.
+const STATUS_KEYWORDS = [
+  ['Blocked', /\b(blocked|blocking)\b/i],
+  ['Done', /\b(done|completed?|shipped?|released|ship[- ]?ready|verified|merged)\b/i],
+  ['Paused', /\b(paused|on\s+hold)\b/i],
+  ['In Progress', /\b(in\s+progress|wip|active|ongoing|executing)\b/i],
+  ['Approved', /\b(approved|spec[- ]?approved|plan[- ]?approved)\b/i],
+  ['Draft', /\b(draft|proposed|new|todo)\b/i],
+];
+
+function normalizeStatus(raw) {
+  if (!raw) return 'Draft';
+  const s = String(raw).trim();
+  for (const [canonical, re] of STATUS_KEYWORDS) {
+    if (re.test(s)) return canonical;
+  }
+  return 'Draft';
+}
+
+function normalizeDate(raw) {
+  if (!raw) return todayIso();
+  const s = String(raw).trim();
+  const m = s.match(/^\d{4}-\d{2}-\d{2}$/);
+  if (m) return s;
+  return todayIso();
+}
+
+function mergeFrontmatter(specFm, trackingFm) {
+  const rawStatus = trackingFm.status || specFm.status || '';
+  return {
+    task_id: trackingFm.task_id || specFm.task_id,
+    created: normalizeDate(specFm.created || trackingFm.started),
+    last_updated: normalizeDate(trackingFm.last_updated),
+    status: normalizeStatus(rawStatus),
+    phase: trackingFm.current_phase || specFm.status || 'Migrated from v2',
+    owner: specFm.owner || trackingFm.owner || 'unknown',
+    depth: specFm.depth || 'standard',
+    related_adr: String(specFm.related_adr || 'none').match(/^(ADR-\d{4}|none)$/) ? specFm.related_adr : 'none',
+    target_ship: specFm.target_ship || 'TBD',
+    schema_version: 'v3.0',
+    blockers: trackingFm.blockers || 'none',
+  };
+}
+
+function stripPrivateFields(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (k.startsWith('_') || v === undefined) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+function buildV3Body(taskTitle, specContent, trackingContent, mergedFm) {
+  const specBody = stripFrontmatter(specContent);
+  const trackingBody = stripFrontmatter(trackingContent);
+
+  const intent = readSection(specBody, 'Intent') || '_TODO: migrate from v2 spec_';
+  const whyNow = readSection(specBody, 'Why Now');
+  const scopeIn = readSection(specBody, '(?:In )?Scope|Scope.*?In Scope');
+  const scopeOut = readSection(specBody, '(?:Out of Scope|Won\'t Contain)');
+  const acceptance = readSection(specBody, '(?:Acceptance|Success Criteria|Task Complete When)');
+  const risks = readSection(specBody, 'Risks(?:\\s+&\\s+Mitigations)?');
+  const deps = readSection(specBody, 'Dependencies');
+
+  const snapshot = readSection(trackingBody, 'Status Snapshot');
+  const trackerTable = readSection(trackingBody, '(?:Subtask Progress|Tracker)');
+  const changelog = readSection(trackingBody, 'Changelog');
+  const handoff = readSection(trackingBody, 'Handoff(?:\\s+Notes)?');
+  const friction = readSection(trackingBody, 'Friction(?:\\s+Journal)?');
+  const debate = readSection(trackingBody, 'Agent Debate Log.*');
+
+  const status = String(mergedFm.status);
+  const phase = String(mergedFm.phase);
+  const blockers = String(mergedFm.blockers);
+  const lastUpdated = String(mergedFm.last_updated);
+
+  const snapshotLines = [
+    `**Phase:** ${phase}`,
+    `**Status:** ${status}`,
+    `**Owner:** ${String(mergedFm.owner)}`,
+    `**Blockers:** ${blockers}`,
+    `**Last updated:** ${lastUpdated}`,
+  ];
+  if (snapshot) snapshotLines.push('', '<!-- Migrated from v2 tracking.md Status Snapshot -->', snapshot);
+
+  const sec2 = [
+    '### Intent',
+    '',
+    intent,
+  ];
+  if (whyNow) sec2.push('', '### Why Now', '', whyNow);
+  sec2.push('', '### Subtasks (in scope)', '', stripStatusMarkers(scopeIn || '_TODO: list subtasks_'));
+  if (scopeOut) sec2.push('', '### Out of Scope', '', scopeOut);
+  if (acceptance) sec2.push('', '### Success Criteria', '', acceptance);
+  if (deps) sec2.push('', '### Dependencies', '', deps);
+  if (risks) sec2.push('', '### Risk Register', '', risks);
+
+  const STATUS_LEGEND = 'Status legend: ⬜ Pending · 🟡 In Progress · ✅ Done · 🔴 Blocked · ⏸ Paused';
+  const baseSec3 = trackerTable
+    || `| # | Subtask | Status | Date | Notes |\n|---|---------|--------|------|-------|\n| ST-1 | _TODO: populate from v2_ | ⬜ Pending | — | |`;
+  const sec3 = baseSec3.includes('Status legend') ? baseSec3 : `${baseSec3}\n\n${STATUS_LEGEND}`;
+
+  const sec4 = changelog || `### ${todayIso()} — Migrated from v2\n\n**Actions:** Migrated spec.md + tracking.md → task.md via \`dw task migrate\`.\n`;
+
+  const sec5 = [];
+  if (handoff) sec5.push(handoff);
+  if (friction) sec5.push('', '### Friction Journal', '', friction);
+  const sec5Text = sec5.join('\n') || '_TODO: handoff notes_';
+
+  const lines = [
+    `# Timeline: ${taskTitle}`,
+    '',
+    '<!-- Migrated from v2 spec.md + tracking.md. Review for status drift markers in Section 2. -->',
+    '<!-- ![Timeline](./timeline.svg) -->',
+    '<!-- SVG sidecar will be injected by `dw task render` or pre-commit hook (WS-4/WS-5). -->',
+    '',
+    '## 1. Snapshot',
+    '',
+    snapshotLines.join('\n'),
+    '',
+    '## 2. Intent & Scope',
+    '',
+    sec2.join('\n'),
+    '',
+    '## 3. Subtask Tracker',
+    '',
+    sec3,
+    '',
+    '## 4. Timeline / Changelog',
+    '',
+    sec4,
+    '',
+    '## 5. Handoff & Friction',
+    '',
+    sec5Text,
+    '',
+    '## 6. Annexes',
+    '',
+    '- (legacy spec.md.v2bak + tracking.md.v2bak preserved for rollback)',
+  ];
+
+  if (debate) {
+    lines.push('', '## 7. Debate Log', '', debate);
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+function lineDiff(oldText, newText) {
+  const oldLines = oldText.split('\n');
+  const newLines = newText.split('\n');
+  const max = Math.max(oldLines.length, newLines.length);
+  let diff = '';
+  for (let i = 0; i < max; i++) {
+    const o = oldLines[i] ?? '';
+    const n = newLines[i] ?? '';
+    if (o === n) continue;
+    if (o && !newLines.includes(o)) diff += chalk.red(`- ${o}\n`);
+    if (n && !oldLines.includes(n)) diff += chalk.green(`+ ${n}\n`);
+  }
+  return diff;
+}
+
+function findV2Tasks(rootDir) {
+  const tasksRoot = join(rootDir, TASKS_DIR);
+  if (!existsSync(tasksRoot)) return [];
+  return readdirSync(tasksRoot)
+    .filter((e) => e !== 'archive' && e !== 'ACTIVE.md')
+    .map((e) => ({ name: e, path: join(tasksRoot, e) }))
+    .filter((e) => {
+      try {
+        if (!statSync(e.path).isDirectory()) return false;
+        if (existsSync(join(e.path, 'task.md'))) return false;
+        return existsSync(join(e.path, 'spec.md')) || existsSync(join(e.path, 'tracking.md'));
+      } catch { return false; }
+    });
+}
+
+async function migrateOne(taskDir, opts) {
+  const specFile = join(taskDir, 'spec.md');
+  const trackingFile = join(taskDir, 'tracking.md');
+  const targetFile = join(taskDir, 'task.md');
+  const specBak = join(taskDir, 'spec.md.v2bak');
+  const trackingBak = join(taskDir, 'tracking.md.v2bak');
+
+  if (existsSync(targetFile) && !opts.force) {
+    console.log(chalk.yellow(`  ⚠  ${taskDir} — task.md already exists (use --force to overwrite)`));
+    return { ok: false, skipped: true };
+  }
+
+  const specContent = existsSync(specFile) ? readFileSync(specFile, 'utf8') : '';
+  const trackingContent = existsSync(trackingFile) ? readFileSync(trackingFile, 'utf8') : '';
+
+  if (!specContent && !trackingContent) {
+    console.log(chalk.yellow(`  ⚠  ${taskDir} — no v2 files (spec.md/tracking.md) found, skipping`));
+    return { ok: false, skipped: true };
+  }
+
+  const specFm = specContent ? parseFrontmatter(specContent) : {};
+  const trackingFm = trackingContent ? parseFrontmatter(trackingContent) : {};
+  const merged = mergeFrontmatter(specFm, trackingFm);
+
+  const titleMatch = (specContent || trackingContent).match(/^#\s+(?:Spec:|Tracking:)?\s*(.+?)\s*$/m);
+  const title = titleMatch ? titleMatch[1] : (merged.task_id || taskDir.split(/[\\/]/).pop());
+
+  const body = buildV3Body(title, specContent, trackingContent, merged);
+  const fmForWrite = stripPrivateFields(merged);
+  const v3Content = stringifyFrontmatter(fmForWrite) + '\n' + body;
+
+  if (opts.dryRun) {
+    console.log(chalk.cyan(`\n  --- Dry run: ${taskDir} ---`));
+    console.log(chalk.dim('  Would write:'));
+    console.log(v3Content.split('\n').slice(0, 30).map((l) => `    ${l}`).join('\n'));
+    if (v3Content.split('\n').length > 30) {
+      console.log(chalk.dim(`    ... (${v3Content.split('\n').length - 30} more lines)`));
+    }
+    return { ok: true, dryRun: true };
+  }
+
+  if (opts.diff && existsSync(targetFile)) {
+    const existing = readFileSync(targetFile, 'utf8');
+    if (existing === v3Content) {
+      console.log(chalk.dim(`  · ${taskDir} — no changes`));
+      return { ok: true, noop: true };
+    }
+    console.log(chalk.cyan(`\n  --- Diff: ${taskDir} ---`));
+    console.log(lineDiff(existing, v3Content));
+    return { ok: true, diff: true };
+  }
+
+  if (existsSync(specFile) && !existsSync(specBak)) copyFileSync(specFile, specBak);
+  if (existsSync(trackingFile) && !existsSync(trackingBak)) copyFileSync(trackingFile, trackingBak);
+
+  writeFileSync(targetFile, v3Content, 'utf8');
+
+  if (opts.removeV2) {
+    if (existsSync(specFile)) unlinkSync(specFile);
+    if (existsSync(trackingFile)) unlinkSync(trackingFile);
+  }
+
+  console.log(chalk.green(`  ✓  ${taskDir} — migrated`));
+  return { ok: true };
+}
+
+async function rollbackOne(taskDir) {
+  const specBak = join(taskDir, 'spec.md.v2bak');
+  const trackingBak = join(taskDir, 'tracking.md.v2bak');
+  const specFile = join(taskDir, 'spec.md');
+  const trackingFile = join(taskDir, 'tracking.md');
+  const targetFile = join(taskDir, 'task.md');
+
+  if (!existsSync(specBak) && !existsSync(trackingBak)) {
+    console.log(chalk.yellow(`  ⚠  ${taskDir} — no backups to restore`));
+    return { ok: false };
+  }
+  if (existsSync(specBak)) renameSync(specBak, specFile);
+  if (existsSync(trackingBak)) renameSync(trackingBak, trackingFile);
+  if (existsSync(targetFile)) unlinkSync(targetFile);
+  console.log(chalk.green(`  ✓  ${taskDir} — rolled back`));
+  return { ok: true };
+}
+
+export async function taskMigrateCommand(taskName, opts = {}) {
+  const rootDir = process.cwd();
+
+  if (opts.rollback) {
+    const taskDir = taskName
+      ? join(rootDir, TASKS_DIR, taskName)
+      : null;
+    if (taskDir) {
+      const r = await rollbackOne(taskDir);
+      logEvent({ event: 'task', action: 'migrate.rollback', name: taskName, success: r.ok }, rootDir);
+      return;
+    }
+    console.error(chalk.red('✗ --rollback requires a task name'));
+    process.exit(1);
+  }
+
+  let targets;
+  if (taskName) {
+    targets = [{ name: taskName, path: join(rootDir, TASKS_DIR, taskName) }];
+  } else if (opts.all) {
+    targets = findV2Tasks(rootDir);
+    if (targets.length === 0) {
+      console.log(chalk.dim('  No v2 tasks found to migrate.'));
+      return;
+    }
+  } else {
+    console.error(chalk.red('✗ Provide a task name or use --all to scan for v2 tasks'));
+    console.error(chalk.dim('  Examples:'));
+    console.error(chalk.dim('    dw task migrate dw-kit-v2-lean-optimization --dry-run'));
+    console.error(chalk.dim('    dw task migrate --all --dry-run'));
+    console.error(chalk.dim('    dw task migrate dw-kit-v2-lean-optimization --rollback'));
+    process.exit(1);
+  }
+
+  console.log();
+  const action = opts.dryRun ? 'Dry-run migrate' : opts.diff ? 'Diff migrate' : 'Migrate';
+  console.log(chalk.bold(`  ${action} (${targets.length} task${targets.length === 1 ? '' : 's'}):`));
+
+  const results = [];
+  for (const t of targets) {
+    const r = await migrateOne(t.path, opts);
+    results.push({ name: t.name, ...r });
+  }
+
+  const okCount = results.filter((r) => r.ok && !r.dryRun && !r.diff && !r.noop && !r.skipped).length;
+  const skipped = results.filter((r) => r.skipped).length;
+
+  logEvent({
+    event: 'task',
+    action: 'migrate.run',
+    count: results.length,
+    success: okCount,
+    skipped,
+    dry_run: !!opts.dryRun,
+  }, rootDir);
+
+  console.log();
+  if (opts.dryRun) {
+    console.log(chalk.cyan(`  Dry-run complete. Re-run without --dry-run to apply.`));
+  } else if (opts.diff) {
+    console.log(chalk.cyan(`  Diff complete.`));
+  } else {
+    console.log(chalk.green(`  ${okCount}/${results.length} migrated, ${skipped} skipped.`));
+    console.log(chalk.dim(`  Backups saved as spec.md.v2bak / tracking.md.v2bak. Run \`dw task migrate <name> --rollback\` to undo.`));
+    console.log(chalk.dim(`  Run \`dw active\` to refresh ACTIVE.md.`));
+  }
+  console.log();
+}