dw-kit 1.4.0 → 1.7.0-rc.1

package/src/commands/lint-task.mjs

@@ -0,0 +1,112 @@
+import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import chalk from 'chalk';
+import yaml from 'js-yaml';
+import { lintTimeline, findAllTaskDirs } from '../lib/lint-rules.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+const TASKS_DIR = '.dw/tasks';
+
+function getLintLevel(rootDir) {
+  try {
+    const cfgPath = join(rootDir, '.dw', 'config', 'dw.config.yml');
+    if (!existsSync(cfgPath)) return 'strict';
+    const cfg = yaml.load(readFileSync(cfgPath, 'utf8'), { schema: yaml.CORE_SCHEMA });
+    return cfg?.task?.lint ?? cfg?.task_lint ?? 'strict';
+  } catch {
+    return 'strict';
+  }
+}
+
+function severityColor(sev) {
+  if (sev === 'error') return chalk.red;
+  if (sev === 'warning') return chalk.yellow;
+  return chalk.dim;
+}
+
+function printViolations(taskDir, result) {
+  if (result.violations.length === 0) {
+    console.log(chalk.green(`  ✓  ${taskDir} — clean`));
+    return;
+  }
+  console.log();
+  console.log(chalk.bold(`  ${taskDir}`));
+  for (const v of result.violations) {
+    const sev = severityColor(v.severity)(`[${v.severity}]`);
+    const rule = chalk.dim(`(${v.rule})`);
+    const lineRef = v.line ? chalk.dim(`:${v.line}`) : '';
+    console.log(`    ${sev} ${v.message} ${rule}${lineRef}`);
+  }
+}
+
+export async function lintTaskCommand(taskName, opts = {}) {
+  const rootDir = process.cwd();
+  const level = opts.level || getLintLevel(rootDir);
+
+  if (level === 'off') {
+    console.log(chalk.dim('  Task lint disabled (task_lint: off in dw.config.yml). Skipping.'));
+    return;
+  }
+
+  let targets;
+  if (taskName) {
+    targets = [join(rootDir, TASKS_DIR, taskName)];
+  } else {
+    targets = findAllTaskDirs(rootDir);
+  }
+
+  if (targets.length === 0) {
+    console.log(chalk.dim('  No v3 tasks to lint.'));
+    return;
+  }
+
+  console.log();
+  console.log(chalk.bold(`  Linting ${targets.length} task${targets.length === 1 ? '' : 's'} (level: ${level})`));
+
+  let totalErrors = 0;
+  let totalWarnings = 0;
+  let totalClean = 0;
+
+  for (const dir of targets) {
+    const result = lintTimeline(dir);
+    printViolations(dir, result);
+    const errs = result.violations.filter((v) => v.severity === 'error').length;
+    const warns = result.violations.filter((v) => v.severity === 'warning').length;
+    totalErrors += errs;
+    totalWarnings += warns;
+    if (result.violations.length === 0) totalClean++;
+
+    for (const v of result.violations) {
+      logEvent({
+        event: 'task',
+        action: 'lint.violation',
+        rule: v.rule,
+        severity: v.severity,
+      }, rootDir);
+    }
+  }
+
+  console.log();
+  const summary = `  ${totalClean} clean · ${totalWarnings} warnings · ${totalErrors} errors`;
+  if (totalErrors > 0) {
+    console.log(chalk.red(summary));
+  } else if (totalWarnings > 0) {
+    console.log(chalk.yellow(summary));
+  } else {
+    console.log(chalk.green(summary));
+  }
+  console.log();
+
+  logEvent({
+    event: 'task',
+    action: 'lint.run',
+    targets: targets.length,
+    errors: totalErrors,
+    warnings: totalWarnings,
+    level,
+  }, rootDir);
+
+  if (level === 'strict' && totalErrors > 0) {
+    process.exit(1);
+  }
+}

package/src/commands/task-migrate.mjs

