dw-kit 1.4.0 → 1.6.0-rc.1

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();
+}

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();
+}

package/src/commands/task-render.mjs

@@ -0,0 +1,235 @@
+import { readFileSync, writeFileSync, existsSync, statSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import chalk from 'chalk';
+import { parseFrontmatter } from '../lib/frontmatter.mjs';
+import { parseTimeline, parseSubtaskTracker } from '../lib/timeline-parser.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const require = createRequire(import.meta.url);
+const TASKS_DIR = '.dw/tasks';
+
+function findV3Tasks(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 { return statSync(e.path).isDirectory() && existsSync(join(e.path, 'task.md')); }
+      catch { return false; }
+    });
+}
+
+function extractManifest(taskDir) {
+  const timelineFile = join(taskDir, 'task.md');
+  if (!existsSync(timelineFile)) return null;
+  const content = readFileSync(timelineFile, 'utf8');
+  const fm = parseFrontmatter(content);
+  const parsed = parseTimeline(content);
+  const subtasks = parseSubtaskTracker(parsed.sections[3]?.text);
+
+  return {
+    task_id: fm.task_id || taskDir.split(/[\\/]/).pop(),
+    title: parsed.title || fm.task_id,
+    status: fm.status || 'Draft',
+    phase: fm.phase || '',
+    owner: fm.owner || '',
+    blockers: fm.blockers || 'none',
+    last_updated: fm.last_updated || '',
+    related_adr: fm.related_adr || 'none',
+    depth: fm.depth || 'standard',
+    subtasks,
+    schema_version: 'task-manifest@v1',
+  };
+}
+
+function resolveRenderer() {
+  try {
+    const pkgPath = require.resolve('dw-kit-render/package.json', { paths: [process.cwd(), __dirname] });
+    const pkgDir = dirname(pkgPath);
+    return pkgDir;
+  } catch {
+    const localCandidate = join(__dirname, '..', '..', 'packages', 'dw-kit-render', 'package.json');
+    if (existsSync(localCandidate)) return dirname(localCandidate);
+    return null;
+  }
+}
+
+async function renderViaSubpackage(manifest, outFile, formats) {
+  const pkgDir = resolveRenderer();
+  if (!pkgDir) {
+    return { ok: false, reason: 'sub-package-absent' };
+  }
+  try {
+    const moduleUrl = pathToFileURL(join(pkgDir, 'src', 'index.mjs')).href;
+    const mod = await import(moduleUrl);
+    if (typeof mod.renderTimeline !== 'function') {
+      return { ok: false, reason: 'renderTimeline-not-exported' };
+    }
+    const result = await mod.renderTimeline({ task: manifest, outFile, formats });
+    return { ok: true, result };
+  } catch (e) {
+    return { ok: false, reason: 'render-error', error: e.message };
+  }
+}
+
+function buildMermaidFallback(manifest) {
+  const lines = ['```mermaid', 'gantt', `    title ${manifest.title || manifest.task_id}`, '    dateFormat YYYY-MM-DD', '    axisFormat %m-%d'];
+  const today = new Date().toISOString().slice(0, 10);
+  let section = 'section Subtasks';
+  lines.push(`    ${section}`);
+  const items = manifest.subtasks || [];
+  for (const s of items.slice(0, 20)) {
+    const status = (s.status || '').trim();
+    const taskName = (s.name || s.id || 'Subtask').replace(/[:|]/g, ' ').slice(0, 60);
+    const date = s.date && /^\d{4}-\d{2}-\d{2}$/.test(s.date) ? s.date : today;
+    const ganttStatus = status.startsWith('✅') ? 'done' : status.startsWith('🟡') ? 'active' : status.startsWith('🔴') ? 'crit' : '';
+    const tag = ganttStatus ? `${ganttStatus}, ` : '';
+    lines.push(`    ${taskName}    :${tag}${date}, 1d`);
+  }
+  lines.push('```');
+  return lines.join('\n');
+}
+
+function ensureSvgRefInSection1(content) {
+  if (content.includes('![Timeline](./timeline.svg)') && !content.includes('<!-- ![Timeline](./timeline.svg) -->')) {
+    return content;
+  }
+  const commented = '<!-- ![Timeline](./timeline.svg) -->';
+  if (content.includes(commented)) {
+    return content.replace(commented, '![Timeline](./timeline.svg)');
+  }
+  const sec1Match = content.match(/^## 1\. Snapshot$/m);
+  if (!sec1Match) return content;
+  const insertAt = sec1Match.index;
+  return content.slice(0, insertAt) + '![Timeline](./timeline.svg)\n\n' + content.slice(insertAt);
+}
+
+function ensureMermaidInSection4(content, mermaidBlock) {
+  const sec4Match = content.match(/^## 4\. Timeline \/ Changelog\s*$/m);
+  if (!sec4Match) return content;
+  const insertAt = sec4Match.index + sec4Match[0].length;
+  const afterHeader = content.slice(insertAt);
+  const existingMermaid = afterHeader.match(/```mermaid[\s\S]*?```/);
+  if (existingMermaid && existingMermaid.index < 500) {
+    const startAbs = insertAt + existingMermaid.index;
+    return content.slice(0, startAbs) + mermaidBlock + content.slice(startAbs + existingMermaid[0].length);
+  }
+  return content.slice(0, insertAt) + '\n\n' + mermaidBlock + '\n' + afterHeader;
+}
+
+async function renderOne(taskDir, opts) {
+  const manifest = extractManifest(taskDir);
+  if (!manifest) {
+    return { ok: false, reason: 'no-timeline' };
+  }
+
+  const timelineFile = join(taskDir, 'task.md');
+  const svgOutFile = join(taskDir, 'timeline.svg');
+
+  if (opts.dryRun) {
+    console.log(chalk.cyan(`  --- Dry run: ${taskDir} ---`));
+    console.log(chalk.dim('  Manifest:'));
+    console.log(JSON.stringify(manifest, null, 2).split('\n').map((l) => '    ' + l).join('\n'));
+    return { ok: true, dryRun: true };
+  }
+
+  let svgWritten = false;
+  let usedFallback = false;
+  let renderError = null;
+
+  if (!opts.mermaidOnly) {
+    const r = await renderViaSubpackage(manifest, svgOutFile, opts.formats || ['svg']);
+    if (r.ok) {
+      svgWritten = true;
+    } else {
+      renderError = r;
+      usedFallback = true;
+    }
+  } else {
+    usedFallback = true;
+  }
+
+  const currentMd = readFileSync(timelineFile, 'utf8');
+  let updatedMd = currentMd;
+
+  if (svgWritten) {
+    updatedMd = ensureSvgRefInSection1(updatedMd);
+  }
+
+  if (usedFallback || opts.alwaysMermaid) {
+    const mermaidBlock = buildMermaidFallback(manifest);
+    updatedMd = ensureMermaidInSection4(updatedMd, mermaidBlock);
+  }
+
+  if (updatedMd !== currentMd) {
+    writeFileSync(timelineFile, updatedMd, 'utf8');
+  }
+
+  logEvent({
+    event: 'task',
+    action: 'render.run',
+    name: manifest.task_id,
+    svg: svgWritten,
+    fallback: usedFallback,
+    error: renderError?.reason,
+  }, process.cwd());
+
+  return {
+    ok: true,
+    svgWritten,
+    usedFallback,
+    renderError,
+    svgPath: svgWritten ? svgOutFile : null,
+    timelineUpdated: updatedMd !== currentMd,
+  };
+}
+
+export async function taskRenderCommand(taskName, opts = {}) {
+  const rootDir = process.cwd();
+  let targets;
+  if (taskName) {
+    targets = [{ name: taskName, path: join(rootDir, TASKS_DIR, taskName) }];
+  } else {
+    targets = findV3Tasks(rootDir);
+    if (targets.length === 0) {
+      console.log(chalk.dim('  No v3 tasks to render.'));
+      return;
+    }
+  }
+
+  console.log();
+  console.log(chalk.bold(`  Render ${targets.length} task${targets.length === 1 ? '' : 's'}${opts.dryRun ? ' (dry-run)' : ''}`));
+
+  let svgCount = 0;
+  let fallbackCount = 0;
+
+  for (const t of targets) {
+    const r = await renderOne(t.path, opts);
+    if (!r.ok) {
+      console.log(chalk.red(`  ✗  ${t.name} — ${r.reason || 'failed'}`));
+      continue;
+    }
+    if (r.dryRun) continue;
+    if (r.svgWritten) {
+      console.log(chalk.green(`  ✓  ${t.name} — ${r.svgPath}${r.timelineUpdated ? ' (+ md updated)' : ''}`));
+      svgCount++;
+    } else if (r.usedFallback) {
+      const msg = r.renderError?.reason === 'sub-package-absent'
+        ? 'dw-kit-render absent → Mermaid fallback in Section 4'
+        : `render failed (${r.renderError?.reason}) → Mermaid fallback`;
+      console.log(chalk.yellow(`  ⚠  ${t.name} — ${msg}`));
+      fallbackCount++;
+    }
+  }
+
+  console.log();
+  if (svgCount) console.log(chalk.green(`  SVG: ${svgCount} task${svgCount === 1 ? '' : 's'} rendered`));
+  if (fallbackCount) console.log(chalk.yellow(`  Mermaid fallback: ${fallbackCount} task${fallbackCount === 1 ? '' : 's'}`));
+  if (!svgCount && !fallbackCount && !opts.dryRun) console.log(chalk.dim(`  No rendering performed`));
+  console.log();
+}