kenaz 0.0.0-stage → 0.3.2

package/core/.collaboration/core/migrate-legacy.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+/**
+ * migrate-legacy.js
+ * 將舊系統 (dev/pipeline/) 的任務遷移到新系統 (.collaboration/tasks/archived/)
+ *
+ * 來源：
+ *   1. dev/pipeline/completed/*.yaml — 舊 YAML 檔
+ *   2. dev/pipeline/TASK_QUEUE.json  — JSON 索引（補充 YAML 沒有的）
+ *
+ * 目標：.collaboration/tasks/archived/TASK_XXX.yaml（新系統格式）
+ *
+ * Usage:
+ *   node .collaboration/core/migrate-legacy.js            # 預覽
+ *   node .collaboration/core/migrate-legacy.js --execute   # 執行寫入
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = (() => {
+  try { return require('js-yaml'); } catch {
+    const candidates = [
+      path.resolve(__dirname, '../../.vendor/js-yaml.cjs'),
+      path.resolve(__dirname, '.vendor/js-yaml.cjs'),
+    ];
+    if (process.env.KENAZ_SOURCE_DIR) {
+      candidates.unshift(path.join(process.env.KENAZ_SOURCE_DIR, '.vendor', 'js-yaml.cjs'));
+    }
+    for (const c of candidates) {
+      try { return require(c); } catch { /* next */ }
+    }
+    throw new Error('js-yaml not found. Install it or ensure .vendor/js-yaml.cjs exists.');
+  }
+})();
+const { randomUUID } = require('crypto');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const LEGACY_COMPLETED = path.join(ROOT, 'dev', 'pipeline', 'completed');
+const LEGACY_TASKS = path.join(ROOT, 'dev', 'pipeline', 'tasks');
+const LEGACY_QUEUE = path.join(ROOT, 'dev', 'pipeline', 'TASK_QUEUE.json');
+const NEW_ARCHIVED = path.join(ROOT, '.collaboration', 'tasks', 'archived');
+
+// 新系統所有已存在的任務 ID
+function getExistingIds() {
+  const dirs = ['backlog', 'active', 'done', 'cancel', 'blocked', 'archived'];
+  const ids = new Set();
+  for (const d of dirs) {
+    const dir = path.join(ROOT, '.collaboration', 'tasks', d);
+    if (!fs.existsSync(dir)) continue;
+    for (const f of fs.readdirSync(dir)) {
+      const m = f.match(/^(TASK_\d+)/);
+      if (m) ids.add(m[1]);
+    }
+  }
+  return ids;
+}
+
+// 將字串陣列中的物件/非字串轉為字串
+function toStringArray(arr) {
+  if (!Array.isArray(arr)) return [];
+  return arr.map(item => {
+    if (typeof item === 'string') return item;
+    if (item == null) return null;
+    if (typeof item === 'object') {
+      if (item.description) return item.description;
+      if (item.name) return item.name;
+      return JSON.stringify(item);
+    }
+    return String(item);
+  }).filter(Boolean);
+}
+
+// 從舊格式轉換成新系統格式
+function convertToNewFormat(old, source) {
+  const id = old.id || old.ID;
+
+  // description 處理
+  let desc = old.description || '';
+  if (typeof desc !== 'string') desc = String(desc);
+
+  // status 映射
+  const statusMap = {
+    'pending': 'backlog',
+    'in_progress': 'active',
+    'completed': 'completed',
+    'cancelled': 'cancel',
+    'blocked': 'blocked',
+    'done': 'completed',
+    'split': 'backlog'
+  };
+  const rawStatus = (old.status || 'completed').toLowerCase();
+  const status = statusMap[rawStatus] || rawStatus;
+
+  // role 映射
+  const role = old.role || old.agent_type || old.assigned_team || 'developer';
+
+  // created_at / completed_at
+  const createdAt = old.created_at || old.metadata?.created_at || '';
+  const completedAt = old.completed_at || old.metadata?.completed_at || '';
+  const createdBy = old.metadata?.created_by || old.created_by || 'Legacy Migration';
+
+  // estimated_hours
+  const estHours = old.estimated_hours != null ? old.estimated_hours : null;
+  const actHours = old.actual_hours != null ? old.actual_hours : null;
+
+  return {
+    id,
+    hash: randomUUID(),
+    title: old.title || '',
+    description: desc.trim(),
+    priority: old.priority || 'P2',
+    status,
+    role: typeof role === 'string' ? role.replace(/"/g, '') : 'developer',
+    tags: Array.isArray(old.tags) ? old.tags : [],
+    complexity: old.complexity || 'medium',
+    rigor: 'low',
+    estimated_hours: estHours,
+    actual_hours: actHours,
+    branch: old.branch || null,
+    dependencies: old.dependencies || [],
+    scope_paths: old.scope_paths || old.scope || [],
+    requirements: toStringArray(old.requirements),
+    acceptance_criteria: toStringArray(old.acceptance_criteria),
+    technical_notes: toStringArray(old.technical_notes),
+    feature_ids: old.feature_ids || [],
+    created_by: {
+      name: typeof createdBy === 'string' ? createdBy : (createdBy.name || 'Legacy'),
+      git_user: '',
+      timestamp: typeof createdAt === 'string' ? createdAt : ''
+    },
+    executed_by: null,
+    assigned_to: null,
+    metadata: {
+      migrated_from: source,
+      migrated_at: new Date().toISOString()
+    }
+  };
+}
+
+// YAML dump 設定（匹配新系統輸出風格）
+function dumpYaml(obj) {
+  return yaml.dump(obj, {
+    lineWidth: -1,
+    noRefs: true,
+    quotingType: "'",
+    forceQuotes: false
+  });
+}
+
+// 主程式
+function main() {
+  const execute = process.argv.includes('--execute');
+  const existingIds = getExistingIds();
+
+  console.log(`📋 Existing tasks in new system: ${existingIds.size}`);
+
+  // 收集所有舊系統任務
+  const legacyTasks = new Map(); // id -> { data, source }
+
+  // 1. 從 completed/ YAML 載入
+  for (const dir of [LEGACY_COMPLETED, LEGACY_TASKS]) {
+    if (!fs.existsSync(dir)) continue;
+    for (const file of fs.readdirSync(dir)) {
+      if (!file.endsWith('.yaml') && !file.endsWith('.md')) continue;
+      const match = file.match(/^(TASK_\d+)/);
+      if (!match) continue;
+      const taskId = match[1];
+      if (legacyTasks.has(taskId)) continue; // 不覆蓋
+
+      try {
+        const content = fs.readFileSync(path.join(dir, file), 'utf8');
+        // 跳過 .md 文件中沒有 YAML frontmatter 的
+        if (file.endsWith('.md')) {
+          if (!content.startsWith('---')) continue;
+          // 提取 frontmatter
+          const parts = content.split('---');
+          if (parts.length < 3) continue;
+          const data = yaml.load(parts[1]);
+          if (data && data.id) {
+            legacyTasks.set(taskId, { data, source: `dev/pipeline/completed/${file}` });
+          }
+        } else {
+          const data = yaml.load(content);
+          if (data && (data.id || data.ID)) {
+            legacyTasks.set(taskId, { data, source: `dev/pipeline/completed/${file}` });
+          }
+        }
+      } catch (e) {
+        console.warn(`  ⚠️  Parse error: ${file}: ${e.message}`);
+      }
+    }
+  }
+
+  // 2. 從 TASK_QUEUE.json 補充
+  if (fs.existsSync(LEGACY_QUEUE)) {
+    try {
+      const queue = JSON.parse(fs.readFileSync(LEGACY_QUEUE, 'utf8'));
+      for (const task of (queue.tasks || [])) {
+        if (!legacyTasks.has(task.id)) {
+          legacyTasks.set(task.id, { data: task, source: 'dev/pipeline/TASK_QUEUE.json' });
+        }
+      }
+    } catch (e) {
+      console.warn(`  ⚠️  TASK_QUEUE.json parse error: ${e.message}`);
+    }
+  }
+
+  // 找出缺失的
+  const missing = [];
+  for (const [id, info] of legacyTasks) {
+    if (!existingIds.has(id)) {
+      missing.push({ id, ...info });
+    }
+  }
+
+  // 按 ID 排序
+  missing.sort((a, b) => {
+    const na = parseInt(a.id.replace('TASK_', ''));
+    const nb = parseInt(b.id.replace('TASK_', ''));
+    return na - nb;
+  });
+
+  console.log(`🔍 Legacy tasks found: ${legacyTasks.size}`);
+  console.log(`❌ Missing from new system: ${missing.length}`);
+
+  if (missing.length === 0) {
+    console.log('✅ All tasks are synced!');
+    return;
+  }
+
+  console.log('');
+
+  // 確保 archived 目錄存在
+  if (execute && !fs.existsSync(NEW_ARCHIVED)) {
+    fs.mkdirSync(NEW_ARCHIVED, { recursive: true });
+  }
+
+  let created = 0;
+  for (const task of missing) {
+    const newTask = convertToNewFormat(task.data, task.source);
+    const filename = `${task.id}.yaml`;
+    const filepath = path.join(NEW_ARCHIVED, filename);
+
+    if (execute) {
+      fs.writeFileSync(filepath, dumpYaml(newTask), 'utf8');
+      console.log(`  ✅ ${task.id} ← ${task.source}`);
+      created++;
+    } else {
+      console.log(`  📝 ${task.id} ← ${task.source} (dry-run)`);
+    }
+  }
+
+  console.log('');
+  if (execute) {
+    console.log(`✅ Migrated ${created} tasks to .collaboration/tasks/archived/`);
+  } else {
+    console.log(`📋 ${missing.length} tasks would be migrated. Run with --execute to apply.`);
+  }
+}
+
+main();

package/core/.collaboration/core/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

package/core/.collaboration/core/task-2257-estimated-hours.test.js

@@ -0,0 +1,72 @@
+// TASK_2257 — --estimated-hours must not silently no-op on empty nor write NaN.
+// Isolated temp project root; never touches the real .kenaz/tasks.
+// Usage: node .collaboration/core/task-2257-estimated-hours.test.js
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const TASKAPI = path.join(__dirname, 'task-api.js');
+const SB = fs.mkdtempSync(path.join(os.tmpdir(), 't2257_'));
+for (const d of ['backlog', 'active', 'done', 'blocked', 'cancel']) fs.mkdirSync(path.join(SB, '.kenaz/tasks', d), { recursive: true });
+const env = { ...process.env }; delete env.CLAUDE_PROJECT_DIR;
+const api = (args) => spawnSync(process.execPath, [TASKAPI, '--project-path', SB, ...args], { encoding: 'utf8', env, windowsHide: true, cwd: SB });
+const cardText = (id) => {
+  for (const d of ['backlog', 'active']) {
+    const dir = path.join(SB, '.kenaz/tasks', d);
+    const f = fs.readdirSync(dir).find(n => n.startsWith(id + '_') || n === id + '.yaml');
+    if (f) return fs.readFileSync(path.join(dir, f), 'utf8');
+  }
+  return '';
+};
+const hoursLine = (id) => (cardText(id).match(/^estimated_hours:\s*(.*)$/m) || [])[1];
+let pass = 0, fail = 0;
+const check = (n, c, d) => { console.log((c ? 'PASS' : 'FAIL') + ' | ' + n + (c ? '' : ' | ' + d)); c ? pass++ : fail++; };
+
+const mk = (extra) => {
+  const r = api(['create', '--title', 't2257', '--description', 'd', '--scope-paths', 'zzz/a.js', '--requirements', 'r', '--acceptance-criteria', 'a', '--force', ...extra]);
+  const m = (r.stdout || '').match(/TASK_\d+/);
+  return { r, id: m && m[0] };
+};
+const argsFile = (obj) => { const p = path.join(SB, 'args_' + Math.random().toString(36).slice(2) + '.json'); fs.writeFileSync(p, JSON.stringify(obj)); return p; };
+const nBacklog = () => fs.readdirSync(path.join(SB, '.kenaz/tasks/backlog')).length;
+
+try {
+  const base = mk(['--estimated-hours', '3']);
+  check('S0 control: create with 3 stores 3', base.id && hoursLine(base.id) === '3', String(base.id) + ' ' + (base.id && hoursLine(base.id)) + base.r.stderr);
+  const id = base.id;
+
+  let r = api(['update', id, '--estimated-hours', '2.5']);
+  check('U1 control: update 2.5 -> 2.5', r.status === 0 && hoursLine(id) === '2.5', r.stderr + hoursLine(id));
+
+  r = api(['update', id, '--estimated-hours', 'abc']);
+  check('U2 update abc exits 1 and card unchanged', r.status === 1 && hoursLine(id) === '2.5', `status=${r.status} line=${hoursLine(id)}`);
+
+  r = api(['update', id, '--estimated-hours', '-1']);
+  check('U3 update -1 exits 1 and card unchanged', r.status === 1 && hoursLine(id) === '2.5', `status=${r.status} line=${hoursLine(id)}`);
+
+  r = api(['update', id, '--estimated-hours', '']);
+  check('U4 update empty clears (null), not silent no-op', r.status === 0 && /^(null|~|)$/.test(hoursLine(id) || ''), `status=${r.status} line=${hoursLine(id)} ${r.stderr}`);
+
+  api(['update', id, '--estimated-hours', '4']);
+  r = api(['update', id, '--args-file', argsFile({ estimatedHours: 'abc' })]);
+  check('F1 update args-file abc exits 1, card unchanged', r.status === 1 && hoursLine(id) === '4', `status=${r.status} line=${hoursLine(id)}`);
+  r = api(['update', id, '--args-file', argsFile({ estimated_hours: -2 })]);
+  check('F2 update args-file -2 exits 1, card unchanged', r.status === 1 && hoursLine(id) === '4', `status=${r.status} line=${hoursLine(id)}`);
+  r = api(['update', id, '--args-file', argsFile({ estimatedHours: 1.5 })]);
+  check('F3 control: update args-file 1.5 ok', r.status === 0 && hoursLine(id) === '1.5', `status=${r.status} line=${hoursLine(id)}`);
+
+  const before = nBacklog();
+  const c1 = mk(['--estimated-hours', 'abc']);
+  check('C1 create abc exits 1 and writes no card', c1.r.status === 1 && nBacklog() === before, `status=${c1.r.status}`);
+  const c2 = mk(['--estimated-hours', '-3']);
+  check('C2 create -3 exits 1', c2.r.status === 1, `status=${c2.r.status}`);
+  const c3 = mk(['--args-file', argsFile({ title: 'x', estimatedHours: 'abc' })]);
+  check('C3 create args-file abc exits 1', c3.r.status === 1, `status=${c3.r.status}`);
+  const c4 = mk(['--estimated-hours', '2.5']);
+  check('C4 control: create 2.5 stores 2.5', c4.id && hoursLine(c4.id) === '2.5', String(c4.id) + ' ' + (c4.id && hoursLine(c4.id)));
+} finally {
+  try { fs.rmSync(SB, { recursive: true, force: true }); } catch { /* best effort */ }
+}
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail ? 1 : 0);