@@ -0,0 +1,471 @@
+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 };
+}
+
+function findV3Tasks(rootDir, targetSchemaVersion = 'v3.0') {
+  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;
+        const taskFile = join(e.path, 'task.md');
+        if (!existsSync(taskFile)) return false;
+        const fm = parseFrontmatter(readFileSync(taskFile, 'utf8'));
+        return fm.schema_version === targetSchemaVersion;
+      } catch { return false; }
+    });
+}
+
+async function migrateOneToV31(taskDir, opts) {
+  const taskFile = join(taskDir, 'task.md');
+  if (!existsSync(taskFile)) {
+    console.log(chalk.yellow(`  ⚠  ${taskDir} — task.md not found, skipping`));
+    return { ok: false, skipped: true };
+  }
+  const content = readFileSync(taskFile, 'utf8');
+  const fm = parseFrontmatter(content);
+  if (fm.schema_version === 'v3.1') {
+    console.log(chalk.dim(`  · ${taskDir} — already v3.1`));
+    return { ok: true, noop: true };
+  }
+  if (fm.schema_version !== 'v3.0') {
+    console.log(chalk.yellow(`  ⚠  ${taskDir} — schema_version=${fm.schema_version || 'missing'}, expected v3.0 — skipping`));
+    return { ok: false, skipped: true };
+  }
+
+  const updated = { ...fm, schema_version: 'v3.1' };
+  if (!('parent_goal_id' in updated)) updated.parent_goal_id = null;
+  if (!('contributing_goal_ids' in updated)) updated.contributing_goal_ids = [];
+  if (!('summary' in updated)) updated.summary = null;
+
+  const body = content.replace(/^---\n[\s\S]*?\n---\n?/, '');
+  const newContent = stringifyFrontmatter(updated) + body;
+
+  if (opts.dryRun) {
+    console.log(chalk.cyan(`  · ${taskDir} — would bump v3.0 → v3.1 (adds parent_goal_id, contributing_goal_ids, summary)`));
+    return { ok: true, dryRun: true };
+  }
+
+  writeFileSync(taskFile, newContent, 'utf8');
+  console.log(chalk.green(`  ✓  ${taskDir} — bumped v3.0 → v3.1`));
+  return { ok: true };
+}
+
+export async function taskMigrateCommand(taskName, opts = {}) {
+  const rootDir = process.cwd();
+
+  if (opts.toV31) {
+    let targets;
+    if (taskName) {
+      targets = [{ name: taskName, path: join(rootDir, TASKS_DIR, taskName) }];
+    } else if (opts.all) {
+      targets = findV3Tasks(rootDir, 'v3.0');
+      if (targets.length === 0) {
+        console.log(chalk.dim('  No v3.0 tasks found to bump to v3.1.'));
+        return;
+      }
+    } else {
+      console.error(chalk.red('✗ --to-v3.1 requires a task name or --all'));
+      console.error(chalk.dim('  Examples:'));
+      console.error(chalk.dim('    dw task migrate --to-v3.1 --all --dry-run'));
+      console.error(chalk.dim('    dw task migrate goals-management-layer --to-v3.1'));
+      process.exit(1);
+    }
+
+    console.log();
+    const action = opts.dryRun ? 'Dry-run bump' : 'Bump';
+    console.log(chalk.bold(`  ${action} schema v3.0 → v3.1 (${targets.length} task${targets.length === 1 ? '' : 's'}):`));
+
+    const results = [];
+    for (const t of targets) {
+      const r = await migrateOneToV31(t.path, opts);
+      results.push({ name: t.name, ...r });
+    }
+    const bumpedCount = results.filter((r) => r.ok && !r.dryRun && !r.noop && !r.skipped).length;
+    const noop = results.filter((r) => r.noop).length;
+    const skipped = results.filter((r) => r.skipped).length;
+
+    logEvent({
+      event: 'task',
+      action: 'migrate.to-v3.1',
+      count: results.length,
+      success: bumpedCount,
+      noop,
+      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 {
+      console.log(chalk.green(`  ${bumpedCount}/${results.length} bumped, ${noop} already v3.1, ${skipped} skipped.`));
+      console.log(chalk.dim(`  v3.1 adds optional parent_goal_id, contributing_goal_ids, summary fields per ADR-0010.`));
+      console.log(chalk.dim(`  Run \`dw task lint\` to verify.`));
+    }
+    console.log();
+    return;
+  }
+
+  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();
+}

package/src/commands/task-new.mjs

@@ -0,0 +1,90 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import { logEvent } from '../lib/telemetry.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TASKS_DIR = '.dw/tasks';
+const TEMPLATE_REL = join('.dw', 'core', 'templates', 'v3', 'task.md');
+const BUNDLED_TEMPLATE = join(__dirname, '..', '..', '.dw', 'core', 'templates', 'v3', 'task.md');
+
+function todayIso() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function slugify(name) {
+  return name
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-')
+    .slice(0, 64);
+}
+
+function loadTemplate(rootDir) {
+  const local = join(rootDir, TEMPLATE_REL);
+  if (existsSync(local)) return readFileSync(local, 'utf8');
+  if (existsSync(BUNDLED_TEMPLATE)) return readFileSync(BUNDLED_TEMPLATE, 'utf8');
+  throw new Error(`v3 template not found at ${local} or ${BUNDLED_TEMPLATE}`);
+}
+
+export async function taskNewCommand(taskName, opts = {}) {
+  const rootDir = process.cwd();
+  if (!taskName) {
+    console.error(chalk.red('✗ Task name required.'));
+    console.error(chalk.dim('  Usage: dw task new <task-name> [--depth quick|standard|thorough] [--title "..."]'));
+    process.exit(1);
+  }
+
+  const slug = slugify(taskName);
+  if (!slug) {
+    console.error(chalk.red('✗ Invalid task name (empty after slugify).'));
+    process.exit(1);
+  }
+
+  const taskDir = join(rootDir, TASKS_DIR, slug);
+  if (existsSync(taskDir)) {
+    console.error(chalk.red(`✗ Task folder already exists: ${taskDir}`));
+    console.error(chalk.dim('  Pick a different name or remove the existing folder first.'));
+    process.exit(1);
+  }
+
+  const template = loadTemplate(rootDir);
+  const today = todayIso();
+  const title = opts.title || taskName;
+  const depth = opts.depth || 'standard';
+  const owner = opts.owner || process.env.DW_OWNER || process.env.USER || process.env.USERNAME || 'unknown';
+  const relatedAdr = opts.adr || 'none';
+  const targetShip = opts.target || 'TBD';
+
+  let filled = template
+    .replace('task_id: {task-name}', `task_id: ${slug}`)
+    .replace('created: {YYYY-MM-DD}', `created: "${today}"`)
+    .replace('last_updated: {YYYY-MM-DD}', `last_updated: "${today}"`)
+    .replace('phase: {free-form phase description}', `phase: Draft`)
+    .replace('owner: {name}', `owner: ${owner}`)
+    .replace('depth: quick | standard | thorough', `depth: ${depth}`)
+    .replace('related_adr: {ADR-NNNN | none}', `related_adr: ${relatedAdr}`)
+    .replace('target_ship: {milestone or TBD}', `target_ship: ${targetShip}`);
+
+  filled = filled.replace('# Timeline: {Task Title}', `# Timeline: ${title}`);
+
+  mkdirSync(taskDir, { recursive: true });
+  const target = join(taskDir, 'task.md');
+  writeFileSync(target, filled, 'utf8');
+
+  logEvent({ event: 'task', action: 'new', name: slug, depth }, rootDir);
+
+  console.log();
+  console.log(chalk.green('✓') + ` Created v3 task: ${chalk.cyan(slug)}`);
+  console.log(`  ${chalk.dim(target)}`);
+  console.log();
+  console.log(chalk.bold('  Next steps:'));
+  console.log(`    1. Fill in Section 2 (Intent & Scope) — subtasks, success criteria`);
+  console.log(`    2. ${chalk.cyan('dw task show ' + slug)}  — view snapshot`);
+  console.log(`    3. ${chalk.cyan('dw active')}              — refresh ACTIVE.md index`);
+  console.log();
+}