kenaz 0.3.2 → 0.3.5

package/core/.formation/tools/headless-v2.js

@@ -1,659 +0,0 @@
-#!/usr/bin/env node
-/**
- * Formation Headless V2 Launcher
- *
- * 雙軸架構：--base（行為模式）+ --role（角色專業）
- *
- * 核心概念：
- *   base = unit/{do,plan,think}.yaml → 決定「做什麼」（workflow、output format）
- *   role = 任意 .formation/*.yaml   → 決定「用什麼角色」（identity、strengths）
- *   prompt = base + role context + task
- *
- * V1 的問題：loadSkill('unit', 'developer') → 找不到 .formation/unit/developer.yaml
- * V2 的解法：loadSkill('unit', 'do') + loadRole('legacy/developer') → 合成 prompt
- *
- * Usage:
- *   node .formation/tools/headless-v2.js --base=do --task=TASK_301
- *   node .formation/tools/headless-v2.js --base=do --role=developer --task=TASK_301
- *   node .formation/tools/headless-v2.js --base=think --role=strategy --task=TASK_302
- *   node .formation/tools/headless-v2.js --base=plan --role=designer --task=TASK_303
- *   node .formation/tools/headless-v2.js --base=do --role=legacy/developer --task=TASK_304
- *   node .formation/tools/headless-v2.js --base=do --role=solo/strategy --task=TASK_305
- */
-
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
-const { loadSkill, loadTask } = require('./loader');
-const {
-  buildPrompt, HEADLESS_PREFIX
-} = require('./prompt');
-const { runHeadless } = require('./runner');
-const { generateSessionId, getLogDir, ROOT, COLLABORATION_API, ensureGitReady,
-  createWorktree, removeWorktree, ensureWorktreeDirIgnored } = require('./utils');
-const { postComplete } = require('./post-complete');
-
-let canary;
-try { canary = require('../../.specialist/tools/canary'); } catch { canary = null; }
-
-// ─────────────────────────────────────────
-// Role Map — 從 role-map.yaml 載入對照表
-// ─────────────────────────────────────────
-
-const ROLE_MAP_PATH = path.join(ROOT, '.formation', 'role-map.yaml');
-const VALID_BASES = ['do', 'plan', 'think'];
-
-function loadRoleMap() {
-  const yaml = (() => {
-    try { return require('js-yaml'); }
-    catch { return require('../../.vendor/js-yaml.cjs'); }
-  })();
-
-  if (!fs.existsSync(ROLE_MAP_PATH)) {
-    console.error(`❌ role-map.yaml not found: ${ROLE_MAP_PATH}`);
-    process.exit(1);
-  }
-  return yaml.load(fs.readFileSync(ROLE_MAP_PATH, 'utf-8'));
-}
-
-/**
- * 解析 --role 參數，回傳 skill YAML 的完整內容
- *
- * 支援格式：
- *   --role=developer           → 查 role-map.yaml → legacy/developer.yaml
- *   --role=legacy/developer    → 直接載入 .formation/legacy/developer.yaml
- *   --role=solo/strategy       → 直接載入 .formation/solo/strategy.yaml
- *   --role=path/to/custom.yaml → 直接載入自訂 YAML
- */
-function loadRole(roleName) {
-  const yaml = (() => {
-    try { return require('js-yaml'); }
-    catch { return require('../../.vendor/js-yaml.cjs'); }
-  })();
-
-  // Case 1: 直接指定路徑（含 / 或 \）
-  if (roleName.includes('/') || roleName.includes('\\')) {
-    // 相對於 .formation/ 的路徑
-    let rolePath = path.join(ROOT, '.formation', roleName);
-    if (!rolePath.endsWith('.yaml')) rolePath += '.yaml';
-
-    if (!fs.existsSync(rolePath)) {
-      console.error(`❌ Role YAML not found: ${rolePath}`);
-      process.exit(1);
-    }
-    return yaml.load(fs.readFileSync(rolePath, 'utf-8'));
-  }
-
-  // Case 2: 短名稱 → 從 role-map.yaml 查找
-  const roleMap = loadRoleMap();
-  const roleEntry = roleMap.roles?.[roleName];
-
-  if (!roleEntry) {
-    const available = Object.keys(roleMap.roles || {}).join(', ');
-    console.error(`❌ Unknown role: "${roleName}"`);
-    console.error(`   Available roles: ${available}`);
-    process.exit(1);
-  }
-
-  const rolePath = path.join(ROOT, '.formation', roleEntry.skill_path);
-  if (!fs.existsSync(rolePath)) {
-    console.error(`❌ Role YAML not found: ${rolePath} (mapped from role "${roleName}")`);
-    process.exit(1);
-  }
-  return yaml.load(fs.readFileSync(rolePath, 'utf-8'));
-}
-
-// ─────────────────────────────────────────
-// Prompt 合成：base + role
-// ─────────────────────────────────────────
-
-/**
- * 將 base skill 和 role 合成為最終 prompt
- *
- * 策略：
- *   1. 用 base（do/plan/think）的 buildPrompt 產生基礎 prompt
- *   2. 在 Role section 後注入 role 的 identity 和 strengths
- *   3. 保留 base 的 workflow 和 output format
- */
-function buildMergedPrompt(baseDef, roleDef, taskInput, taskData, options = {}) {
-  // 合成 skillDef：以 base 為主體，注入 role 的 identity
-  const mergedDef = JSON.parse(JSON.stringify(baseDef));
-
-  if (roleDef) {
-    // 保留 base 的 workflow/output，但替換 role identity
-    const baseIdentity = mergedDef.role?.identity || '';
-    const roleIdentity = roleDef.role?.identity || '';
-    const rolePriority = roleDef.role?.priority || '';
-
-    mergedDef.role = {
-      identity: `${roleIdentity}\n\n[Base Mode: ${baseDef.name}] ${baseIdentity}`,
-      priority: rolePriority || mergedDef.role?.priority || '',
-    };
-
-    // 合併 behavior：role 的 behavior 在前（角色特性），base 的在後（行為模式）
-    const roleBehavior = roleDef.behavior || [];
-    const baseBehavior = baseDef.behavior || [];
-    mergedDef.behavior = [...roleBehavior, ...baseBehavior];
-
-    // 注入 role 的 perspectives（如 solo/strategy 的六視角）
-    if (roleDef.perspectives) {
-      mergedDef.perspectives = roleDef.perspectives;
-    }
-
-    // 注入 role 的 analysis_principles（如 solo/diagnosis）
-    if (roleDef.analysis_principles) {
-      mergedDef.analysis_principles = roleDef.analysis_principles;
-    }
-  }
-
-  return buildPrompt(mergedDef, taskInput, taskData, options);
-}
-
-// ─────────────────────────────────────────
-// 任務相關（複用 headless.js 邏輯）
-// ─────────────────────────────────────────
-
-function findNextTask(projectPath) {
-  const pathMod = require('path');
-  const yamlLib = (() => { try { return require('js-yaml'); } catch { return require('../../.vendor/js-yaml.cjs'); } })();
-
-  const coreRoot = pathMod.resolve(__dirname, '../..');
-  const backlogDirs = [];
-  if (projectPath && projectPath !== coreRoot) {
-    backlogDirs.push(pathMod.join(projectPath, '.kenaz', 'tasks', 'backlog'));
-    backlogDirs.push(pathMod.join(projectPath, '.collaboration', 'tasks', 'backlog'));
-  }
-  if (!projectPath || projectPath === coreRoot) {
-    backlogDirs.push(pathMod.join(coreRoot, '.collaboration', 'tasks', 'backlog'));
-  }
-
-  let backlogDir = null;
-  for (const dir of backlogDirs) {
-    if (fs.existsSync(dir)) {
-      const files = fs.readdirSync(dir).filter(f => f.endsWith('.yaml'));
-      if (files.length > 0) { backlogDir = dir; break; }
-    }
-  }
-  if (!backlogDir) return null;
-
-  const files = fs.readdirSync(backlogDir).filter(f => f.endsWith('.yaml'));
-  if (files.length === 0) return null;
-
-  const taskRoot = pathMod.resolve(backlogDir, '..');
-  const doneDir = pathMod.join(taskRoot, 'done');
-  const priorityOrder = { P0: 0, P1: 1, P2: 2, P3: 3 };
-  const tasks = [];
-
-  for (const file of files) {
-    try {
-      const content = fs.readFileSync(pathMod.join(backlogDir, file), 'utf-8');
-      const data = yamlLib.load(content);
-      if (!data || !data.id) continue;
-      const deps = Array.isArray(data.dependencies) ? data.dependencies : (data.dependencies ? [data.dependencies] : []); // TASK_1771
-      if (deps.length > 0) {
-        const archivedDir = pathMod.join(taskRoot, 'archived');
-        const hasPendingDep = deps.some(dep => {
-          const doneFiles = fs.existsSync(doneDir) ? fs.readdirSync(doneDir) : [];
-          const archivedFiles = fs.existsSync(archivedDir) ? fs.readdirSync(archivedDir) : [];
-          return !doneFiles.some(f => f.startsWith(dep)) && !archivedFiles.some(f => f.startsWith(dep));
-        });
-        if (hasPendingDep) continue;
-      }
-      const prio = priorityOrder[data.priority] ?? 99;
-      const idNum = parseInt((data.id.match(/\d+/) || [0])[0], 10);
-      tasks.push({ id: data.id, priority: prio, idNum, title: data.title });
-    } catch { /* skip */ }
-  }
-  if (tasks.length === 0) return null;
-  tasks.sort((a, b) => a.priority - b.priority || a.idNum - b.idNum);
-  return tasks[0];
-}
-
-function checkTaskDependencies(taskData, projectPath) {
-  let deps = [];
-  try {
-    const parsed = JSON.parse(taskData);
-    deps = parsed.dependencies || [];
-  } catch {
-    const match = (taskData || '').match(/^dependencies:\s*\n((?:\s+-\s+\S+\n?)+)/m);
-    if (match) {
-      deps = match[1].split('\n').map(l => l.trim().replace(/^-\s*/, '')).filter(Boolean);
-    }
-  }
-  if (deps.length === 0) return { blocked: false, unmet: [] };
-
-  const completedIds = new Set();
-  const blockedIds = new Set();
-  const scanDir = (dir, bucket) => {
-    if (!dir || !fs.existsSync(dir)) return;
-    try {
-      for (const f of fs.readdirSync(dir)) {
-        if (f.startsWith('TASK_')) bucket.add(f.split('_').slice(0, 2).join('_'));
-      }
-    } catch { /* ignore */ }
-  };
-
-  const projectRoot = projectPath || ROOT;
-  scanDir(path.join(projectRoot, '.kenaz', 'tasks', 'done'), completedIds);
-  scanDir(path.join(projectRoot, '.kenaz', 'tasks', 'archived'), completedIds);
-  scanDir(path.join(projectRoot, '.kenaz', 'tasks', 'blocked'), blockedIds);
-  scanDir(path.join(projectRoot, '.collaboration', 'tasks', 'done'), completedIds);
-  scanDir(path.join(projectRoot, '.collaboration', 'tasks', 'archived'), completedIds);
-  scanDir(path.join(projectRoot, '.collaboration', 'tasks', 'blocked'), blockedIds);
-  scanDir(path.join(projectRoot, 'dev', 'pipeline', 'completed'), completedIds);
-
-  const blockedDeps = deps.filter(dep => {
-    const taskId = dep.match(/TASK_\d+/)?.[0];
-    if (!taskId) return false;
-    return blockedIds.has(taskId);
-  });
-  const unmet = deps.filter(dep => {
-    const taskId = dep.match(/TASK_\d+/)?.[0];
-    if (!taskId) return false;
-    return !completedIds.has(taskId);
-  });
-  return { blocked: unmet.length > 0, unmet, blockedDeps };
-}
-
-function ensureTaskComplete(taskId, projectPath) {
-  if (!taskId || !taskId.startsWith('TASK_')) return;
-  try {
-    const ppArg = projectPath ? ` --project-path "${projectPath}"` : '';
-    const info = execSync(
-      `node "${COLLABORATION_API}"${ppArg} get ${taskId}`,
-      { encoding: 'utf-8', timeout: 10000, windowsHide: true }
-    );
-    if (info.includes('"status":"done"') || info.includes('status: done')) return;
-    execSync(
-      `node "${COLLABORATION_API}"${ppArg} complete ${taskId}`,
-      { encoding: 'utf-8', timeout: 10000, windowsHide: true }
-    );
-  } catch { /* ignore */ }
-}
-
-// ─────────────────────────────────────────
-// Active dispatch registry（複用 headless.js 格式）
-// ─────────────────────────────────────────
-
-const ACTIVE_DISPATCH_FILE = path.join(ROOT, '.formation', '.active-dispatches.json');
-
-function readActiveDispatches() {
-  try {
-    if (fs.existsSync(ACTIVE_DISPATCH_FILE)) {
-      return JSON.parse(fs.readFileSync(ACTIVE_DISPATCH_FILE, 'utf-8'));
-    }
-  } catch { /* corrupted file */ }
-  return [];
-}
-
-function writeActiveDispatches(list) {
-  try {
-    fs.writeFileSync(ACTIVE_DISPATCH_FILE, JSON.stringify(list, null, 2));
-  } catch { /* ignore */ }
-}
-
-function registerDispatch({ sessionId, logPath, taskId, formation, projectPath: pp }) {
-  const list = readActiveDispatches();
-  const nextEntry = {
-    sessionId,
-    logPath,
-    taskId,
-    formation,
-    startedAt: new Date().toISOString(),
-    projectPath: pp || null,
-  };
-  const existingIndex = list.findIndex(d => d.sessionId === sessionId);
-  if (existingIndex >= 0) {
-    const mergedEntry = {
-      ...list[existingIndex],
-      startedAt: list[existingIndex].startedAt || nextEntry.startedAt,
-    };
-    for (const [key, value] of Object.entries(nextEntry)) {
-      if (key === 'startedAt') continue;
-      if (value !== null && value !== undefined) {
-        mergedEntry[key] = value;
-      }
-    }
-    list[existingIndex] = mergedEntry;
-  } else {
-    list.push(nextEntry);
-  }
-  writeActiveDispatches(list);
-}
-
-function unregisterDispatch(sessionId) {
-  const list = readActiveDispatches().filter(d => d.sessionId !== sessionId);
-  if (list.length === 0) {
-    try { fs.unlinkSync(ACTIVE_DISPATCH_FILE); } catch { /* ignore */ }
-  } else {
-    writeActiveDispatches(list);
-  }
-}
-
-function syncCommit(taskId, projectPath) {
-  try {
-    const commitSync = require('./commit-sync');
-    if (commitSync && typeof commitSync.sync === 'function') {
-      commitSync.sync({ taskId, projectPath });
-    }
-  } catch { /* commit-sync not available */ }
-}
-
-function broadcastStatusSync(projectPath, status) {
-  try {
-    const { broadcastSync } = require('./utils');
-    if (broadcastSync) broadcastSync(projectPath, status);
-  } catch { /* ignore */ }
-}
-
-function recoverStaleTasks(projectPath) {
-  try {
-    const { recoverStale } = require('./task-recovery');
-    if (recoverStale) recoverStale(projectPath);
-  } catch { /* ignore */ }
-}
-
-// ─────────────────────────────────────────
-// 主調度
-// ─────────────────────────────────────────
-
-function launch(options) {
-  const {
-    base = 'do',
-    role = null,
-    task,
-    dryRun = false,
-    projectPath = null,
-    skipPostComplete = false,
-    skipTests = false,
-    force = false,
-  } = options;
-
-  // Validate base
-  if (!VALID_BASES.includes(base)) {
-    console.error(`❌ Invalid --base: "${base}". Must be one of: ${VALID_BASES.join(', ')}`);
-    process.exit(1);
-  }
-
-  const sessionId = generateSessionId();
-
-  // 0. Cleanup
-  try {
-    const { cleanOrphanedClaude } = require('../../.specialist/tools/session');
-    const orphanResult = cleanOrphanedClaude();
-    if (orphanResult.killed > 0) {
-      console.log(`🧹 Cleaned ${orphanResult.killed} orphaned claude.exe process(es)`);
-    }
-  } catch { /* session.js not available */ }
-  recoverStaleTasks(projectPath);
-
-  // 0.1 Parallel dispatch guard
-  const activeDispatches = readActiveDispatches();
-  const sameProject = activeDispatches.filter(d =>
-    (d.projectPath || null) === (projectPath || null)
-  );
-  if (sameProject.length > 0) {
-    console.log(`⏳ Waiting for ${sameProject.length} active dispatch(es) on same project...`);
-    const PARALLEL_WAIT_TIMEOUT_MS = 600000;
-    const PARALLEL_POLL_MS = 5000;
-    const deadline = Date.now() + PARALLEL_WAIT_TIMEOUT_MS;
-    while (Date.now() < deadline) {
-      const current = readActiveDispatches();
-      const still = current.filter(d => (d.projectPath || null) === (projectPath || null));
-      if (still.length === 0) { console.log('   ✅ Previous dispatches completed.'); break; }
-      const wait = Date.now() + PARALLEL_POLL_MS;
-      while (Date.now() < wait) { /* busy wait */ }
-    }
-    const remaining = readActiveDispatches().filter(d => (d.projectPath || null) === (projectPath || null));
-    if (remaining.length > 0) {
-      console.log(`   ⚠️  Timed out. Clearing ${remaining.length} stale dispatch(es).`);
-      writeActiveDispatches(readActiveDispatches().filter(d => (d.projectPath || null) !== (projectPath || null)));
-    }
-  }
-
-  // 0.2 Auto-select task
-  let resolvedTask = task;
-  if (!resolvedTask) {
-    const nextTask = findNextTask(projectPath);
-    if (!nextTask) {
-      console.log('✅ No pending tasks found in backlog. Nothing to do.');
-      if (projectPath) console.log(`   (searched in: ${projectPath})`);
-      process.exit(0);
-    }
-    resolvedTask = nextTask.id;
-    console.log(`🔍 Auto-selected: [${nextTask.id}] ${nextTask.title} (${['P0','P1','P2','P3'][nextTask.priority] || 'P?'})\n`);
-  }
-
-  // 1. 載入 base skill
-  const baseDef = loadSkill('unit', base);
-  const loadOpts = projectPath ? { projectPath } : undefined;
-  const taskData = resolvedTask && resolvedTask.startsWith('TASK_') ? loadTask(resolvedTask, loadOpts) : null;
-  const taskInput = resolvedTask || '';
-
-  // 1.1 載入 role（如有指定）
-  const roleDef = role ? loadRole(role) : null;
-
-  // 1.2 依賴預檢
-  if (taskData) {
-    const depCheck = checkTaskDependencies(taskData, projectPath);
-    if (depCheck.blocked) {
-      console.error(`❌ Dispatch blocked: ${taskInput} has unmet dependencies`);
-      for (const dep of depCheck.unmet) {
-        if (depCheck.blockedDeps && depCheck.blockedDeps.includes(dep)) {
-          console.error(`   ⛔ ${dep} — blocked`);
-        } else {
-          console.error(`   ⛔ ${dep} — not in done/completed`);
-        }
-      }
-      if (!force) {
-        console.error(`   → Complete the dependencies first, or use --force to override`);
-        process.exitCode = 1;
-        return null;
-      }
-      console.warn(`   ⚠️  --force: dispatching despite unmet dependencies`);
-    }
-  }
-
-  // 1.5 Worktree isolation — create an isolated git worktree for real TASK_xxx dispatches
-  // This closes the no-lock gap: headless-v2 previously had neither a dispatch-lock nor a worktree.
-  const isRealTask = resolvedTask && /^TASK_\d+$/i.test(resolvedTask);
-  let _worktreePath = null;
-
-  if (isRealTask) {
-    const projectRoot = projectPath || ROOT;
-    const worktreeName = `task_${resolvedTask.toLowerCase()}`;
-    const absoluteWorktreePath = require('path').join(projectRoot, '.formation', 'worktrees', worktreeName);
-
-    ensureWorktreeDirIgnored(projectRoot);
-
-    const branchName = `task/${resolvedTask.toLowerCase()}`;
-    try {
-      createWorktree(projectRoot, absoluteWorktreePath, branchName);
-      _worktreePath = absoluteWorktreePath;
-      console.log(`   🌿 V2 worktree: .formation/worktrees/${worktreeName}`);
-
-      // Cleanup on exit
-      const releaseWorktree = () => {
-        try { removeWorktree(projectRoot, absoluteWorktreePath); } catch {}
-      };
-      process.on('exit', releaseWorktree);
-      process.on('SIGTERM', () => { releaseWorktree(); process.exit(1); });
-      process.on('SIGINT',  () => { releaseWorktree(); process.exit(1); });
-    } catch (err) {
-      console.warn(`⚠️  Worktree creation failed: ${err.message}`);
-      console.warn(`   Proceeding without worktree isolation.`);
-    }
-  }
-
-  // 2. 合成 prompt
-  const promptOpts = {};
-  if (projectPath) promptOpts.projectPath = projectPath;
-  if (_worktreePath) promptOpts.worktreePath = _worktreePath;
-  const rawPrompt = buildMergedPrompt(baseDef, roleDef, taskInput, taskData, promptOpts);
-
-  // 2.1 Parse scope paths for canary
-  let taskScopePaths = [];
-  if (taskData) {
-    try {
-      const parsed = JSON.parse(taskData);
-      taskScopePaths = parsed.scope_paths || [];
-    } catch { /* raw YAML */ }
-  }
-
-  // 3. Banner
-  const roleLabel = role ? ` + ${role}` : '';
-  console.log(`⚔️  Formation Headless V2 Launch`);
-  console.log(`   Base: ${base}${roleLabel}`);
-  console.log(`   Task: ${resolvedTask || '(inline)'}`);
-  console.log(`   Session: ${sessionId}`);
-  if (projectPath) console.log(`   Project: ${projectPath}`);
-  console.log('');
-
-  if (dryRun) {
-    console.log('--- DRY RUN: Merged Prompt ---');
-    console.log(rawPrompt);
-    console.log('--- END ---');
-    console.log(`\nPrompt length: ${rawPrompt.length.toLocaleString()} chars`);
-    if (roleDef) {
-      console.log(`Base: unit/${base}.yaml`);
-      console.log(`Role: ${role} → ${roleDef.name || 'unknown'}`);
-    }
-    return;
-  }
-
-  // 4. Launch
-  let finalPrompt = HEADLESS_PREFIX + rawPrompt;
-  if (canary) {
-    try {
-      const { block } = canary.generate({
-        session: sessionId,
-        specialist: 'unit-v2',
-        task: resolvedTask || 'none',
-        scope: taskScopePaths.join(','),
-      }, projectPath);
-      finalPrompt = block + '\n\n' + finalPrompt;
-    } catch (err) {
-      console.warn(`⚠️  Canary injection skipped: ${err.message}`);
-    }
-  }
-
-  const skillLabel = role ? `${base}+${role}` : base;
-  const child = runHeadless({
-    prompt: finalPrompt,
-    formation: 'unit',
-    skill: skillLabel,
-    sessionId,
-    projectPath,
-    worktreeDir: _worktreePath,
-  });
-
-  // 5. 註冊 dispatch
-  const logPath = child._formation?.logPath;
-  registerDispatch({ sessionId, logPath, taskId: resolvedTask, formation: 'unit-v2', projectPath });
-  process.on('exit', () => unregisterDispatch(sessionId));
-
-  // 6. 閉環：post-complete
-  let cleanedUp = false;
-  const onDone = (code) => {
-    if (cleanedUp) return;
-    cleanedUp = true;
-    unregisterDispatch(sessionId);
-
-    // Worktree cleanup: remove isolated worktree after agent completes
-    if (_worktreePath) {
-      try { removeWorktree(projectPath || ROOT, _worktreePath); } catch {}
-    }
-
-    if (resolvedTask && resolvedTask.startsWith('TASK_') && !skipPostComplete) {
-      if (code === 0) {
-        console.log(`\n⚔️  Auto Post-Complete: ${resolvedTask}`);
-        ensureTaskComplete(resolvedTask, projectPath);
-        try {
-          postComplete({ taskId: resolvedTask, projectPath, skipTests });
-        } catch (e) {
-          console.error(`❌ Post-complete failed: ${e.message}`);
-        }
-      } else {
-        console.log(`\n⚠️  Agent exited with code ${code} — skipping post-complete`);
-      }
-    } else if (code === 0) {
-      syncCommit(resolvedTask, projectPath);
-    }
-
-    broadcastStatusSync(projectPath, { is_online: false, current_task: null, touching_files: [] });
-    setTimeout(() => process.exit(code || 0), 500);
-  };
-
-  child.on('close', onDone);
-  child.on('formation:done', onDone);
-
-  return child;
-}
-
-// ─────────────────────────────────────────
-// CLI
-// ─────────────────────────────────────────
-
-if (require.main === module) {
-  const args = process.argv.slice(2);
-
-  if (args.includes('--help') || args.includes('-h')) {
-    console.log(`
-⚔️  Formation Headless V2 Launcher
-
-雙軸架構：base（行為模式）+ role（角色專業）
-
-Usage:
-  node .formation/tools/headless-v2.js --base=<mode> [--role=<name>] --task=<value>
-
-Options:
-  --base <mode>           行為模式: do (default), plan, think
-  --role <name>           角色名稱或路徑（可選）
-                            短名稱:  developer, frontend, backend, designer, qa, sre, pm
-                            路徑:    legacy/developer, solo/strategy, solo/diagnosis
-  --task <value>          TASK_ID 或任務描述
-  --project-path <p>      子專案路徑
-  --dry-run               只印合成的 prompt，不啟動進程
-  --skip-post-complete    跳過 post-complete
-  --skip-tests            跳過回歸測試
-  --force                 強制執行（忽略依賴未滿足）
-
-Role Map: .formation/role-map.yaml
-
-Examples:
-  # 開發者執行任務
-  node .formation/tools/headless-v2.js --base=do --role=developer --task=TASK_301
-
-  # 策略分析
-  node .formation/tools/headless-v2.js --base=think --role=strategy --task=TASK_302
-
-  # 純執行（無角色注入）
-  node .formation/tools/headless-v2.js --base=do --task=TASK_303
-
-  # 用路徑指定角色
-  node .formation/tools/headless-v2.js --base=do --role=solo/strategy --task=TASK_304
-`);
-    process.exit(0);
-  }
-
-  const getArg = (flag) => {
-    for (let i = 0; i < args.length; i++) {
-      if (args[i].startsWith(`${flag}=`)) return args[i].split('=').slice(1).join('=');
-      if (args[i] === flag && args[i + 1]) return args[i + 1];
-    }
-    return null;
-  };
-
-  const base = getArg('--base') || 'do';
-  const role = getArg('--role') || null;
-  const task = getArg('--task');
-  const dryRun = args.includes('--dry-run');
-  const projectPath = getArg('--project-path');
-  const skipPostComplete = args.includes('--skip-post-complete');
-  const skipTests = args.includes('--skip-tests');
-  const force = args.includes('--force');
-
-  launch({ base, role, task, dryRun, projectPath, skipPostComplete, skipTests, force });
-}
-
-module.exports = { launch, loadRoleMap, loadRole, VALID_BASES };