package/core/.collaboration/core/task-2260-dir-layout-move.test.js

@@ -0,0 +1,60 @@
+// TASK_2260 — moveTask must move directory-layout cards (<status>/TASK_ID/TASK_ID.yaml) as a
+// unit and the residual sweep must remove dir-layout stale copies. Isolated temp tasks root.
+// Usage: node .collaboration/core/task-2260-dir-layout-move.test.js
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { TaskAPI, toYAML } = require('./task-api.js');
+
+const SB = fs.mkdtempSync(path.join(os.tmpdir(), 't2260_'));
+const tasksDir = path.join(SB, '.kenaz', 'tasks');
+for (const d of ['backlog', 'active', 'done', 'blocked', 'cancel', 'archived']) fs.mkdirSync(path.join(tasksDir, d), { recursive: true });
+let pass = 0, fail = 0;
+const check = (n, c, d) => { console.log((c ? 'PASS' : 'FAIL') + ' | ' + n + (c ? '' : ' | ' + d)); c ? pass++ : fail++; };
+const P = (...a) => path.join(tasksDir, ...a);
+const card = (id, status) => toYAML({ id, title: 't2260 ' + id, priority: 'P2', status });
+const dirCard = (status, id, extra) => {
+  fs.mkdirSync(P(status, id), { recursive: true });
+  fs.writeFileSync(P(status, id, id + '.yaml'), card(id, 'in_progress'));
+  fs.writeFileSync(P(status, id, 'attachment.txt'), 'keep me');
+  if (extra) extra();
+};
+
+(async () => {
+  const api = new TaskAPI({ tasksDir, projectPath: SB });
+  try {
+    // A: directory-layout card moves as a directory, with its sibling file
+    dirCard('active', 'TASK_9100');
+    await api.moveTask('TASK_9100', 'done');
+    check('A1 yaml lands in done/TASK_9100/', fs.existsSync(P('done', 'TASK_9100', 'TASK_9100.yaml')), 'missing');
+    check('A2 no flat done/TASK_9100.yaml', !fs.existsSync(P('done', 'TASK_9100.yaml')), 'flat copy created');
+    check('A3 sibling file moved with the card', fs.existsSync(P('done', 'TASK_9100', 'attachment.txt')), 'attachment missing');
+    check('A4 old active/TASK_9100 removed (no orphan)', !fs.existsSync(P('active', 'TASK_9100')), 'orphan dir remains');
+    const t = await api.getTask('TASK_9100');
+    check('A5 getTask reports done', t && t._status_dir === 'done' && t.status === 'completed', JSON.stringify(t && [t._status_dir, t.status]));
+
+    // B: stale dir-layout residual in another status dir is swept
+    dirCard('active', 'TASK_9101', () => {
+      fs.mkdirSync(P('blocked', 'TASK_9101'), { recursive: true });
+      fs.writeFileSync(P('blocked', 'TASK_9101', 'TASK_9101.yaml'), card('TASK_9101', 'blocked'));
+    });
+    await api.moveTask('TASK_9101', 'done');
+    check('B1 residual blocked/TASK_9101/ swept', !fs.existsSync(P('blocked', 'TASK_9101')), 'residual dir remains');
+
+    // C control: flat card unaffected
+    fs.writeFileSync(P('active', 'TASK_9102_x.yaml'), card('TASK_9102', 'in_progress'));
+    await api.moveTask('TASK_9102', 'done');
+    check('C1 control: flat card moves to done/TASK_9102_x.yaml', fs.existsSync(P('done', 'TASK_9102_x.yaml')) && !fs.existsSync(P('active', 'TASK_9102_x.yaml')), 'flat move broken');
+
+    // D control: same-status dir-layout move must not delete the card
+    dirCard('backlog', 'TASK_9103');
+    try { await api.moveTask('TASK_9103', 'backlog', null, { skipValidation: true }); } catch { /* may reject; only data loss matters */ }
+    check('D1 control: same-dir move keeps dir card intact', fs.existsSync(P('backlog', 'TASK_9103', 'TASK_9103.yaml')) && fs.existsSync(P('backlog', 'TASK_9103', 'attachment.txt')), 'card lost');
+  } catch (e) {
+    check('no exception', false, e && e.stack);
+  } finally {
+    try { fs.rmSync(SB, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+  console.log(`\n${pass} passed, ${fail} failed`);
+  process.exit(fail ? 1 : 0);
+})();

package/core/.collaboration/core/task-2264-single-after-capture.test.js

@@ -0,0 +1,61 @@
+// TASK_2264 — completeTask must schedule exactly ONE 'after' health capture.
+// moveTask used to schedule a detached 'after' capture on every ->done move even when
+// completeTask's own postComplete was about to measure the same snapshot.
+// Counting seam: child_process.spawn is patched (task-api requires it at call time) and
+// calls whose inline script carries phase "after" are counted. Isolated temp project.
+// Usage: node .collaboration/core/task-2264-single-after-capture.test.js
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const cp = require('child_process');
+const { TaskAPI, toYAML } = require('./task-api.js');
+
+const SB = fs.mkdtempSync(path.join(os.tmpdir(), 't2264_'));
+const tasksDir = path.join(SB, '.kenaz', 'tasks');
+for (const d of ['backlog', 'active', 'done', 'blocked', 'cancel', 'archived']) fs.mkdirSync(path.join(tasksDir, d), { recursive: true });
+delete process.env.FORMATION_SCHEDULER; delete process.env.FORMATION_HEADLESS;
+
+let pass = 0, fail = 0;
+const check = (n, c, d) => { console.log((c ? 'PASS' : 'FAIL') + ' | ' + n + (c ? '' : ' | ' + d)); c ? pass++ : fail++; };
+
+let phases = [];
+const realSpawn = cp.spawn;
+cp.spawn = function (cmd, argv, opts) {
+  const script = Array.isArray(argv) ? argv.find(a => typeof a === 'string' && a.includes('const CFG')) : null;
+  if (script) {
+    const m = script.match(/"phase":"(before|after)"/);
+    phases.push(m ? m[1] : '?');
+    return { unref() {}, on() {} };
+  }
+  return realSpawn.apply(this, arguments);
+};
+
+const mkActive = (id) => fs.writeFileSync(path.join(tasksDir, 'active', id + '_t.yaml'),
+  toYAML({ id, title: 't2264 ' + id, priority: 'P2', status: 'in_progress' }));
+
+(async () => {
+  const api = new TaskAPI({ tasksDir, projectPath: SB });
+  try {
+    // A: complete with post-complete running in-process (dry run, no git/archive) -> post-complete owns 'after'
+    mkActive('TASK_9001'); phases = [];
+    await api.completeTask('TASK_9001', { dryRun: true, skipGit: true, skipArchive: true });
+    check('A complete w/ post-complete: moveTask schedules NO after capture', phases.filter(p => p === 'after').length === 0, JSON.stringify(phases));
+
+    // B control: post-complete skipped -> nobody else measures, moveTask must still capture exactly once
+    mkActive('TASK_9002'); phases = [];
+    await api.completeTask('TASK_9002', { skipPostComplete: true });
+    check('B control: complete w/ skipPostComplete schedules exactly 1 after capture', phases.filter(p => p === 'after').length === 1, JSON.stringify(phases));
+
+    // C control: bare move done (no post-complete) keeps its single capture
+    mkActive('TASK_9003'); phases = [];
+    await api.moveTask('TASK_9003', 'done');
+    check('C control: bare move done schedules exactly 1 after capture', phases.filter(p => p === 'after').length === 1, JSON.stringify(phases));
+  } catch (e) {
+    check('no exception', false, e && e.stack);
+  } finally {
+    cp.spawn = realSpawn;
+    try { fs.rmSync(SB, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+  console.log(`\n${pass} passed, ${fail} failed`);
+  process.exit(fail ? 1 : 0);
+})();

package/core/.collaboration/core/task-2288-followups.test.js

@@ -0,0 +1,121 @@
+// TASK_2288 — follow-ups from TASK_2257/2264:
+//  (1) complete --actual-hours must validate like parseEstimatedHours (NaN/negative exit 1 before writes)
+//  (2) 0 hours is preserved as 0 (create + task-api-json), not coerced to null
+//  (3) exactly one 'after' health capture per completion on headless/scheduler paths
+//      (post-complete, run by the caller, is the single winner; moveTask must not also capture)
+// Isolated temp project roots; never touches real .kenaz/tasks.
+// Usage: node .collaboration/core/task-2288-followups.test.js
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const cp = require('child_process');
+
+const TASKAPI = path.join(__dirname, 'task-api.js');
+const TASKJSON = path.join(__dirname, 'task-api-json.js');
+const { TaskAPI, toYAML } = require('./task-api.js');
+
+const SB = fs.mkdtempSync(path.join(os.tmpdir(), 't2288_'));
+const tasksDir = path.join(SB, '.kenaz', 'tasks');
+for (const d of ['backlog', 'active', 'done', 'blocked', 'cancel', 'archived']) fs.mkdirSync(path.join(tasksDir, d), { recursive: true });
+const cleanEnv = () => { const e = { ...process.env }; delete e.CLAUDE_PROJECT_DIR; delete e.FORMATION_SCHEDULER; delete e.FORMATION_HEADLESS; return e; };
+const cli = (args) => spawnSync(process.execPath, [TASKAPI, '--project-path', SB, ...args], { encoding: 'utf8', env: cleanEnv(), windowsHide: true, cwd: SB });
+delete process.env.FORMATION_SCHEDULER; delete process.env.FORMATION_HEADLESS;
+
+let pass = 0, fail = 0;
+const check = (n, c, d) => { console.log((c ? 'PASS' : 'FAIL') + ' | ' + n + (c ? '' : ' | ' + d)); c ? pass++ : fail++; };
+
+const findCard = (id) => {
+  for (const d of ['backlog', 'active', 'done']) {
+    const dir = path.join(tasksDir, d);
+    const f = fs.readdirSync(dir).find(n => n.startsWith(id + '_') || n === id + '.yaml');
+    if (f) return { dir: d, text: fs.readFileSync(path.join(dir, f), 'utf8') };
+  }
+  return { dir: null, text: '' };
+};
+const field = (id, k) => (findCard(id).text.match(new RegExp('^' + k + ':\\s*(.*)$', 'm')) || [])[1];
+const mkActive = (id) => fs.writeFileSync(path.join(tasksDir, 'active', id + '_t.yaml'),
+  toYAML({ id, title: 't2288 ' + id, priority: 'P2', status: 'in_progress' }));
+
+// --- spawn counting seam (same as TASK_2264) ---
+let phases = [];
+const realSpawn = cp.spawn;
+cp.spawn = function (cmd, argv, opts) {
+  const script = Array.isArray(argv) ? argv.find(a => typeof a === 'string' && a.includes('const CFG')) : null;
+  if (script) {
+    const m = script.match(/"phase":"(before|after)"/);
+    phases.push(m ? m[1] : '?');
+    return { unref() {}, on() {} };
+  }
+  return realSpawn.apply(this, arguments);
+};
+const afters = () => phases.filter(p => p === 'after').length;
+
+(async () => {
+  try {
+    // ---- (1) actual-hours validation (CLI, subprocess so spawn patch is irrelevant) ----
+    mkActive('TASK_9101'); mkActive('TASK_9103'); mkActive('TASK_9104'); mkActive('TASK_9105');
+    let r = cli(['complete', 'TASK_9101', '--actual-hours', 'abc', '--skip-post-complete']);
+    check('H1 complete --actual-hours abc exits 1 and card stays active', r.status === 1 && findCard('TASK_9101').dir === 'active', `status=${r.status} dir=${findCard('TASK_9101').dir}`);
+    r = cli(['complete', 'TASK_9103', '--actual-hours', '-2', '--skip-post-complete']);
+    check('H2 complete --actual-hours -2 exits 1 and card stays active', r.status === 1 && findCard('TASK_9103').dir === 'active', `status=${r.status} dir=${findCard('TASK_9103').dir}`);
+    r = cli(['complete', 'TASK_9104', '--actual-hours']);
+    check('H3 complete --actual-hours with missing value exits 1 and card stays active', r.status === 1 && findCard('TASK_9104').dir === 'active', `status=${r.status} dir=${findCard('TASK_9104').dir}`);
+    r = cli(['complete', 'TASK_9101', '--actual-hours', '2.5', '--skip-post-complete']);
+    check('H4 control: --actual-hours 2.5 completes and stores 2.5', r.status === 0 && findCard('TASK_9101').dir === 'done' && field('TASK_9101', 'actual_hours') === '2.5', `status=${r.status} ${r.stderr} line=${field('TASK_9101', 'actual_hours')}`);
+    mkActive('TASK_9102');
+    r = cli(['complete', 'TASK_9102', '--actual-hours', '0', '--skip-post-complete']);
+    check('H5 --actual-hours 0 stores 0 (not null)', r.status === 0 && field('TASK_9102', 'actual_hours') === '0', `status=${r.status} line=${field('TASK_9102', 'actual_hours')}`);
+
+    // ---- (2) 0 hours preserved on create + json ----
+    const mk = (h) => {
+      const c = cli(['create', '--title', 't2288', '--description', 'd', '--scope-paths', 'zzz/a.js', '--requirements', 'r', '--acceptance-criteria', 'a', '--force', '--estimated-hours', h]);
+      const m = (c.stdout || '').match(/TASK_\d+/);
+      return { c, id: m && m[0] };
+    };
+    const z = mk('0');
+    check('Z1 create --estimated-hours 0 stores 0 (not null)', z.id && field(z.id, 'estimated_hours') === '0', `${z.id} line=${z.id && field(z.id, 'estimated_hours')} ${z.c.stderr}`);
+    const three = mk('3');
+    check('Z2 control: create 3 stores 3', three.id && field(three.id, 'estimated_hours') === '3', `${three.id} line=${three.id && field(three.id, 'estimated_hours')}`);
+    if (z.id) {
+      const j = spawnSync(process.execPath, [TASKJSON, '--project-path', SB, '--task', z.id], { encoding: 'utf8', env: cleanEnv(), windowsHide: true, cwd: SB });
+      let parsed = null; try { parsed = JSON.parse(j.stdout); } catch { /* reported below */ }
+      // card forced to 0 on disk so the json check does not depend on Z1
+      const f = fs.readdirSync(path.join(tasksDir, 'backlog')).find(n => n.startsWith(z.id + '_'));
+      const p = path.join(tasksDir, 'backlog', f);
+      const orig = fs.readFileSync(p, 'utf8').replace(/^estimated_hours:.*\r?\n/m, '').replace(/^actual_hours:.*\r?\n/m, '');
+      fs.writeFileSync(p, orig.replace(/\s*$/, '\n') + 'estimated_hours: 0\nactual_hours: 0\n');
+      const j2 = spawnSync(process.execPath, [TASKJSON, '--project-path', SB, '--task', z.id], { encoding: 'utf8', env: cleanEnv(), windowsHide: true, cwd: SB });
+      let p2 = null; try { p2 = JSON.parse(j2.stdout); } catch { /* reported below */ }
+      check('Z3 task-api-json emits estimated_hours 0 as 0', p2 && p2.estimated_hours === 0, JSON.stringify(p2 && p2.estimated_hours) + j2.stderr);
+      check('Z4 task-api-json emits actual_hours 0 as 0', p2 && p2.actual_hours === 0, JSON.stringify(p2 && p2.actual_hours));
+    }
+
+    // ---- (3) single 'after' capture ----
+    const api = new TaskAPI({ tasksDir, projectPath: SB });
+    for (const envName of ['FORMATION_HEADLESS', 'FORMATION_SCHEDULER']) {
+      const id = envName === 'FORMATION_HEADLESS' ? 'TASK_9111' : 'TASK_9112';
+      mkActive(id); phases = [];
+      process.env[envName] = '1';
+      try { await api.completeTask(id, {}); } finally { delete process.env[envName]; }
+      check(`R1 ${envName}: caller's post-complete owns 'after'; moveTask schedules none`, afters() === 0, JSON.stringify(phases));
+    }
+    mkActive('TASK_9113'); phases = [];
+    process.env.FORMATION_HEADLESS = '1';
+    try { await api.completeTask('TASK_9113', { skipPostComplete: true }); } finally { delete process.env.FORMATION_HEADLESS; }
+    check('R2 control: headless + skipPostComplete (nobody else measures) keeps exactly 1 capture', afters() === 1, JSON.stringify(phases));
+    mkActive('TASK_9114'); phases = [];
+    await api.moveTask('TASK_9114', 'done');
+    check('R3 control: bare move done captures exactly once', afters() === 1, JSON.stringify(phases));
+    mkActive('TASK_9115'); phases = [];
+    await api.completeTask('TASK_9115', { dryRun: true, skipGit: true, skipArchive: true });
+    check('R4 control: in-process complete (TASK_2264) still schedules none', afters() === 0, JSON.stringify(phases));
+  } catch (e) {
+    check('no exception', false, e && e.stack);
+  } finally {
+    cp.spawn = realSpawn;
+    try { fs.rmSync(SB, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+  console.log(`\n${pass} passed, ${fail} failed`);
+  process.exit(fail ? 1 : 0);
+})();