kenaz 0.0.0-stage → 0.3.2

package/core/.collaboration/core/task-api.js

@@ -0,0 +1,3729 @@
+#!/usr/bin/env node
+/**
+ * task-api.js — Thalamus-integrated task management
+ * 統一任務查詢 API v3.5
+ *
+ * v3.5 改進:
+ * - 新增 verification 欄位（三層驗證規格）：level_1 commands, level_2 API probes, level_3 Playwright
+ * - task-api.js create 支援 --verification JSON 參數
+ * - task-api.js list 含 verification 的 task 顯示 [V] 標記
+ *
+ * v3.5 改進:
+ * - 支援可配置 tasksDir（多專案支援）
+ * - 自動偵測 core project vs sub-project（.kenaz/ 存在與否）
+ * - CLI 新增 --project-path 參數
+ * - Legacy pipeline fallback 支援 projectPath
+ * - 無參數時 100% backward compatible
+ *
+ * v3.3 改進:
+ * - 新增 rigor 欄位（嚴謹度）：high 需要 team 執行
+ *
+ * v3.2 改進:
+ * - 新增 hash 欄位（UUID v4）用於 ID 衝突時的唯一識別
+ * - agent_type 改名為 role（保持向後相容）
+ * - 新增 tags 欄位（陣列）
+ * - 新增 actual_hours 和 branch 欄位
+ * - 簡化人員追蹤（移除 assigned_to, collaborators, metadata）
+ *
+ * v3.1 改進:
+ * - 使用 js-yaml 替代自訂 YAML 解析器（修復 round-trip 資料損壞 Bug）
+ * - moveTask 原子性操作（先複製後刪除）
+ * - 狀態機驗證（禁止不合理的狀態轉換）
+ *
+ * 目錄結構:
+ * Core project:    .collaboration/tasks/{status}/
+ * Sub-project:     .kenaz/tasks/{status}/
+ *
+ * .collaboration/tasks/ (or .kenaz/tasks/)
+ * ├── backlog/     # status: backlog (原 pending)
+ * ├── active/      # status: active (原 in_progress)
+ * ├── done/        # status: done (原 completed)
+ * ├── cancel/      # status: cancel (原 cancelled)
+ * └── blocked/     # status: blocked
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const { execSync } = require('child_process');
+const { randomUUID } = require('crypto');
+const fsSync = require('fs');
+
+// ─────────────────────────────────────────
+// M1: wx Claim Marker helpers (TASK_1758)
+// Spec: dev/MULTI_ANSUZ_SPEC.md §2.2
+// ─────────────────────────────────────────
+
+function _claimContext(projectRoot) {
+  const locksDir = require('path').join(projectRoot, '.kenaz', 'locks');
+  const streamFile = require('path').join(projectRoot, '.kenaz', 'specialist', 'current_stream.json');
+  // TASK_2265: env-first (CLAUDE_CODE_SESSION_ID = own conversation id, mirrors
+  // dispatch.js _getOwnConversationId), then the per-conversation binding
+  // (hmap/scratch via _session-identity.js), current_stream.json singleton last.
+  const envConv = process.env.CLAUDE_CODE_SESSION_ID || null;
+  let convId = envConv;
+  let streamId = null;
+  let source = null;
+  if (envConv) {
+    try {
+      const ident = require(require('path').join(projectRoot, '.claude', 'hooks', '_session-identity.js'));
+      const b = ident.resolveOwnBinding(envConv, require('path').join(projectRoot, '.kenaz', 'specialist', 'sessions'));
+      if (b && b.bootSid) { streamId = b.bootSid; source = b.source; }
+    } catch { /* no helper in this project: fall through to the singleton */ }
+  }
+  if (!streamId) {
+    try {
+      const parsed = JSON.parse(require('fs').readFileSync(streamFile, 'utf8'));
+      // A singleton that names a DIFFERENT conversation belongs to another live session:
+      // never adopt it as our owner (worker-skip instead of a wrong-owner marker).
+      const foreign = envConv && parsed && parsed.conversation_id && parsed.conversation_id !== envConv;
+      if (parsed && parsed.session_id && !foreign) { streamId = parsed.session_id; source = 'current_stream'; }
+      if (!convId && parsed && parsed.conversation_id) convId = parsed.conversation_id;
+    } catch { /* no identity = worker context */ }
+  }
+  return { locksDir, streamId, convId, source };
+}
+
+function _claimMarkerPath(locksDir, taskId) {
+  return require('path').join(locksDir, 'claim_' + taskId + '.json');
+}
+
+function _isPidAlive(pid) {
+  if (!pid || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (e) { if (e.code === 'EPERM') return true; return false; }
+}
+
+function acquireClaimMarker(taskId, projectRoot, opts = {}) {
+  const { locksDir, streamId, convId } = _claimContext(projectRoot);
+  if (!streamId) return { claimed: true, workerSkip: true };
+  const fsS = require('fs');
+  const p = require('path');
+  fsS.mkdirSync(locksDir, { recursive: true });
+  const markerPath = _claimMarkerPath(locksDir, taskId);
+  // M1.5 (TASK_1761): owner_pid records process.pid (CLI pid) for re-entrancy detection.
+  // Liveness is judged via owner session LEASE (isSessionLive), not owner_pid alone.
+  // marker owner_pid is informational for re-entrancy; session lease is authoritative for liveness.
+  const content = JSON.stringify({
+    owner_session: streamId,
+    owner_conversation_id: convId || null,
+    owner_pid: process.pid,
+    claimed_at: new Date().toISOString(),
+    dispatch_path: opts.dispatchPath || null,
+  }, null, 2);
+  try {
+    fsS.writeFileSync(markerPath, content, { flag: 'wx', encoding: 'utf8' });
+    return { claimed: true };
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+    let existing = null;
+    try { existing = JSON.parse(fsS.readFileSync(markerPath, 'utf8')); } catch { /* corrupted */ }
+    if (!existing) {
+      fsS.writeFileSync(markerPath, content, { encoding: 'utf8' });
+      return { claimed: true };
+    }
+    if (existing && existing.owner_session === streamId && existing.owner_pid === process.pid) {
+      // Re-entrant acquire by the same session+anchor (claimTask -> moveTask double path): refresh and succeed.
+      // Requires pid match too: concurrent CLIs share the same stream identity, so session alone is not proof of re-entrancy.
+      fsS.writeFileSync(markerPath, content, { encoding: 'utf8' });
+      return { claimed: true, reentrant: true };
+    }
+    // M1.5 (TASK_1761): owned/orphan judgment now uses owner SESSION lease liveness, not just owner_pid.
+    // Load the owner's lease from the leases directory and apply isSessionLive.
+    // Fallback to _isPidAlive(owner_pid) when no lease file exists.
+    const ownerSession = existing.owner_session;
+    const ownerPid = existing.owner_pid;
+    let ownerIsLive = false;
+    try {
+      const slPath = require('path').join(projectRoot, '.specialist', 'tools', 'stream-lease.js');
+      const sl = require(slPath);
+      const ownerLease = sl.readLease(ownerSession);
+      ownerIsLive = ownerLease ? sl.isSessionLive(ownerLease) : _isPidAlive(ownerPid);
+    } catch (_e) { ownerIsLive = _isPidAlive(ownerPid); }
+    if (ownerIsLive) {
+      return { claimed: false, reason: 'owned', owner: existing };
+    }
+    // Dead owner = ORPHAN
+    console.warn([
+      '⚠️  ORPHAN CLAIM DETECTED: ' + taskId,
+      '   Previous owner session: ' + existing.owner_session + ' (pid=' + ownerPid + ') — DEAD',
+      '   Claimed at: ' + existing.claimed_at,
+      '   The process is gone but the claim marker was not released.',
+      '   This likely indicates a crash. Manual arbitration required.',
+      '   To override: re-run with --force-claim (prints this warning and proceeds).',
+    ].join(String.fromCharCode(10)));
+    if (!opts.forceClaim) {
+      return { claimed: false, reason: 'orphan', owner: existing };
+    }
+    console.warn('⚠️  --force-claim: overriding orphan marker for ' + taskId);
+    fsS.writeFileSync(markerPath, content, { encoding: 'utf8' });
+    return { claimed: true, forceOverride: true };
+  }
+}
+
+function releaseClaimMarker(taskId, projectRoot) {
+  // No identity check: the marker guards a card while it is active, and a card leaving
+  // active is done with it whoever moved it. Worker contexts (verify-and-land,
+  // subagents) complete most cards and have no stream id; skipping them leaked a
+  // marker per completed card (Huginn 2026-10-05/07).
+  const { locksDir } = _claimContext(projectRoot);
+  const markerPath = _claimMarkerPath(locksDir, taskId);
+  try { require('fs').unlinkSync(markerPath); } catch { /* already gone */ }
+}
+
+// ─────────────────────────────────────────
+// TASK_1861: Dispatch-path-agnostic health snapshot capture
+// _before at activation (move/claim/update→active), _after + observe-only verdict
+// at completion (complete AND bare `move X done`). Fires a detached child so the
+// short-lived CLI never blocks, fails, or slows on Dashboard state. Every capture
+// attempt is audited in .kenaz/health_snapshots/snapshot_events.jsonl (never silent).
+// Reuses .formation/tools/post-complete/health.js (measureHealthScoreSync etc.) —
+// no third implementation. Does NOT touch guardian_counter.json (TASK_1720 periodic
+// counter semantics unchanged; verdict stays observe-only, no git action).
+// ─────────────────────────────────────────
+
+function _appendSnapshotEvent(projectRoot, taskId, phase, action, reason) {
+  try {
+    const dir = path.join(projectRoot, '.kenaz', 'health_snapshots');
+    fsSync.mkdirSync(dir, { recursive: true });
+    const line = JSON.stringify({
+      task_id: taskId,
+      ts: new Date().toISOString(),
+      snapshot_type: phase,
+      action,
+      ...(reason ? { reason } : {}),
+    });
+    fsSync.appendFileSync(path.join(dir, 'snapshot_events.jsonl'), line + '\n', 'utf8');
+  } catch { /* audit is best-effort — must never block task ops */ }
+}
+
+function scheduleHealthSnapshotCapture(taskId, phase, projectRoot) {
+  try {
+    if (!taskId || !projectRoot) return;
+    const healthJs = path.join(__dirname, '..', '..', '.formation', 'tools', 'post-complete', 'health.js');
+    if (!fsSync.existsSync(healthJs)) {
+      _appendSnapshotEvent(projectRoot, taskId, phase, 'skipped', 'health_module_missing');
+      return;
+    }
+    const cfg = { taskId, phase, projectRoot, healthJs };
+    // ASCII-only inline script (Windows argv codepage safety). Child owns the full
+    // outcome audit: written | skipped(reason). measureHealthScoreSync already
+    // handles Dashboard-down gracefully (returns null within its own timeout).
+    const script = [
+      `const CFG = ${JSON.stringify(cfg)};`,
+      "const fs = require('fs');",
+      "const path = require('path');",
+      "function logEvent(action, reason) {",
+      "  try {",
+      "    const dir = path.join(CFG.projectRoot, '.kenaz', 'health_snapshots');",
+      "    fs.mkdirSync(dir, { recursive: true });",
+      "    const line = JSON.stringify({ task_id: CFG.taskId, ts: new Date().toISOString(), snapshot_type: CFG.phase, action, ...(reason ? { reason } : {}) });",
+      "    fs.appendFileSync(path.join(dir, 'snapshot_events.jsonl'), line + '\\n', 'utf8');",
+      "  } catch (_e) { /* best-effort */ }",
+      "}",
+      "try {",
+      "  const snapFile = path.join(CFG.projectRoot, '.kenaz', 'health_snapshots', CFG.taskId + '_' + CFG.phase + '.json');",
+      "  if (fs.existsSync(snapFile)) { logEvent('skipped', 'snapshot_already_exists'); process.exit(0); }",
+      "  const h = require(CFG.healthJs);",
+      "  const health = h.measureHealthScoreSync(CFG.projectRoot);",
+      "  if (!health || typeof health.score !== 'number') { logEvent('skipped', 'dashboard_unreachable'); process.exit(0); }",
+      // TASK_1891: capture the written payload (delta_from_previous) for
+      // observability threading into computeHealthVerdict below -- see
+      // health.js's computeHealthVerdict doc comment for why that field
+      // never gates the verdict itself.
+      "  const afterPayload = h.saveTaskHealthSnapshot(CFG.taskId, CFG.phase, health, CFG.projectRoot);",
+      "  logEvent('written');",
+      "  if (CFG.phase === 'after') {",
+      "    const pre = h.readPreTaskHealthSnapshot(CFG.taskId, CFG.projectRoot);",
+      "    if (pre && typeof pre.score === 'number') {",
+      "      const loopCfg = h.readLoopConfig(CFG.projectRoot);",
+      "      const threshold = typeof loopCfg.revert_threshold === 'number' ? loopCfg.revert_threshold : h.DEFAULT_REVERT_THRESHOLD;",
+      // TASK_1890/1891: same computeHealthVerdict as post-complete.js's
+      // auto/manual arms -- no third re-implementation of the delta/trust-gate
+      // logic. No git access here (no isScopeUnchanged callback), so guard 3
+      // (stale snapshot + zero scope diff) is a safe no-op for this call
+      // site, same as it always was before TASK_1890. TASK_1891: pass the
+      // full `pre` object (not pre.score) so ordering + symmetric trust can
+      // be checked -- this is one of the two call sites that actually runs
+      // in production (readLoopConfig's TASK_1885 note).
+      "      const vr = h.computeHealthVerdict(pre, health, threshold, { projectPath: CFG.projectRoot, trendDeltaFromPrevious: afterPayload ? afterPayload.delta_from_previous : null });",
+      "      const reason = vr.verdict === 'REVERT'",
+      "        ? vr.reason + ' - observe-only capture at task completion, no git action taken'",
+      "        : vr.reason;",
+      "      h.writeVerdictToTask(CFG.taskId, vr.verdict, vr.delta, reason, CFG.projectRoot);",
+      "    }",
+      "  }",
+      "} catch (e) { logEvent('skipped', 'error: ' + String(e && e.message || e)); }",
+    ].join('\n');
+    const { spawn } = require('child_process');
+    const child = spawn(process.execPath, ['-e', script], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.unref();
+  } catch (e) {
+    _appendSnapshotEvent(projectRoot, taskId, phase, 'skipped', 'spawn_failed: ' + String(e && e.message || e));
+  }
+}
+const yaml = (() => {
+  try { return require('js-yaml'); } catch {
+    // Fallback: resolve .vendor/js-yaml.cjs relative to this script's real location.
+    // When task-api.js is copied to a temp directory, '../../' relative path breaks.
+    // Try multiple strategies:
+    const candidates = [
+      path.resolve(__dirname, '../../.vendor/js-yaml.cjs'),           // normal: .collaboration/core/ → project root
+      path.resolve(__dirname, '.vendor/js-yaml.cjs'),                 // temp dir mirror
+    ];
+    // Also try KENAZ_SOURCE_DIR if set
+    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.');
+  }
+})();
+
+// Shared project identity resolver (TASK_1701): pin-based session->project routing.
+// Lazy-loaded so task-api.js can still run without the specialist tools tree.
+let _projectResolver = null;
+function getProjectResolver() {
+  if (_projectResolver) return _projectResolver;
+  try {
+    _projectResolver = require('../../.specialist/tools/lib/project-resolver');
+  } catch (_) { _projectResolver = null; }
+  return _projectResolver;
+}
+
+// Yggdrasil task-sync (lazy loaded, graceful degradation)
+let _taskSync = null;
+let _taskSyncLoaded = false;
+function getTaskSync() {
+  if (_taskSyncLoaded) return _taskSync;
+  _taskSyncLoaded = true;
+  try {
+    const mod = require('../../.formation/tools/task-sync');
+    _taskSync = mod;
+  } catch {
+    _taskSync = null;
+  }
+  return _taskSync;
+}
+
+// TASK_2142 R2: Task Pool status push (lazy loaded, graceful degradation --
+// a sub-project checkout without .formation/ must not break moveTask).
+// Overridable via setPoolStatusPush() so tests can inject a fake/spy
+// implementation instead of require()-caching a module-level singleton.
+let _poolStatusPush = null;
+let _poolStatusPushLoaded = false;
+function getPoolStatusPush() {
+  if (_poolStatusPushLoaded) return _poolStatusPush;
+  _poolStatusPushLoaded = true;
+  try {
+    _poolStatusPush = require('../../.formation/tools/pool-status-push');
+  } catch {
+    _poolStatusPush = { pushPoolStatus: async () => ({ pushed: false, reason: 'module-unavailable' }) };
+  }
+  return _poolStatusPush;
+}
+/** Test seam: force a specific module (or reset with null to re-require on next call). */
+function setPoolStatusPush(mod) {
+  _poolStatusPush = mod;
+  _poolStatusPushLoaded = mod !== null;
+}
+
+// 配置
+const CONFIG = {
+  TASKS_DIR: path.join(__dirname, '../tasks'),
+  API_VERSION: '3.5.0',
+  // 有效的 role 值
+  VALID_ROLES: ['backend', 'designer', 'developer', 'frontend', 'pm', 'qa', 'sre', 'team_developer', 'team_strategy'],
+  // 常用 tags
+  COMMON_TAGS: ['doc', 'code', 'plan', 'fix', 'refactor', 'test', 'design', 'review'],
+  // 有效的 rigor 值（嚴謹度）
+  VALID_RIGOR: ['high', 'medium', 'low'],
+  // 狀態目錄映射（list 預設掃描範圍，不含 archived）
+  STATUS_DIRS: ['backlog', 'active', 'done', 'blocked', 'cancel'],
+  // 所有有效的狀態目錄（含 archived，用於 moveTask 驗證）
+  ALL_STATUS_DIRS: ['backlog', 'active', 'done', 'blocked', 'cancel', 'archived', 'pool'],
+  // 舊狀態 → 新狀態映射（向後相容）
+  STATUS_MAP: {
+    'pending': 'backlog',
+    'in_progress': 'active',
+    'completed': 'done',
+    'cancelled': 'cancel',
+    'blocked': 'blocked',
+    'split': 'backlog',
+    'archived': 'archived'
+  },
+  // 新狀態 → 舊狀態映射（輸出相容）
+  REVERSE_STATUS_MAP: {
+    'backlog': 'pending',
+    'active': 'in_progress',
+    'done': 'completed',
+    'cancel': 'cancelled',
+    'blocked': 'blocked',
+    'archived': 'completed'
+  },
+  // 狀態機：允許的狀態轉換
+  ALLOWED_TRANSITIONS: {
+    'backlog': ['active', 'cancel', 'blocked'],
+    'active': ['done', 'blocked', 'cancel', 'backlog'],
+    'blocked': ['active', 'backlog', 'cancel'],
+    'done': ['backlog', 'archived'],  // 重新開啟 or 封存
+    'cancel': ['backlog'], // 重新開啟
+    'archived': ['backlog'] // 重新開啟
+  }
+};
+
+// Default number of recent entries to load for large dirs (done/cancel) in CLI fast path
+const RECENT_DEFAULT = 20;
+
+/**
+ * 使用 js-yaml 解析 YAML 內容
+ * json: true → 允許 duplicated keys（last-wins，與 JSON.parse 行為一致）
+ * 避免因歷史資料汙染（assigned_to/metadata 混入 outcome 欄位）導致靜默丟失任務
+ */
+function parseYAML(content, filePath) {
+  try {
+    const result = yaml.load(content, { json: true });
+    return result ?? {};
+  } catch (error) {
+    const location = filePath ? ` (file: ${filePath})` : '';
+    console.error(`YAML 解析錯誤${location}:`, error.message);
+    return {};
+  }
+}
+
+/**
+ * 使用 js-yaml 將物件轉換為 YAML 格式
+ */
+function toYAML(obj) {
+  // 過濾掉內部屬性
+  const cleanObj = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (!key.startsWith('_')) {
+      cleanObj[key] = value;
+    }
+  }
+  return yaml.dump(cleanObj, {
+    indent: 2,
+    lineWidth: -1,  // 不自動換行
+    noRefs: true,   // 不使用引用
+    sortKeys: false // 保持原有順序
+  });
+}
+
+/**
+ * TASK_1771: Coerce a value into a TOKEN array for LIST fields
+ * (dependencies, tags, scope_paths). These hold comma-separable short tokens
+ * (e.g. "TASK_9001,TASK_9002" or "code,fix").
+ * - array      => map(String).map(trim).filter(Boolean)
+ * - string     => split(",").map(trim).filter(Boolean)
+ * - null/other => []
+ * Root-cause safety net: MCP/args-file/programmatic callers may pass a raw
+ * string where an array is expected; without coercion a poisoned task crashes
+ * every consumer that calls .join/.some/.filter on the field, aborting the
+ * whole-queue dispatch scan.
+ */
+function toTokenArray(v) {
+  if (Array.isArray(v)) {
+    return v.map((x) => String(x).trim()).filter(Boolean);
+  }
+  if (typeof v === "string") {
+    return v.split(",").map((s) => s.trim()).filter(Boolean);
+  }
+  return [];
+}
+
+/**
+ * TASK_1771: Coerce a value into a FREE-TEXT array for prose fields
+ * (requirements, acceptance_criteria, technical_notes). These may contain
+ * commas / newlines / YAML block scalars, so we MUST NOT comma-split.
+ * - array      => filter(x => x != null)
+ * - string     => trimmed non-empty ? [v] : []  (single element, preserved)
+ * - null/other => []
+ */
+function toTextArray(v) {
+  if (Array.isArray(v)) {
+    return v.filter((x) => x != null);
+  }
+  if (typeof v === "string") {
+    return v.trim() ? [v] : [];
+  }
+  return [];
+}
+
+/**
+ * TASK_1778: Count how many LIVE status dirs (backlog/active/done/blocked/cancel)
+ * exist under a tasks root. Worktree git snapshots contain ONLY archived/ because
+ * .gitignore ignores .kenaz/tasks/ (the archived files pre-date the ignore rule),
+ * so a pin/cwd resolution landing on such a snapshot makes every list/scan
+ * silently report 0 tasks while the real files sit intact in the main repo.
+ */
+function countLiveStatusDirs(tasksDir) {
+  const fsS = require('fs');
+  let n = 0;
+  for (const d of CONFIG.STATUS_DIRS) {
+    try { if (fsS.statSync(path.join(tasksDir, d)).isDirectory()) n++; } catch { /* missing */ }
+  }
+  return n;
+}
+
+/**
+ * Resolve the tasksDir for a given project path.
+ * - Sub-project (has .kenaz/): {projectPath}/.kenaz/tasks/
+ * - Core project: .collaboration/tasks/ (default)
+ * - Explicit tasksDir: use as-is
+ */
+function resolveTasksDir(options = {}) {
+  // Explicit tasksDir always wins
+  if (options.tasksDir) {
+    return options.tasksDir;
+  }
+
+  // If projectPath is provided, auto-detect
+  if (options.projectPath) {
+    const fsSync = require('fs');
+    const collabTasksDir = path.join(options.projectPath, '.collaboration', 'tasks');
+    const kenazTasksDir = path.join(options.projectPath, '.kenaz', 'tasks');
+    const hasCollab = fsSync.existsSync(collabTasksDir);
+    const hasKenaz = fsSync.existsSync(kenazTasksDir);
+
+    // All projects use .kenaz/tasks/ when available (unified path, no core vs sub-project distinction)
+    if (hasKenaz) return kenazTasksDir;
+    if (hasCollab) return collabTasksDir;
+
+    // Fallback: assume sub-project pattern
+    return kenazTasksDir;
+  }
+
+  // Default: consult pin file first (TASK_1701), then cwd, then CONFIG default.
+  // This ensures a session pinned to a sub-project gets that project tasks,
+  // without requiring --project-path on every invocation.
+  const fsSync = require('fs');
+  const resolver = getProjectResolver();
+  if (resolver) {
+    const resolved = resolver.resolveProjectPath({ argv: process.argv.slice(2) });
+    if (resolved.source !== 'base') {
+      // Pin or cwd detected a specific project -- use its tasks dir
+      const pinKenaz = path.join(resolved.projectPath, '.kenaz', 'tasks');
+      const pinCollab = path.join(resolved.projectPath, '.collaboration', 'tasks');
+      const candidate = fsSync.existsSync(pinKenaz) ? pinKenaz
+        : (fsSync.existsSync(pinCollab) ? pinCollab : null);
+      if (candidate) {
+        // TASK_1778: a tasks root with ZERO live status dirs (backlog/active/done/
+        // blocked/cancel) is degenerate -- typically a .formation/worktrees/wt-*
+        // git snapshot that only carries archived/. Following it makes list/scan
+        // silently report 0 tasks. A PIN pointing at such a root is ignored
+        // (loudly) and resolution falls through to cwd; a cwd-sourced degenerate
+        // root is kept (behavior-preserving) but announced on stderr.
+        const viable = countLiveStatusDirs(candidate) > 0;
+        const isPin = resolved.source === 'pin' || resolved.source === 'pin-heuristic';
+        if (viable || !isPin) {
+          if (isPin && path.resolve(resolved.projectPath) !== path.resolve(process.cwd())) {
+            process.stderr.write('[task-api] tasksDir resolved via session pin -> ' + candidate + String.fromCharCode(10));
+          }
+          if (!viable) {
+            process.stderr.write('[task-api] ⚠️ tasksDir has no live status dirs (' + CONFIG.STATUS_DIRS.join('/') + '): ' + candidate +
+              ' -- list/scan will see 0 tasks. Worktree snapshot? Use --project-path to target the real repo.' + String.fromCharCode(10));
+          }
+          return candidate;
+        }
+        process.stderr.write('[task-api] ⚠️ ignoring pinned project ' + resolved.projectPath + ': tasks root ' + candidate +
+          ' has no live status dirs (' + CONFIG.STATUS_DIRS.join('/') + ') -- falling back to cwd resolution.' + String.fromCharCode(10));
+      }
+    }
+  }
+  const cwdKenaz = path.join(process.cwd(), '.kenaz', 'tasks');
+  if (fsSync.existsSync(cwdKenaz)) {
+    if (countLiveStatusDirs(cwdKenaz) === 0) {
+      process.stderr.write('[task-api] ⚠️ tasksDir has no live status dirs (' + CONFIG.STATUS_DIRS.join('/') + '): ' + cwdKenaz +
+        ' -- list/scan will see 0 tasks. If cwd is a worktree snapshot, pass --project-path <main repo>.' + String.fromCharCode(10));
+    }
+    return cwdKenaz;
+  }
+
+  return CONFIG.TASKS_DIR;
+}
+
+/**
+ * TASK_1778: When list scans 0 tasks, explain WHERE it looked instead of a
+ * silent '0 total'. Emits stderr ONLY when there is evidence of misresolution:
+ * non-empty sibling dirs (archived/archive/...) under the resolved root, or a
+ * non-empty .kenaz/tasks under cwd that resolution ignored. A genuinely fresh
+ * empty project stays quiet. Diagnostics must never break list.
+ */
+function emitEmptyListDiagnostics(tasksDir) {
+  try {
+    const fsS = require('fs');
+    const abs = path.resolve(tasksDir);
+    const evidence = [];
+    let entries = [];
+    try { entries = fsS.readdirSync(abs, { withFileTypes: true }); } catch { /* missing root */ }
+    for (const e of entries) {
+      if (!e.isDirectory() || CONFIG.STATUS_DIRS.includes(e.name)) continue;
+      let n = 0;
+      try { n = fsS.readdirSync(path.join(abs, e.name)).filter((x) => x.startsWith('TASK_')).length; } catch { n = 0; }
+      if (n > 0) evidence.push('    sibling ' + e.name + '/ holds ' + n + ' task files -- this root looks like a snapshot (worktree?) missing live status dirs');
+    }
+    const cwdKenaz = path.resolve(process.cwd(), '.kenaz', 'tasks');
+    if (cwdKenaz !== abs && fsS.existsSync(cwdKenaz)) {
+      let live = 0;
+      for (const d of CONFIG.STATUS_DIRS) {
+        try { live += fsS.readdirSync(path.join(cwdKenaz, d)).filter((x) => x.startsWith('TASK_')).length; } catch { /* missing */ }
+      }
+      if (live > 0) evidence.push('    cwd has a non-empty tasks root: ' + cwdKenaz + ' (' + live + ' task files) -- resolution ignored it; use --project-path ' + process.cwd());
+    }
+    if (evidence.length > 0) {
+      process.stderr.write(['⚠️  [task-api] list found 0 tasks -- resolved tasksDir: ' + abs].concat(evidence).join(String.fromCharCode(10)) + String.fromCharCode(10));
+    }
+  } catch { /* never break list */ }
+}
+
+class TaskAPI {
+  /**
+   * @param {Object} config
+   * @param {string} [config.tasksDir] - Explicit tasks directory path
+   * @param {string} [config.projectPath] - Project root path (auto-detect tasksDir)
+   */
+  constructor(config = {}) {
+    this.tasksDir = resolveTasksDir(config);
+    this.projectPath = config.projectPath || null;
+  }
+
+  /**
+   * 取得當前 Git 用戶資訊
+   */
+  _getGitUser() {
+    const cwd = this.projectPath || path.resolve(__dirname, '../..');
+    try {
+      const name = execSync('git config user.name', { encoding: 'utf8', cwd, windowsHide: true }).trim();
+      const email = execSync('git config user.email', { encoding: 'utf8', cwd, windowsHide: true }).trim();
+      const gitUser = email.split('@')[0];
+      return { name, email, git_user: gitUser };
+    } catch (error) {
+      return { name: 'Unknown', email: '', git_user: 'unknown' };
+    }
+  }
+
+  /**
+   * 取得狀態對應的目錄路徑
+   */
+  _getStatusDir(status) {
+    // 轉換舊狀態名稱
+    const normalizedStatus = CONFIG.STATUS_MAP[status] || status;
+    return path.join(this.tasksDir, normalizedStatus);
+  }
+
+  /**
+   * 確保所有狀態目錄存在
+   */
+  async _ensureStatusDirs() {
+    for (const dir of CONFIG.STATUS_DIRS) {
+      await fs.mkdir(path.join(this.tasksDir, dir), { recursive: true });
+    }
+  }
+
+  /**
+   * 從任務檔案路徑推斷 status 目錄名（TASK_1843 / TASK_1846 共用 helper）：
+   * 往上走祖先目錄鏈，找出第一個屬於 ALL_STATUS_DIRS 的目錄名。
+   * 只看直接父目錄會漏掉目錄型卡片
+   * （active/TASK_XXX/TASK_XXX.yaml → 父目錄是 'TASK_XXX'，不是 status dir）。
+   * 上界：this.tasksDir（到達即停，不往上猜）；最多走 3 層，涵蓋
+   * 扁平檔（1 層）與目錄型（2 層）版面，並留一層餘裕。
+   * 找不到時回傳 null — 呼叫端自行決定 fallback 策略。
+   */
+  _resolveStatusDirName(filePath) {
+    let probeDir = path.dirname(filePath);
+    for (let depth = 0; depth < 3; depth++) {
+      const base = path.basename(probeDir);
+      if (CONFIG.ALL_STATUS_DIRS.includes(base)) {
+        return base;
+      }
+      // 到達 tasksDir 上界或檔案系統根目錄 → 停止（status dir 一定在 tasksDir 之下）
+      if (this.tasksDir && path.resolve(probeDir) === path.resolve(this.tasksDir)) break;
+      const parent = path.dirname(probeDir);
+      if (parent === probeDir) break;
+      probeDir = parent;
+    }
+    return null;
+  }
+
+  /**
+   * TASK_1864: 寫回驗證（write-back verification）。
+   * 背景：三個已修復的靜默變異缺陷（TASK_1832 / TASK_1843+1846 / TASK_1851）
+   * 機制互不相同，唯一共性是「操作回報成功，但落盤狀態 != 呼叫者認知」。
+   * 本 helper 讓該類別的下一個形狀大聲失敗：寫檔後立刻讀回、解析、
+   * 與意圖物件全欄位 diff，不一致即 throw（不是 warn — 降級成警告等於沒做）。
+   *
+   * 比對規則：
+   * - 忽略底線開頭內部鍵（_file_path/_status_dir/...，toYAML 本來就過濾）
+   * - 忽略 metadata.updated_at（每次寫入必變）
+   * - 其餘欄位全比對，不用白名單 — 白名單會讓下一個未預期形狀再度靜默
+   * - Date 與 ISO 字串視為等值（YAML timestamp round-trip 可能互轉）
+   *
+   * 唯一實作：createTask / updateTask / moveTask 三個寫入點共用本方法，
+   * 禁止複製第二份（lock 協定三份實作各自漂移的前例：TASK_1839）。
+   */
+  async _verifyPersisted(filePath, intendedTask) {
+    let content;
+    try {
+      content = await fs.readFile(filePath, 'utf8');
+    } catch (err) {
+      throw new Error(`PERSISTENCE VERIFY FAILED (${filePath}): 寫入後無法讀回 — ${err.message}`);
+    }
+    const persisted = parseYAML(content, filePath);
+
+    // 意圖基準：與 toYAML 相同的底線鍵過濾（內部鍵不落盤）
+    const intended = {};
+    for (const [key, value] of Object.entries(intendedTask)) {
+      if (!key.startsWith('_')) intended[key] = value;
+    }
+
+    const IGNORED_PATHS = new Set(['metadata.updated_at']);
+    // YAML round-trip 正規化：Date <-> ISO 字串視為同值
+    const norm = (v) => (v instanceof Date ? v.toISOString() : v);
+    const show = (v) => {
+      if (v === undefined) return '<missing>';
+      let s;
+      try { s = JSON.stringify(norm(v)); } catch { s = String(v); }
+      return s && s.length > 120 ? s.slice(0, 120) + '…' : s;
+    };
+
+    const diffs = [];
+    const walk = (a, b, prefix) => {
+      if (IGNORED_PATHS.has(prefix)) return;
+      const na = norm(a);
+      const nb = norm(b);
+      if (na === nb) return;
+      const aIsObj = na !== null && typeof na === 'object';
+      const bIsObj = nb !== null && typeof nb === 'object';
+      if (aIsObj && bIsObj && Array.isArray(na) === Array.isArray(nb)) {
+        const keys = new Set([...Object.keys(na), ...Object.keys(nb)]);
+        for (const k of keys) {
+          walk(na[k], nb[k], prefix ? `${prefix}.${k}` : k);
+        }
+        return;
+      }
+      diffs.push(`${prefix || '<root>'}: intended=${show(a)} persisted=${show(b)}`);
+    };
+    walk(intended, persisted, '');
+
+    if (diffs.length > 0) {
+      throw new Error(
+        `PERSISTENCE VERIFY FAILED (${filePath}): 落盤內容與意圖不一致（${diffs.length} 處）— ` +
+        diffs.slice(0, 10).join('; ') +
+        (diffs.length > 10 ? `; …+${diffs.length - 10} more` : '')
+      );
+    }
+  }
+
+  /**
+   * 讀取 YAML 任務檔案
+   * Returns null when the file is unreadable or its YAML is invalid AND
+   * the parser produced an empty object — caller should filter nulls so
+   * one corrupted file does not break the entire list/scan operation.
+   */
+  async _loadTaskFile(filePath) {
+    let content;
+    try {
+      content = await fs.readFile(filePath, 'utf8');
+    } catch (err) {
+      console.error(`Task file unreadable (${filePath}): ${err.message}`);
+      return null;
+    }
+    const task = parseYAML(content, filePath);
+
+    // parseYAML returns {} on failure (after logging the error). Empty object →
+    // unrecoverable parse failure, skip silently (the parser already logged).
+    if (!task || Object.keys(task).length === 0) {
+      return null;
+    }
+
+    // Schema fallback: some legacy archived YAMLs have a valid body but no top-level
+    // `id` field. Recover the id from the filename pattern `TASK_<num>...` so the
+    // task is still discoverable instead of being silently dropped.
+    if (!task.id) {
+      const baseName = path.basename(filePath);
+      const match = baseName.match(/^(TASK_\d+)/);
+      if (match) {
+        task.id = match[1];
+      } else {
+        console.error(`Task file has no id field and filename does not match TASK_<num>: ${filePath}`);
+        return null;
+      }
+    }
+
+    // 從檔案路徑推斷狀態（TASK_1843）：祖先鏈解析抽至 _resolveStatusDirName
+    // （TASK_1846，與 updateTask 共用）。直接父目錄的舊寫法會把目錄型卡片的
+    // _status_dir 毒化成 'TASK_XXX'，並讓內嵌的陳舊 status 原樣流出
+    // （get 與 list 對同一張卡給出不同狀態）。
+    task._file_path = filePath;
+    const statusDirName = this._resolveStatusDirName(filePath);
+
+    if (statusDirName) {
+      // 目錄是狀態的唯一真相來源（使用舊格式輸出），同時覆寫內嵌 status 與 _status_dir
+      task._status_dir = statusDirName;
+      task.status = CONFIG.REVERSE_STATUS_MAP[statusDirName] || statusDirName;
+    } else {
+      // 找不到任何 status 祖先目錄：_loadTaskFile 收到了不在 status 樹下的路徑。
+      // 選擇：保留內嵌 status 值、但同時設 _status_unresolved = true。
+      // 為什麼不回 null status：既有呼叫端（list 過濾、post-complete 等）以
+      // truthy status 判斷卡片有效性，強制 null 會讓這類卡片被靜默丟棄；
+      // 保留內嵌值 + 顯式旗標讓呼叫端能區分「目錄推斷（可信）」vs
+      // 「僅內嵌值（不可信，需自行查證）」，而非沉默地信任內嵌值。
+      task._status_dir = null;
+      task._status_unresolved = true;
+    }
+
+    // 向後相容：agent_type → role
+    if (task.agent_type && !task.role) {
+      task.role = task.agent_type;
+    }
+
+    // 向後相容：字串 tags（逗號分隔）→ 陣列。歷史 bug：kenaz_task_create 曾把
+    // 逗號字串原樣寫入 YAML，下游 (t.tags || []).join 會 crash 並截斷 list 輸出。
+    if (typeof task.tags === 'string') {
+      task.tags = task.tags.split(',').map((t) => t.trim()).filter(Boolean);
+    }
+
+    return task;
+  }
+
+  /**
+   * 掃描指定目錄下的所有 YAML 任務
+   * 支援兩種格式：
+   * - 檔案: TASK_XXX_username.yaml
+   * - 資料夾: TASK_XXX/ (內含 .yaml 檔案)
+   */
+  async _scanDir(dirPath) {
+    const tasks = [];
+    const seenIds = new Set();
+
+    try {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (!entry.name.startsWith('TASK_')) continue;
+
+        if (entry.isFile() &&
+            (entry.name.endsWith('.yaml') || entry.name.endsWith('.yml'))) {
+          // Flat file: TASK_XXX_username.yaml
+          try {
+            const filePath = path.join(dirPath, entry.name);
+            const task = await this._loadTaskFile(filePath);
+            // _loadTaskFile returns null for unreadable / corrupted / id-less files
+            if (!task) continue;
+            if (seenIds.has(task.id)) continue;
+            seenIds.add(task.id);
+            tasks.push(task);
+          } catch (error) {
+            console.error(`警告: 無法載入任務 ${entry.name}:`, error.message);
+          }
+        } else if (entry.isDirectory()) {
+          // Directory task: TASK_XXX/ — find .yaml files inside
+          try {
+            const subEntries = await fs.readdir(path.join(dirPath, entry.name), { withFileTypes: true });
+            for (const sub of subEntries) {
+              if (sub.isFile() && (sub.name.endsWith('.yaml') || sub.name.endsWith('.yml'))) {
+                try {
+                  const filePath = path.join(dirPath, entry.name, sub.name);
+                  const task = await this._loadTaskFile(filePath);
+                  if (!task) continue;
+                  // Ensure id from directory name if missing (defensive — _loadTaskFile
+                  // already requires id, but the directory-based layout could legitimately
+                  // carry id only in dirname)
+                  if (!task.id) {
+                    const match = entry.name.match(/^(TASK_\d+)/);
+                    if (match) task.id = match[1];
+                  }
+                  tasks.push(task);
+                } catch (error) {
+                  console.error(`警告: 無法載入任務 ${entry.name}/${sub.name}:`, error.message);
+                }
+              }
+            }
+          } catch (error) {
+            console.error(`警告: 無法掃描資料夾 ${entry.name}:`, error.message);
+          }
+        }
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+
+    return tasks;
+  }
+
+  /**
+   * 掃描所有狀態目錄
+   */
+  async _scanAllDirs(includeArchived = false) {
+    const allTasks = [];
+    const seenIds = new Set();
+    const dirsToScan = includeArchived ? [...CONFIG.STATUS_DIRS, 'archived'] : CONFIG.STATUS_DIRS;
+
+    // 1. 當前專案任務（.kenaz/tasks/ 或 .collaboration/tasks/）
+    for (const dir of dirsToScan) {
+      const dirPath = path.join(this.tasksDir, dir);
+      const tasks = await this._scanDir(dirPath);
+      for (const t of tasks) {
+        t._source = 'new';
+        seenIds.add(t.id);
+        allTasks.push(t);
+      }
+    }
+
+    // 2. 舊系統（dev/pipeline/）— 只有 Core 專案才掃描
+    //    子專案（.kenaz/tasks/）不再載入 legacy pipeline
+    const isSubProject = this.tasksDir.includes('.kenaz');
+    if (!isSubProject) {
+      const legacyTasks = await this._scanLegacyPipeline();
+      for (const t of legacyTasks) {
+        if (!seenIds.has(t.id)) {
+          t._source = 'old';
+          seenIds.add(t.id);
+          allTasks.push(t);
+        }
+      }
+    }
+
+    // 3. 專案隔離：不再跨專案載入任務
+    //    主專案只讀主專案任務，子專案只讀子專案任務
+
+    return allTasks;
+  }
+
+  /**
+   * Resolve project root from tasksDir.
+   * Core: .collaboration/tasks/ -> go up 2 levels
+   * Sub-project: .kenaz/tasks/ -> go up 2 levels
+   */
+  _resolveProjectRoot() {
+    if (this.projectPath) return this.projectPath;
+    return path.resolve(this.tasksDir, '../..');
+  }
+
+  _getAnsuzThoughtStackPath() {
+    return path.join(this._resolveProjectRoot(), '.kenaz', 'specialist', 'ansuz_thoughts_stack.json');
+  }
+
+  _rewriteJsonFileAtomic(filePath, data) {
+    const fsSync = require('fs');
+    const tempPath = `${filePath}.tmp`;
+    fsSync.mkdirSync(path.dirname(filePath), { recursive: true });
+    fsSync.writeFileSync(tempPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+    fsSync.renameSync(tempPath, filePath);
+  }
+
+  _autoPopThoughtsForCompletedTask(taskId, completedAt) {
+    const fsSync = require('fs');
+    const stackPath = this._getAnsuzThoughtStackPath();
+
+    if (!fsSync.existsSync(stackPath)) {
+      return {
+        event: 'thought_stack.auto_pop',
+        task_id: taskId,
+        removed_ids: [],
+        removed_count: 0,
+        completed_at: completedAt
+      };
+    }
+
+    const raw = fsSync.readFileSync(stackPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    const originalStack = Array.isArray(parsed?.stack) ? parsed.stack : [];
+    const nowMs = Date.now();
+    const liveStack = originalStack.filter((thought) => {
+      if (!thought || typeof thought !== 'object') return false;
+      if (typeof thought.expires_at !== 'string' || thought.expires_at.trim() === '') {
+        return true;
+      }
+      const expiresAtMs = Date.parse(thought.expires_at);
+      return Number.isNaN(expiresAtMs) || expiresAtMs > nowMs;
+    });
+
+    const removedThoughts = liveStack.filter((thought) => thought.related_task_id === taskId);
+    const remainingStack = liveStack.filter((thought) => thought.related_task_id !== taskId);
+    const removedIds = removedThoughts
+      .map((thought) => thought.id)
+      .filter((id) => typeof id === 'string' && id.trim() !== '');
+    const shouldPersist =
+      liveStack.length !== originalStack.length ||
+      remainingStack.length !== originalStack.length;
+
+    if (shouldPersist) {
+      this._rewriteJsonFileAtomic(stackPath, {
+        ...parsed,
+        stack: remainingStack
+      });
+    }
+
+    if (removedIds.length > 0) {
+      console.log(`◈ Auto-popped ${removedIds.length} thoughts linked to ${taskId}`);
+    }
+
+    return {
+      event: 'thought_stack.auto_pop',
+      task_id: taskId,
+      removed_ids: removedIds,
+      removed_count: removedIds.length,
+      completed_at: completedAt
+    };
+  }
+
+  /**
+   * 掃描舊系統 dev/pipeline/（TASK_QUEUE.json + completed/ YAML）
+   */
+  async _scanLegacyPipeline() {
+    const projectRoot = this._resolveProjectRoot();
+    const pipelineDir = path.join(projectRoot, 'dev', 'pipeline');
+    const tasks = [];
+
+    // 2a. 從 TASK_QUEUE.json 讀取活躍（非 completed）任務
+    //     completed 任務視為 archived，不在 Dashboard 顯示
+    const queueFile = path.join(pipelineDir, 'TASK_QUEUE.json');
+    try {
+      const content = await fs.readFile(queueFile, 'utf8');
+      // 移除 BOM
+      const cleanContent = content.charCodeAt(0) === 0xFEFF ? content.slice(1) : content;
+      const queue = JSON.parse(cleanContent);
+      if (Array.isArray(queue.tasks)) {
+        for (const t of queue.tasks) {
+          if (t.id && t.status !== 'completed') {
+            t._file_path = queueFile;
+            t._source = 'old';
+            tasks.push(t);
+          }
+        }
+      }
+    } catch (e) {
+      // TASK_QUEUE.json 不存在或解析失敗，靜默跳過
+    }
+
+    // 2b. 不載入 completed/ 目錄 — 視為 archived
+    //     （舊系統的 completed/ ≈ 新系統的 archived/）
+
+    return tasks;
+  }
+
+  /**
+   * 找出最大的任務編號
+   */
+  async _findMaxTaskNumber() {
+    const tasks = await this._scanAllDirs();
+    let maxNum = 0;
+
+    for (const task of tasks) {
+      const id = task.id || '';
+      const match = id.match(/^TASK_(\d+)/);
+      if (match) {
+        const num = parseInt(match[1], 10);
+        if (num > maxNum) {
+          maxNum = num;
+        }
+      }
+    }
+
+    return maxNum;
+  }
+
+  /**
+   * 生成新的任務 ID
+   * Uses high-water mark file (.counter) to prevent ID regression when
+   * directories are temporarily empty or inaccessible (e.g., stale cwd
+   * after worktree cleanup).
+   *
+   * Shared mode (Yggdrasil relay enabled + shared_task_ids !== false):
+   *   - Consumes IDs from a lease cache {tasksDir}/.id_lease.json
+   *   - Refills from relay POST /api/tasks/allocate-ids when exhausted
+   *   - Falls back to local counter on relay failure (id_alloc: local_fallback)
+   *   - Keeps .counter monotonic so solo fallback never collides backwards
+   *
+   * Solo mode: existing behavior byte-for-byte unchanged.
+   */
+  async generateTaskID() {
+    const yggConfig = this._loadYggdrasilConfigSync();
+    const isShared = yggConfig &&
+      yggConfig.enabled !== false &&
+      yggConfig.relay_url &&
+      yggConfig.relay_url.trim() !== '' &&
+      yggConfig.shared_task_ids !== false;
+
+    if (!isShared) {
+      // Solo path — byte-for-byte unchanged
+      const scanMax = await this._findMaxTaskNumber();
+      const counterMax = this._readCounterFile();
+      const maxNum = Math.max(scanMax, counterMax);
+      const nextId = `TASK_${maxNum + 1}`;
+      this._writeCounterFile(maxNum + 1);
+      return nextId;
+    }
+
+    // ---- Shared mode ----
+    // Try to consume from lease cache first
+    const lease = this._readLease();
+    if (lease && lease.next <= lease.end) {
+      const id = lease.next;
+      this._writeLease({ ...lease, next: id + 1 });
+      this._writeCounterFile(id);
+      this._lastIdAlloc = 'relay';
+      return `TASK_${id}`;
+    }
+
+    // Lease exhausted — refill from relay
+    const scanMax = await this._findMaxTaskNumber();
+    const counterMax = this._readCounterFile();
+    const localMax = Math.max(scanMax, counterMax);
+
+    let allocated = null;
+    try {
+      allocated = await this._allocateFromRelay(yggConfig, localMax);
+    } catch {
+      // relay unreachable — fall through to local fallback
+    }
+
+    if (allocated && typeof allocated.start === 'number' && typeof allocated.end === 'number') {
+      const start = allocated.start;
+      const end = allocated.end;
+      const firstId = start;
+      this._writeLease({
+        start,
+        end,
+        next: firstId + 1,
+        leased_at: new Date().toISOString()
+      });
+      this._writeCounterFile(firstId);
+      this._lastIdAlloc = 'relay';
+      return `TASK_${firstId}`;
+    }
+
+    // Relay unreachable + lease exhausted — local fallback
+    const maxNum = localMax;
+    const nextId = `TASK_${maxNum + 1}`;
+    this._writeCounterFile(maxNum + 1);
+    this._lastIdAlloc = 'local_fallback';
+    return nextId;
+  }
+
+  // ---- Yggdrasil shared-ID helpers ----
+
+  /**
+   * Load .kenaz/yggdrasil.yaml synchronously.
+   * Returns null when file absent, parse fails, or enabled:false.
+   */
+  _loadYggdrasilConfigSync() {
+    const fsSync = require('fs');
+    const projectRoot = this._resolveProjectRoot();
+    const yamlPath = path.join(projectRoot, '.kenaz', 'yggdrasil.yaml');
+    // TASK_2244: per-machine keys live in the gitignored yggdrasil.local.yaml (overlay).
+    const localPath = path.join(projectRoot, '.kenaz', 'yggdrasil.local.yaml');
+    if (!fsSync.existsSync(yamlPath) && !fsSync.existsSync(localPath)) return null;
+    try {
+      let config = fsSync.existsSync(yamlPath) ? yaml.load(fsSync.readFileSync(yamlPath, 'utf8')) : null;
+      config = require('../../.formation/tools/yggdrasil-local.js').overlayMachineLocal(projectRoot, config, (t) => yaml.load(t));
+      if (!config || config.enabled === false) return null;
+      return config;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Read relay publishable_key.
+   * Priority: YGGDRASIL_PUBLISHABLE_KEY env var -> ~/.kenaz/credentials.yaml
+   */
+  _readPublishableKey() {
+    if (process.env.YGGDRASIL_PUBLISHABLE_KEY) {
+      return process.env.YGGDRASIL_PUBLISHABLE_KEY;
+    }
+    const fsSync = require('fs');
+    const os = require('os');
+    try {
+      const credPath = path.join(os.homedir(), '.kenaz', 'credentials.yaml');
+      if (fsSync.existsSync(credPath)) {
+        const raw = fsSync.readFileSync(credPath, 'utf8');
+        const m = raw.match(/^publishable_key:\s*"?([^"]+)"?/m);
+        if (m) return m[1].trim();
+      }
+    } catch { /* credentials unavailable */ }
+    return null;
+  }
+
+  /** Lease cache file path */
+  _leaseCachePath() {
+    return path.join(this.tasksDir, '.id_lease.json');
+  }
+
+  /** Read lease cache. Returns null when absent or corrupt. */
+  _readLease() {
+    const fsSync = require('fs');
+    try {
+      const raw = fsSync.readFileSync(this._leaseCachePath(), 'utf8');
+      const obj = JSON.parse(raw);
+      if (typeof obj.start === 'number' && typeof obj.end === 'number' && typeof obj.next === 'number') {
+        return obj;
+      }
+    } catch { /* absent or corrupt */ }
+    return null;
+  }
+
+  /** Write lease cache atomically. */
+  _writeLease(obj) {
+    const fsSync = require('fs');
+    const filePath = this._leaseCachePath();
+    const tempPath = `${filePath}.tmp`;
+    try {
+      fsSync.mkdirSync(path.dirname(filePath), { recursive: true });
+      fsSync.writeFileSync(tempPath, JSON.stringify(obj, null, 2), 'utf8');
+      fsSync.renameSync(tempPath, filePath);
+    } catch (e) {
+      process.stderr.write(`[task-api] lease write failed: ${e.message}
+`);
+    }
+  }
+
+  /**
+   * Call relay POST /api/tasks/allocate-ids with 3s total timeout.
+   * Derives HTTP base from relay_url (wss:// -> https://, ws:// -> http://).
+   * Uses Node core http/https -- no external dependencies.
+   *
+   * @param {object} yggConfig - loaded yggdrasil config
+   * @param {number} localMax  - Lamport local_max for sequence merge
+   * @returns {Promise<{start:number, end:number}>}
+   */
+  _allocateFromRelay(yggConfig, localMax) {
+    return new Promise((resolve, reject) => {
+      const relayUrl = yggConfig.relay_url;
+      const httpBase = relayUrl
+        .replace(/^wss:\/\//, 'https://')
+        .replace(/^ws:\/\//, 'http://');
+
+      const publishableKey = this._readPublishableKey();
+
+      // Derive project name (yggdrasil_project override -> folder basename)
+      const projectRoot = this._resolveProjectRoot();
+      const project = (yggConfig.yggdrasil_project && String(yggConfig.yggdrasil_project).trim()) ||
+        path.basename(projectRoot) || 'default';
+
+      const body = JSON.stringify({
+        project,
+        count: 20,
+        local_max: localMax
+      });
+
+      let url;
+      try {
+        url = new URL('/api/tasks/allocate-ids', httpBase);
+      } catch {
+        reject(new Error(`invalid relay_url: ${httpBase}`));
+        return;
+      }
+
+      const isHttps = url.protocol === 'https:';
+      const transport = isHttps ? require('https') : require('http');
+
+      const options = {
+        hostname: url.hostname,
+        port: url.port || (isHttps ? 443 : 80),
+        path: url.pathname,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(body),
+          ...(publishableKey ? { Authorization: `Bearer ${publishableKey}` } : {})
+        }
+      };
+
+      const timeoutMs = 3000;
+      let settled = false;
+
+      const req = transport.request(options, (res) => {
+        let data = '';
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          if (settled) return;
+          settled = true;
+          try {
+            const parsed = JSON.parse(data);
+            if (typeof parsed.start === 'number' && typeof parsed.end === 'number') {
+              resolve(parsed);
+            } else {
+              reject(new Error(`relay allocate-ids bad response: ${data}`));
+            }
+          } catch (e) {
+            reject(new Error(`relay allocate-ids parse error: ${e.message}`));
+          }
+        });
+      });
+
+      req.on('error', (e) => {
+        if (settled) return;
+        settled = true;
+        reject(e);
+      });
+
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        req.destroy();
+        reject(new Error('relay allocate-ids timeout'));
+      }, timeoutMs);
+
+      req.on('close', () => clearTimeout(timer));
+      req.write(body);
+      req.end();
+    });
+  }
+
+  _counterFilePath() {
+    return path.join(this.tasksDir, '.counter');
+  }
+
+  _readCounterFile() {
+    const fsSync = require('fs');
+    try {
+      const raw = fsSync.readFileSync(this._counterFilePath(), 'utf8').trim();
+      const num = parseInt(raw, 10);
+      return Number.isFinite(num) ? num : 0;
+    } catch {
+      return 0;
+    }
+  }
+
+  _writeCounterFile(num) {
+    const fsSync = require('fs');
+    try {
+      const filePath = this._counterFilePath();
+      const dir = path.dirname(filePath);
+      fsSync.mkdirSync(dir, { recursive: true });
+      fsSync.writeFileSync(filePath, String(num), 'utf8');
+    } catch (e) {
+      // best-effort — scan still works as fallback
+      process.stderr.write(`[task-api] counter write failed: ${e.message}\n`);
+    }
+  }
+
+  /**
+   * 驗證任務 ID 格式
+   */
+  validateTaskID(id) {
+    if (!id || typeof id !== 'string') return false;
+    const pattern = /^TASK_(\d+|[0-9A-Z]{10})$/;
+    return pattern.test(id);
+  }
+
+  /**
+   * 驗證狀態轉換是否合法
+   */
+  validateTransition(fromStatus, toStatus) {
+    const from = CONFIG.STATUS_MAP[fromStatus] || fromStatus;
+    const to = CONFIG.STATUS_MAP[toStatus] || toStatus;
+
+    const allowed = CONFIG.ALLOWED_TRANSITIONS[from];
+    if (!allowed) {
+      return { valid: false, reason: `無效的來源狀態: ${fromStatus}` };
+    }
+
+    if (!allowed.includes(to)) {
+      return {
+        valid: false,
+        reason: `不允許的狀態轉換: ${fromStatus} → ${toStatus}。允許的目標: ${allowed.join(', ')}`
+      };
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * 驗證任務內容品質（品質閘門）
+   * 確保任務有足夠的 description、requirements、acceptance_criteria、technical_notes
+   * @param {Object} taskData - 任務資料
+   * @returns {{ valid: boolean, warnings: string[] }}
+   */
+  validateTaskQuality(taskData) {
+    const warnings = [];
+
+    if (!taskData.description || taskData.description.trim() === '') {
+      warnings.push('description 為空');
+    }
+
+    const reqCount = (taskData.requirements || []).length;
+    if (reqCount < 3) {
+      warnings.push(`requirements 僅 ${reqCount} 條（最少 3 條）`);
+    }
+
+    const acCount = (taskData.acceptance_criteria || []).length;
+    if (acCount < 3) {
+      warnings.push(`acceptance_criteria 僅 ${acCount} 條（最少 3 條）`);
+    }
+
+    const tnCount = (taskData.technical_notes || []).length;
+    if (tnCount < 2) {
+      warnings.push(`technical_notes 僅 ${tnCount} 條（最少 2 條）`);
+    }
+
+    return {
+      valid: warnings.length === 0,
+      warnings
+    };
+  }
+
+  // ============================================================================
+  // 核心 API
+  // ============================================================================
+
+  /**
+   * 取得所有任務
+   * @param {Object} options - 可選參數
+   * @param {string} options.format - 輸出格式：'table'（預設）或 'json'
+   */
+  async getAllTasks(options = {}) {
+    const allTasks = await this._scanAllDirs(options.includeArchived || false);
+
+    // archived count: readdir-only (no YAML parse) when not loading archived tasks.
+    // Mirrors route.ts countTaskDirs + Rust manager.rs:917 — total reflects
+    // full project history, but tasks[] stays board-sized so dashboard polling
+    // doesn't parse 1000+ historical files every 5s.
+    let archivedCount = 0;
+    if (!options.includeArchived) {
+      try {
+        const archivedDir = path.join(this.tasksDir, 'archived');
+        const entries = await fs.readdir(archivedDir, { withFileTypes: true });
+        archivedCount = entries.filter(e =>
+          e.isFile() && /^TASK_.*\.ya?ml$/.test(e.name)
+        ).length;
+      } catch { /* archived dir absent → count 0 */ }
+    }
+
+    // 計算統計（使用舊狀態名稱）
+    const statistics = {
+      total: allTasks.length + archivedCount,
+      pending: allTasks.filter(t => t.status === 'pending').length,
+      in_progress: allTasks.filter(t => t.status === 'in_progress').length,
+      completed: allTasks.filter(t => t.status === 'completed').length + archivedCount,
+      blocked: allTasks.filter(t => t.status === 'blocked').length,
+      cancelled: allTasks.filter(t => t.status === 'cancelled').length
+    };
+
+    return {
+      version: CONFIG.API_VERSION,
+      tasks: allTasks,
+      statistics,
+      metadata: {
+        last_updated: new Date().toISOString(),
+        directories: options.includeArchived ? [...CONFIG.STATUS_DIRS, 'archived'] : [...CONFIG.STATUS_DIRS, 'archived (count-only)'],
+        format: options.format || 'table'
+      }
+    };
+  }
+
+  /**
+   * 取得單個任務
+   */
+  async getTask(taskId) {
+    if (!this.validateTaskID(taskId)) {
+      throw new Error(`無效的任務 ID: ${taskId}`);
+    }
+
+    // 在所有目錄中搜尋（含 pool/blocked/cancel/archived）
+    for (const dir of CONFIG.ALL_STATUS_DIRS) {
+      const dirPath = path.join(this.tasksDir, dir);
+
+      try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+
+        for (const entry of entries) {
+          // Match exact task ID: TASK_1_ or TASK_1.yaml, not TASK_10_
+          if (entry.isFile() &&
+              (entry.name.startsWith(taskId + '_') || entry.name.startsWith(taskId + '.')) &&
+              (entry.name.endsWith('.yaml') || entry.name.endsWith('.yml'))) {
+            const filePath = path.join(dirPath, entry.name);
+            const task = await this._loadTaskFile(filePath);
+            // _loadTaskFile returns null for corrupted/unparseable YAML (TASK_1699).
+            // Guard: skip this file (warn) rather than crashing on null.id access.
+            if (!task) {
+              console.error('Warning: skipping corrupted task file (YAML parse failed): ' + filePath);
+              continue;
+            }
+            if (!task.id) task.id = taskId;
+            if (this.projectPath) {
+              task._project_path = this.projectPath;
+            }
+            return task;
+          }
+          // Directory task: TASK_XXX/ (exact match)
+          if (entry.isDirectory() && entry.name === taskId) {
+            const subEntries = await fs.readdir(path.join(dirPath, entry.name));
+            for (const sub of subEntries) {
+              if (sub.endsWith('.yaml') || sub.endsWith('.yml')) {
+                const filePath = path.join(dirPath, entry.name, sub);
+                const task = await this._loadTaskFile(filePath);
+                // _loadTaskFile returns null for corrupted YAML -- warn and skip (TASK_1699)
+                if (!task) {
+                  console.error('Warning: skipping corrupted task file (YAML parse failed): ' + filePath);
+                  continue;
+                }
+                if (!task.id) task.id = taskId;
+                if (this.projectPath) {
+                  task._project_path = this.projectPath;
+                }
+                return task;
+              }
+            }
+          }
+        }
+      } catch (error) {
+        if (error.code !== 'ENOENT') {
+          throw error;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * 建立新任務
+   */
+  _assertTaskWritable(task, taskId) {
+    const missing = [];
+    if (!task || !task.id) missing.push('id');
+    if (!task || !task.title) missing.push('title');
+    if (!task || !task.priority) missing.push('priority');
+    if (missing.length > 0) {
+      throw new Error(`Task file for ${taskId || (task && task.id) || 'unknown'} is incomplete: missing [${missing.join(', ')}]. Refusing to rewrite a corrupted YAML.`);
+    }
+  }
+
+  /**
+   * TASK_1110: Detect parallel scope overlap between a new task and existing
+   * backlog/active tasks. Returns an array of overlapping task descriptors.
+   *
+   * A "parallel conflict" candidate is any existing task in backlog/ or
+   * active/ that shares one or more normalized file paths with the new task.
+   * Paths are extracted from both scope_paths and requirements/description
+   * (any token that looks like a relative file path with an extension).
+   */
+  /**
+   * TASK_1110 / TASK_1758: Detect parallel scope overlap between a new task and existing
+   * backlog/active tasks.
+   *
+   * FIX (TASK_1758): comparison is ONLY on the actual scope_paths field values of each task,
+   * never on text mined from description/requirements prose (which caused "e.g." false positives
+   * observed on 2026-07-20 when TASK_1755/1756 creation reported sharing "e.g" with TASK_1752).
+   *
+   * Paths are normalized (backslash → forward-slash, lowercase on win32) before comparison.
+   */
+  async _detectParallelScopeOverlap(newTask) {
+    const normalizePath = (p) => {
+      if (!p) return '';
+      let s = String(p).split(String.fromCharCode(92)).join('/').trim();
+      if (process.platform === 'win32') s = s.toLowerCase();
+      return s;
+    };
+
+    const extractScopePaths = (task) => {
+      const bag = new Set();
+      for (const sp of (task.scope_paths || [])) {
+        const n = normalizePath(sp);
+        if (n) bag.add(n);
+      }
+      return bag;
+    };
+
+    const newPaths = extractScopePaths(newTask);
+    if (newPaths.size === 0) return [];
+
+    const targets = ['backlog', 'active'];
+    const overlaps = [];
+    for (const dir of targets) {
+      const dirPath = require('path').join(this.tasksDir, dir);
+      let entries;
+      try {
+        entries = await fs.readdir(dirPath, { withFileTypes: true });
+      } catch (e) {
+        if (e.code === 'ENOENT') continue;
+        throw e;
+      }
+      for (const entry of entries) {
+        if (!entry.isFile()) continue;
+        if (!(entry.name.endsWith('.yaml') || entry.name.endsWith('.yml'))) continue;
+        let other;
+        try {
+          other = await this._loadTaskFile(require('path').join(dirPath, entry.name));
+        } catch { continue; }
+        if (!other || !other.id || other.id === newTask.id) continue;
+        const otherPaths = extractScopePaths(other);
+        const shared = [];
+        for (const p of newPaths) {
+          if (otherPaths.has(p)) shared.push(p);
+        }
+        if (shared.length > 0) {
+          overlaps.push({ task_id: other.id, status: dir, shared });
+        }
+      }
+    }
+    return overlaps;
+  }
+
+  _requiresAcceptanceCriteria(taskData = {}) {
+    const codeExtensions = new Set(['.js', '.ts', '.tsx', '.jsx', '.rs', '.py', '.go', '.rb', '.java']);
+    const scopePaths = taskData.scope_paths || taskData.scope || [];
+    return scopePaths.some(scopePath => codeExtensions.has(path.extname(String(scopePath)).toLowerCase()));
+  }
+
+  async createTask(taskData, options = {}) {
+    await this._ensureStatusDirs();
+
+    const acCount = (taskData.acceptance_criteria || []).length;
+    const requiresAcceptanceCriteria = this._requiresAcceptanceCriteria(taskData);
+    if (requiresAcceptanceCriteria && acCount === 0) {
+      if (!options.force) {
+        throw new Error('acceptance_criteria required for code-touching task');
+      }
+      console.warn('WARNING: overriding acceptance_criteria required for code-touching task via --force');
+    }
+
+    // 品質閘門：檢查任務內容是否足夠豐富
+    if (!options.force) {
+      const quality = this.validateTaskQuality(taskData);
+      if (!quality.valid) {
+        const msg = [
+          '❌ 任務品質不足，無法建立：',
+          ...quality.warnings.map(w => `  - ${w}`),
+          '',
+          '提示：補齊欄位後重試，或使用 --force 強制建立'
+        ].join('\n');
+        throw new Error(msg);
+      }
+    }
+
+    const gitUser = this._getGitUser();
+    const now = new Date().toISOString();
+    const taskId = taskData.id || await this.generateTaskID();
+    // Stamp id_alloc when relay fallback was used (set by generateTaskID)
+    const idAllocStamp = (!taskData.id && this._lastIdAlloc === 'local_fallback')
+      ? 'local_fallback' : undefined;
+
+    // 建立任務物件（v3.2 格式）
+    const task = {
+      id: taskId,
+      hash: randomUUID(),  // UUID v4 唯一識別
+      title: taskData.title || '未命名任務',
+      description: taskData.description || '',
+      priority: taskData.priority || 'P2',
+      status: 'pending',  // 新任務預設為 pending（顯示用）
+
+      // 任務分類（v3.2）
+      role: (() => {
+        const r = taskData.role || taskData.agent_type || 'developer';
+        if (r === 'developer' && !taskData.role && !taskData.agent_type) {
+          console.warn('⚠️  role 未指定，自動 fallback 為 developer。建議根據 scope_paths 指定：frontend/backend/sre/qa/designer');
+        }
+        return r;
+      })(),  // 向後相容 agent_type，但警告未指定 role
+      tags: toTokenArray(taskData.tags),
+      complexity: taskData.complexity || 'medium',
+      rigor: taskData.rigor || 'medium',  // 嚴謹度：high 需要 team
+      // TASK_2288: ?? not || — 0 hours is a real value
+      estimated_hours: taskData.estimated_hours ?? null,
+      actual_hours: taskData.actual_hours ?? null,
+      branch: taskData.branch || null,
+
+      // 依賴關係
+      dependencies: toTokenArray(taskData.dependencies),
+
+      // 範圍
+      scope_paths: toTokenArray(taskData.scope_paths != null ? taskData.scope_paths : taskData.scope),
+
+      // 需求和驗收標準
+      requirements: toTextArray(taskData.requirements),
+      acceptance_criteria: toTextArray(taskData.acceptance_criteria),
+
+      // 技術筆記
+      technical_notes: toTextArray(taskData.technical_notes),
+
+      // 人員追蹤（v3.2 簡化版）
+      created_by: {
+        name: gitUser.name,
+        git_user: gitUser.git_user,
+        timestamp: now
+      },
+      executed_by: null
+    };
+
+    // 添加可選欄位
+    if (taskData.source) task.source = taskData.source;
+    if (taskData.feature_ids) task.feature_ids = taskData.feature_ids;
+    if (taskData.related_tasks) task.related_tasks = taskData.related_tasks;
+    if (taskData.keywords) task.keywords = taskData.keywords;
+    if (taskData.notes) task.notes = taskData.notes;
+
+    // verification 欄位（optional）：三層驗證規格
+    // { level_1: string[], level_2: [{endpoint, method, expect}], level_3: {scenario, generates} }
+    if (taskData.verification) task.verification = taskData.verification;
+    if (idAllocStamp) task.id_alloc = idAllocStamp;
+
+    // TASK_1110: parallel scope overlap warning (non-blocking).
+    // When two tasks declare overlapping scope_paths / file references in
+    // requirements, running them in parallel via Formation dispatch produces
+    // a parallel-conflict at merge time (e.g. TASK_1101 + TASK_1102 both
+    // touching identity.yaml → merge fail). Warn the creator so they can
+    // serialize or narrow scope before dispatch. This is advisory only; a
+    // true fix requires worktree rebase-before-merge (tracked separately).
+    try {
+      const overlaps = await this._detectParallelScopeOverlap(task);
+      if (overlaps.length > 0) {
+        console.warn('⚠️  parallel scope overlap detected — running these tasks concurrently may cause merge conflict:');
+        for (const o of overlaps) {
+          console.warn(`   - ${o.task_id} (${o.status}): shares ${o.shared.slice(0, 3).join(', ')}${o.shared.length > 3 ? ` +${o.shared.length - 3} more` : ''}`);
+        }
+        console.warn('   Consider serializing dispatch or narrowing scope_paths. (warning only, task still created)');
+      }
+    } catch (e) {
+      // Never block task creation on overlap detection failure.
+      console.warn(`   (scope-overlap check skipped: ${e.message})`);
+    }
+
+    // 寫入 backlog 目錄（檔名含 title slug + git 短名避免多 agent 撞名）
+    const slug = taskData.title
+      ? '_' + taskData.title.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff]+/g, '_').replace(/^_|_$/g, '').slice(0, 40)
+      : '';
+    const fileName = `${taskId}${slug}_${gitUser.git_user}.yaml`;
+    const filePath = path.join(this.tasksDir, 'backlog', fileName);
+
+    const yamlContent = toYAML(task);
+    await fs.writeFile(filePath, yamlContent);
+    await this._verifyPersisted(filePath, task); // TASK_1864: 落盤 != 意圖 → throw
+
+    task._file_path = filePath;
+    task._status_dir = 'backlog';
+
+    return task;
+  }
+
+  /**
+   * 更新任務
+   */
+  async updateTask(taskId, updates) {
+    const task = await this.getTask(taskId);
+    if (!task) {
+      throw new Error(`任務不存在: ${taskId}`);
+    }
+
+    // TASK_1771: coerce array-typed fields so a raw-string update can never
+    // poison a task (mirrors createTask normalization). Only touch keys the
+    // caller actually provided.
+    if (updates && typeof updates === "object") {
+      updates = { ...updates };
+      for (const k of ["dependencies", "tags", "scope_paths"]) {
+        if (k in updates) updates[k] = toTokenArray(updates[k]);
+      }
+      for (const k of ["requirements", "acceptance_criteria", "technical_notes"]) {
+        if (k in updates) updates[k] = toTextArray(updates[k]);
+      }
+    }
+
+    const gitUser = this._getGitUser();
+
+    // 合併更新
+    const updatedTask = {
+      ...task,
+      ...updates,
+      metadata: {
+        ...task.metadata,
+        updated_at: new Date().toISOString(),
+        updated_by: gitUser.name
+      }
+    };
+
+    const filePath = task._file_path;
+
+    // 檢查是否需要移動目錄
+    const oldStatus = task.status;
+    const newStatus = updates.status || oldStatus;
+
+    if (newStatus !== oldStatus) {
+      // 狀態變更，需要移動檔案 -- moveTask 需要 _file_path/_status_dir 才能定位
+      // 舊檔案並判斷來源狀態，因此這條路徑上不能先移除內部屬性 (TASK_2108)
+      return await this.moveTask(taskId, newStatus, updatedTask);
+    }
+
+    // 僅更新內容：移除內部屬性後再落盤
+    delete updatedTask._file_path;
+    delete updatedTask._status_dir;
+    const yamlContent = toYAML(updatedTask);
+    await fs.writeFile(filePath, yamlContent);
+    await this._verifyPersisted(filePath, updatedTask); // TASK_1864: 落盤 != 意圖 → throw
+
+    updatedTask._file_path = filePath;
+    // TASK_1846：與 _loadTaskFile 共用祖先鏈解析。舊寫法 basename(dirname()) 對
+    // 目錄型卡片（active/TASK_XXX/*.yaml）會把回傳值的 _status_dir 毒化成 'TASK_XXX'。
+    // 垃圾值只污染回傳值，不落 YAML（toYAML 過濾底線鍵 + 寫檔前已 delete）。
+    updatedTask._status_dir = this._resolveStatusDirName(filePath);
+
+    return updatedTask;
+  }
+
+  /**
+   * 移動任務到新狀態目錄（原子操作）
+   */
+  async moveTask(taskId, newStatus, taskData = null, options = {}) {
+    await this._ensureStatusDirs();
+    // TASK_2264: skipHealthAfter = the caller (completeTask) knows post-complete will measure and
+    // save the 'after' snapshot itself, so scheduling a second detached measurement is pure waste.
+    const { skipValidation = false, forceClaim = false, skipHealthAfter = false } = options;
+
+    // 取得任務資料
+    let task = taskData;
+    if (!task) {
+      task = await this.getTask(taskId);
+      if (!task) {
+        throw new Error(`任務不存在: ${taskId}`);
+      }
+    }
+
+    this._assertTaskWritable(task, taskId);
+    const oldFilePath = task._file_path;
+    const oldStatus = task._status_dir;
+
+    // 轉換狀態名稱
+    const targetDir = CONFIG.STATUS_MAP[newStatus] || newStatus;
+    if (!CONFIG.ALL_STATUS_DIRS.includes(targetDir)) {
+      throw new Error(`無效的狀態: ${newStatus}`);
+    }
+
+    // 確保目標目錄存在
+    await fs.mkdir(path.join(this.tasksDir, targetDir), { recursive: true });
+
+    // 狀態機驗證（可跳過）
+    if (!skipValidation && oldStatus && oldStatus !== targetDir) {
+      const validation = this.validateTransition(oldStatus, targetDir);
+      if (!validation.valid) {
+        throw new Error(validation.reason);
+      }
+    }
+
+    // M1 (TASK_1758): acquire claim marker when transitioning TO active (move active path)
+    // claimTask already handles this; this covers direct moveTask(..., 'active') callers.
+    if (targetDir === 'active') {
+      const _prClaim = this._resolveProjectRoot();
+      const claimRes = acquireClaimMarker(taskId, _prClaim, { dispatchPath: null, forceClaim });
+      if (!claimRes.claimed) {
+        if (claimRes.reason === 'owned') {
+          const o = claimRes.owner;
+          throw new Error(
+            'Task ' + taskId + ' is already claimed by session ' + o.owner_session +
+            ' (pid=' + o.owner_pid + ', at ' + o.claimed_at + '). Use --force-claim to override.'
+          );
+        }
+        throw new Error(
+          'Task ' + taskId + ' has an ORPHAN claim marker (dead pid). Resolve manually or use --force-claim.'
+        );
+      }
+    }
+
+    // 更新狀態（使用舊格式）
+    const updatedTask = {
+      ...task,
+      status: CONFIG.REVERSE_STATUS_MAP[targetDir] || targetDir
+    };
+
+    // 移除內部屬性
+    delete updatedTask._file_path;
+    delete updatedTask._status_dir;
+
+    // 計算新檔案路徑
+    // TASK_2260: preserve the card's layout under its status dir. Flat card:
+    // <status>/TASK_X_user.yaml. Directory card: <status>/TASK_X/TASK_X.yaml (+ siblings).
+    // Third callsite of the TASK_1843/1846 family -- uses _resolveStatusDirName's result
+    // (task._status_dir) rather than assuming the file's parent is the status dir.
+    const fileName = path.basename(oldFilePath);
+    const relInStatus = oldStatus ? path.relative(path.join(this.tasksDir, oldStatus), oldFilePath) : fileName;
+    const cardDirName = (path.dirname(relInStatus) !== '.' && !relInStatus.startsWith('..'))
+      ? path.dirname(relInStatus).split(path.sep)[0] : null;
+    const oldCardDir = cardDirName ? path.join(this.tasksDir, oldStatus, cardDirName) : null;
+    const newCardDir = cardDirName ? path.join(this.tasksDir, targetDir, cardDirName) : null;
+    const newFilePath = cardDirName
+      ? path.join(this.tasksDir, targetDir, relInStatus)
+      : path.join(this.tasksDir, targetDir, fileName);
+    const cardDirIsNew = !!newCardDir && newCardDir !== oldCardDir && !fsSync.existsSync(newCardDir);
+
+    // 原子操作：先寫入新位置，確認成功後再刪除舊檔案
+    const yamlContent = toYAML(updatedTask);
+
+    try {
+      // Step 1: 寫入新位置（目錄型卡片：先把整個卡片目錄複製過去，附件才不會被孤立，再覆寫 yaml）
+      if (oldCardDir && newCardDir !== oldCardDir) {
+        await fs.cp(oldCardDir, newCardDir, { recursive: true });
+      }
+      await fs.writeFile(newFilePath, yamlContent);
+
+      // Step 2: 驗證新檔案寫入成功
+      await fs.access(newFilePath);
+
+      // Step 2.5 (TASK_1864): 寫回驗證 — 必須在 Step 3 unlink 之前，
+      // 失敗時舊檔仍在，狀態可回復；throw 會走下方 catch 清掉 newFilePath
+      await this._verifyPersisted(newFilePath, updatedTask);
+
+      // Step 3: 刪除舊檔案（僅當路徑不同時）
+      if (oldFilePath && oldFilePath !== newFilePath) {
+        try {
+          if (oldCardDir && newCardDir !== oldCardDir) await fs.rm(oldCardDir, { recursive: true, force: true });
+          else await fs.unlink(oldFilePath);
+        } catch (error) {
+          if (error.code !== 'ENOENT') {
+            // 刪除失敗但新檔案已存在，記錄警告但不拋出錯誤
+            console.error(`警告: 刪除舊檔案失敗 ${oldFilePath}:`, error.message);
+          }
+        }
+      }
+
+      // Step 4: 清除其他目錄的殘留副本（防止 git 操作還原舊檔案）
+      for (const dir of CONFIG.ALL_STATUS_DIRS) {
+        if (dir === targetDir) continue; // 跳過目標目錄
+        // TASK_2260: sweep both the flat copy and a directory-layout copy (dir/TASK_X/)
+        const residualPath = path.join(this.tasksDir, dir, fileName);
+        try {
+          if (cardDirName) {
+            const residualDir = path.join(this.tasksDir, dir, cardDirName);
+            if (fsSync.existsSync(residualDir)) {
+              await fs.rm(residualDir, { recursive: true, force: true });
+              console.error(`清除殘留: ${dir}/${cardDirName}/`);
+            }
+          }
+          await fs.unlink(residualPath);
+          console.error(`清除殘留: ${dir}/${fileName}`);
+        } catch (error) {
+          if (error.code !== 'ENOENT') {
+            console.error(`警告: 清除殘留失敗 ${residualPath}:`, error.message);
+          }
+          // ENOENT = 檔案不存在，正常情況，靜默忽略
+        }
+      }
+    } catch (error) {
+      // 寫入失敗，嘗試清理
+      try {
+        if (cardDirIsNew) await fs.rm(newCardDir, { recursive: true, force: true });
+        else await fs.unlink(newFilePath);
+      } catch { /* 忽略清理錯誤 */ }
+      throw new Error(`移動任務失敗: ${error.message}`);
+    }
+
+    updatedTask._file_path = newFilePath;
+    updatedTask._status_dir = targetDir;
+
+    // M1 (TASK_1758): release claim marker when task reaches a terminal state
+    const _projectRootForClaim = this._resolveProjectRoot();
+    if (['done', 'blocked', 'cancel'].includes(targetDir)) {
+      releaseClaimMarker(taskId, _projectRootForClaim);
+    }
+
+    // TASK_1861: dispatch-path-agnostic health capture. moveTask is the single choke
+    // point every activation/completion path funnels through (claim → moveTask,
+    // update --status → moveTask, complete → moveTask, bare move). Fire-and-forget
+    // detached child; idempotent only against snapshots that ALREADY exist when the child
+    // starts (it can race a concurrent writer). TASK_2264: completeTask therefore passes
+    // skipHealthAfter when its own in-process postComplete will measure 'after', so that
+    // path is measured exactly once; paths with no post-complete (bare move, update --status,
+    // complete --skip-post-complete) keep this capture as their only one.
+    if (targetDir === 'active') {
+      scheduleHealthSnapshotCapture(taskId, 'before', _projectRootForClaim);
+    } else if (targetDir === 'done' && !skipHealthAfter) {
+      scheduleHealthSnapshotCapture(taskId, 'after', _projectRootForClaim);
+    }
+
+    // Yggdrasil: sync status change to kenaz_tasks
+    const sync = getTaskSync();
+    if (sync) {
+      sync.syncTaskStatus({
+        taskId,
+        status: CONFIG.REVERSE_STATUS_MAP[targetDir] || targetDir,
+        projectPath: this.projectPath,
+      }).catch(() => {});
+    }
+
+    // TASK_2142 R2: push status to the Task Pool relay row (only when this
+    // card originated from the pool -- see pool-status-push.js's
+    // poolOriginOf(); silent no-op otherwise). Fire-and-forget, best-effort:
+    // never awaited into a throw path, and pushPoolStatus() itself never
+    // rejects, so this can never fail moveTask().
+    getPoolStatusPush().pushPoolStatus({
+      targetDir,
+      task: updatedTask,
+      fullYaml: yamlContent,
+      projectPath: this.projectPath,
+    }).catch(() => {});
+
+    return updatedTask;
+  }
+
+  /**
+   * 刪除任務
+   */
+  async deleteTask(taskId) {
+    const task = await this.getTask(taskId);
+    if (!task) {
+      return false;
+    }
+
+    await fs.unlink(task._file_path);
+    return true;
+  }
+
+  /**
+   * 認領任務（移動到 active）
+   */
+  /**
+   * 認領任務（移動到 active）
+   * M1 (TASK_1758): acquires wx claim marker before moving.
+   * Worker context (no current_stream.json): skip marker, behave as before.
+   */
+  async claimTask(taskId, assignee = null, opts = {}) {
+    const currentUser = this._getGitUser();
+    const now = new Date().toISOString();
+
+    const task = await this.getTask(taskId);
+    if (!task) {
+      throw new Error('任務不存在: ' + taskId);
+    }
+
+    // M1: acquire claim marker (wx atomic — no TOCTOU)
+    const projectRoot = this._resolveProjectRoot();
+    const claimResult = acquireClaimMarker(taskId, projectRoot, {
+      dispatchPath: task._file_path,
+      forceClaim: opts.forceClaim,
+    });
+    if (!claimResult.claimed) {
+      if (claimResult.reason === 'owned') {
+        const o = claimResult.owner;
+        throw new Error(
+          'Task ' + taskId + ' is already claimed by session ' + o.owner_session +
+          ' (pid=' + o.owner_pid + ', at ' + o.claimed_at + '). ' +
+          'Use --force-claim to override an orphan (dead-pid) marker.'
+        );
+      }
+      // orphan — warning already printed; refuse
+      throw new Error(
+        'Task ' + taskId + ' has an ORPHAN claim marker (dead pid). ' +
+        'Resolve manually or use --force-claim to override.'
+      );
+    }
+
+    // M3 (TASK_1760): theme advisory — non-blocking one-liner when another live stream's
+    // declared theme matches this task's scope_paths better than own stream's theme.
+    try {
+      const _slPath2 = require('path').join(projectRoot, '.specialist', 'tools', 'stream-lease.js');
+      if (require('fs').existsSync(_slPath2)) {
+        const _sl2 = require(_slPath2);
+        const _allLeases2 = _sl2.readAllLeases();
+        const _ownLease2 = _sl2.readLease(_claimContext(projectRoot).streamId);
+        const _ownTheme2 = _ownLease2 ? (_ownLease2.theme || '') : '';
+        const _taskScope = Array.isArray(task.scope_paths) ? task.scope_paths.join(' ') : '';
+        if (_taskScope) {
+          const _candidates = _allLeases2.filter(function(l) {
+            return l.session_id !== (_ownLease2 && _ownLease2.session_id) &&
+                   _sl2.isSessionLive(l) && l.theme && l.theme.length > 0;
+          });
+          const _ownScore = _ownTheme2 ? (_taskScope.toLowerCase().includes(_ownTheme2.toLowerCase()) ? 1 : 0) : 0;
+          for (const _cl of _candidates) {
+            const _score = _taskScope.toLowerCase().includes(_cl.theme.toLowerCase()) ? 1 : 0;
+            if (_score > _ownScore) {
+              console.warn('[theme-advisory] ' + (_cl.label || _cl.session_id.slice(0,8)) +
+                ' (theme=' + _cl.theme + ') may be a better fit for ' + taskId +
+                '; proceeding with claim anyway.');
+              break;
+            }
+          }
+        }
+      }
+    } catch (e) { /* advisory best-effort — never block claim */ }
+    // 更新分配資訊
+    const updatedTask = {
+      ...task,
+      assigned_to: {
+        name: assignee || currentUser.name,
+        git_user: assignee || currentUser.git_user,
+        timestamp: now
+      },
+      metadata: {
+        ...task.metadata,
+        claimed_at: now,
+        claimed_by: currentUser.name
+      }
+    };
+
+    const result = await this.moveTask(taskId, 'active', updatedTask);
+
+    // Yggdrasil: sync claimed task to kenaz_tasks
+    const sync = getTaskSync();
+    if (sync) {
+      sync.syncTaskStatus({
+        taskId,
+        status: 'active',
+        claimedBy: currentUser.name,
+        priority: task.priority,
+        scopePaths: task.scope_paths,
+        title: task.title,
+        dependencies: task.dependencies,
+        projectPath: this.projectPath,
+      }).catch(() => {});
+    }
+
+    return result;
+  }
+
+  /**
+   * 完成任務（移動到 done）
+   * @param {string} taskId - 任務 ID
+   * @param {Object} options - 可選參數
+   * @param {number} options.actual_hours - 實際花費時間（小時）
+   * @param {boolean} options.skipPostComplete - 跳過 post-complete 流程（預設 false）
+   */
+  async completeTask(taskId, options = {}) {
+    const gitUser = this._getGitUser();
+    const now = new Date().toISOString();
+
+    const task = await this.getTask(taskId);
+    if (!task) {
+      throw new Error(`任務不存在: ${taskId}`);
+    }
+
+    // TASK_2233: backlog → done is not an allowed transition; say what to do instead
+    if (task.status === 'backlog' || task.status === 'pending' || task._status_dir === 'backlog') {
+      throw new Error(`無法從 backlog 直接完成 ${taskId}: move it to active first (node task-api.js move ${taskId} active), then complete.`);
+    }
+
+    const updatedTask = {
+      ...task,
+      executed_by: {
+        name: gitUser.name,
+        git_user: gitUser.git_user,
+        timestamp: now
+      }
+    };
+
+    // 設置實際工時（如果提供）
+    if (options.actual_hours !== undefined) {
+      updatedTask.actual_hours = options.actual_hours;
+    }
+
+    // TASK_2264: decide up front whether post-complete (below) will measure 'after' in-process.
+    // TASK_2288 single-winner rule: whenever a post-complete run is expected for this completion,
+    // post-complete's own measurement is the ONE 'after' capture (it runs after merge and feeds the
+    // verdict), so moveTask must not also spawn one. Expected = in-process (below) OR the caller
+    // (headless.js / scheduler, signalled by FORMATION_HEADLESS / FORMATION_SCHEDULER) runs it itself.
+    // moveTask's detached capture stays the sole one only when nobody measures: --skip-post-complete.
+    const postCompleteRuns = !options.skipPostComplete;
+    const result = await this.moveTask(taskId, 'done', updatedTask, { skipHealthAfter: postCompleteRuns });
+
+    try {
+      this._autoPopThoughtsForCompletedTask(taskId, now);
+    } catch (error) {
+      console.error(`Warning: thought stack cleanup failed for ${taskId}: ${error.message}`);
+    }
+
+    // Yggdrasil: sync completed task to kenaz_tasks
+    const sync = getTaskSync();
+    if (sync) {
+      sync.syncTaskStatus({
+        taskId,
+        status: 'done',
+        claimedBy: null,
+        projectPath: this.projectPath,
+      }).catch(() => {});
+    }
+
+    // 自動執行 post-complete（除非明確跳過）
+    // - FORMATION_SCHEDULER: 由 scheduler 統一管理，避免重複執行
+    // - FORMATION_HEADLESS: 由 headless.js onDone 統一執行，避免並行 agent git 衝突
+    if (postCompleteRuns) {
+      try {
+        const { postComplete } = require('../../.formation/tools/post-complete.js');
+        console.log(`\n🔗 自動執行 post-complete for ${taskId}...\n`);
+        await postComplete({
+          taskId,
+          keep: options.keep || 10,
+          skipArchive: options.skipArchive || false,
+          skipGit: options.skipGit || false,
+          dryRun: options.dryRun || false,
+          message: options.message,
+          projectPath: this.projectPath,
+        });
+      } catch (error) {
+        console.error(`⚠️  post-complete 失敗: ${error.message}`);
+        console.error('   任務已完成，但 post-complete 需要手動執行');
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * 查詢任務
+   */
+  async queryTasks(query = {}) {
+    const queryDir = query.status ? (CONFIG.STATUS_MAP[query.status] || query.status) : null;
+    const includeArchived = query.includeArchived || queryDir === 'archived';
+    const allData = await this.getAllTasks({ includeArchived });
+    let tasks = allData.tasks;
+
+    if (query.status) {
+      // Allow both old status names ('completed') and new dir names ('done', 'active', etc.)
+      const targetDir = CONFIG.STATUS_MAP[query.status] || query.status;
+      tasks = tasks.filter(t => t.status === query.status || t._status_dir === targetDir);
+    }
+
+    // Exclude done tasks where merge_landed=false (quarantine unverified completions)
+    // Pass includeUnmerged:true to opt-in to the full set
+    if (!query.includeUnmerged) {
+      tasks = tasks.filter(t => t._status_dir !== 'done' || t.merge_landed !== false);
+    }
+
+    if (query.priority) {
+      tasks = tasks.filter(t => t.priority === query.priority);
+    }
+
+    // 支持 role（新）和 agent_type（舊，向後相容）
+    if (query.role || query.agent_type) {
+      const targetRole = query.role || query.agent_type;
+      tasks = tasks.filter(t => (t.role || t.agent_type) === targetRole);
+    }
+
+    // 支持 rigor 過濾
+    if (query.rigor) {
+      tasks = tasks.filter(t => t.rigor === query.rigor);
+    }
+
+    // 支持 tags 過濾（任一匹配）
+    if (query.tags && query.tags.length > 0) {
+      const targetTags = Array.isArray(query.tags) ? query.tags : [query.tags];
+      tasks = tasks.filter(t => {
+        const taskTags = t.tags || [];
+        return targetTags.some(tag => taskTags.includes(tag));
+      });
+    }
+
+    // 文字搜尋
+    if (query.search) {
+      const searchLower = query.search.toLowerCase();
+      tasks = tasks.filter(t => {
+        const title = (t.title || '').toLowerCase();
+        const desc = (t.description || '').toLowerCase();
+        const id = (t.id || '').toLowerCase();
+        const tags = (t.tags || []).join(' ').toLowerCase();
+        return title.includes(searchLower) || desc.includes(searchLower) || id.includes(searchLower) || tags.includes(searchLower);
+      });
+    }
+
+    return tasks;
+  }
+
+  /**
+   * TASK_895: Thalamus Fire → Task Priority Auto-Boost
+   *
+   * Cross-reference fired symbols with backlog task scope_paths.
+   * When a symbol fires 3+ times and its file_path matches a task's scope_path
+   * (prefix match), boost that task's priority by one level.
+   *
+   * @param {Array<{symbolId: string, fireCount: number}>} firedSymbols
+   * @returns {{ boosted: Array<{taskId: string, from: string, to: string}>, skipped: number }}
+   */
+  async boostByFiredSymbols(firedSymbols) {
+    const PRIORITY_ORDER = ['P3', 'P2', 'P1', 'P0'];
+    const results = { boosted: [], skipped: 0 };
+
+    if (!firedSymbols || firedSymbols.length === 0) return results;
+
+    // Filter to symbols with fire_count >= 2 (lowered from 3 — 2 fires in quick
+    // succession indicates sustained attention, worth boosting related tasks)
+    const eligible = firedSymbols.filter(s => s.fireCount >= 2);
+    if (eligible.length === 0) return results;
+
+    // Extract file_paths from symbol_ids (format: "file::name" → "file")
+    const firedFilePaths = eligible.map(s => {
+      const parts = s.symbolId.split('::');
+      return parts.length > 1 ? parts[0] : s.symbolId;
+    });
+
+    // List backlog tasks
+    const backlogTasks = await this.queryTasks({ status: 'pending' });
+
+    for (const task of backlogTasks) {
+      // Skip tasks already boosted by thalamus
+      const tags = task.tags || [];
+      if (tags.includes('thalamus-boosted')) {
+        results.skipped++;
+        continue;
+      }
+
+      const scopePaths = task.scope_paths || [];
+      if (scopePaths.length === 0) continue;
+
+      // Check if any fired file_path matches any task scope_path (prefix match)
+      const hasMatch = firedFilePaths.some(filePath =>
+        scopePaths.some(scopePath => {
+          // Normalize separators for cross-platform matching
+          const normFile = filePath.replace(/\\/g, '/');
+          const normScope = scopePath.replace(/\\/g, '/');
+          return normFile.startsWith(normScope) || normScope.startsWith(normFile);
+        })
+      );
+
+      if (!hasMatch) continue;
+
+      // Compute boosted priority
+      const currentPriority = task.priority || 'P2';
+      const currentIndex = PRIORITY_ORDER.indexOf(currentPriority);
+      if (currentIndex < 0 || currentIndex === PRIORITY_ORDER.length - 1) {
+        // Already P0 or unknown priority — skip
+        results.skipped++;
+        continue;
+      }
+
+      const newPriority = PRIORITY_ORDER[currentIndex + 1]; // P3→P2, P2→P1, P1→P0
+
+      // Update task: boost priority + add thalamus-boosted tag
+      const updatedTags = [...tags, 'thalamus-boosted'];
+      await this.updateTask(task.id, {
+        priority: newPriority,
+        tags: updatedTags,
+      });
+
+      results.boosted.push({
+        taskId: task.id,
+        from: currentPriority,
+        to: newPriority,
+      });
+    }
+
+    return results;
+  }
+
+  /**
+   * Reload: 確保目錄結構存在 + 遷移舊系統任務到新系統
+   *
+   * 1. 建立所有 status 目錄
+   * 2. 掃描舊系統 dev/pipeline/ 的任務
+   * 3. 將尚未存在於新系統的任務遷移過來
+   *
+   * @returns {{ created_dirs: string[], migrated: number, skipped: number, errors: string[] }}
+   */
+  async reload() {
+    const stats = { created_dirs: [], migrated: 0, skipped: 0, errors: [] };
+    const fsSync = require('fs');
+
+    // 1. 確保所有目錄存在
+    for (const dir of CONFIG.ALL_STATUS_DIRS) {
+      const dirPath = path.join(this.tasksDir, dir);
+      if (!fsSync.existsSync(dirPath)) {
+        await fs.mkdir(dirPath, { recursive: true });
+        stats.created_dirs.push(dir);
+      }
+    }
+
+    // 2. 收集新系統中已有的 task ID
+    const existingIds = new Set();
+    for (const dir of CONFIG.ALL_STATUS_DIRS) {
+      const dirPath = path.join(this.tasksDir, dir);
+      try {
+        const entries = await fs.readdir(dirPath);
+        for (const entry of entries) {
+          if (entry.startsWith('TASK_') && entry.endsWith('.yaml')) {
+            const id = entry.split('_').slice(0, 2).join('_');
+            existingIds.add(id);
+          }
+        }
+      } catch { /* dir doesn't exist yet */ }
+    }
+
+    // 3. 掃描舊系統
+    const projectRoot = this._resolveProjectRoot();
+    const pipelineDir = path.join(projectRoot, 'dev', 'pipeline');
+
+    // 3a. dev/pipeline/tasks/*.yaml → backlog/
+    const legacyTasksDir = path.join(pipelineDir, 'tasks');
+    if (fsSync.existsSync(legacyTasksDir)) {
+      try {
+        const files = await fs.readdir(legacyTasksDir);
+        for (const file of files) {
+          if (!file.startsWith('TASK_') || !file.endsWith('.yaml')) continue;
+          const id = file.split('_').slice(0, 2).join('_');
+          if (existingIds.has(id)) {
+            stats.skipped++;
+            continue;
+          }
+          try {
+            const src = path.join(legacyTasksDir, file);
+            const dst = path.join(this.tasksDir, 'backlog', file);
+            await fs.copyFile(src, dst);
+            existingIds.add(id);
+            stats.migrated++;
+          } catch (e) {
+            stats.errors.push(`${file}: ${e.message}`);
+          }
+        }
+      } catch { /* ignore */ }
+    }
+
+    // 3b. dev/pipeline/completed/*.yaml → done/
+    const legacyCompletedDir = path.join(pipelineDir, 'completed');
+    if (fsSync.existsSync(legacyCompletedDir)) {
+      try {
+        const files = await fs.readdir(legacyCompletedDir);
+        for (const file of files) {
+          if (!file.startsWith('TASK_') || !file.endsWith('.yaml')) continue;
+          const id = file.split('_').slice(0, 2).join('_');
+          if (existingIds.has(id)) {
+            stats.skipped++;
+            continue;
+          }
+          try {
+            const src = path.join(legacyCompletedDir, file);
+            const dst = path.join(this.tasksDir, 'done', file);
+            await fs.copyFile(src, dst);
+            existingIds.add(id);
+            stats.migrated++;
+          } catch (e) {
+            stats.errors.push(`${file}: ${e.message}`);
+          }
+        }
+      } catch { /* ignore */ }
+    }
+
+    // 3c. TASK_QUEUE.json — 將 JSON 條目轉為 YAML 檔案
+    const queueFile = path.join(pipelineDir, 'TASK_QUEUE.json');
+    if (fsSync.existsSync(queueFile)) {
+      try {
+        const content = await fs.readFile(queueFile, 'utf8');
+        const cleanContent = content.charCodeAt(0) === 0xFEFF ? content.slice(1) : content;
+        const queue = JSON.parse(cleanContent);
+        if (Array.isArray(queue.tasks)) {
+          for (const task of queue.tasks) {
+            if (!task.id || existingIds.has(task.id)) {
+              stats.skipped++;
+              continue;
+            }
+            try {
+              const status = (task.status || '').toLowerCase();
+              const isCompleted = status === 'completed' || status === 'done';
+              const targetDir = isCompleted ? 'done' : 'backlog';
+              const gitUser = task.assigned_agent || 'system';
+              const fileName = `${task.id}_${gitUser}.yaml`;
+              const dst = path.join(this.tasksDir, targetDir, fileName);
+              const yamlContent = toYAML(task);
+              await fs.writeFile(dst, yamlContent);
+              existingIds.add(task.id);
+              stats.migrated++;
+            } catch (e) {
+              stats.errors.push(`${task.id}: ${e.message}`);
+            }
+          }
+        }
+      } catch { /* ignore */ }
+    }
+
+    // 4. 子專案 .collaboration/tasks/ → .kenaz/tasks/ 遷移
+    //    當 tasksDir 是 .kenaz/tasks/ 時，檢查同專案是否有 .collaboration/tasks/
+    const collabTasksDir = path.join(projectRoot, '.collaboration', 'tasks');
+    if (this.tasksDir.includes('.kenaz') && fsSync.existsSync(collabTasksDir) && collabTasksDir !== this.tasksDir) {
+      // 狀態目錄映射：.collaboration/ dir name → .kenaz/ dir name（相同）
+      for (const statusDir of CONFIG.ALL_STATUS_DIRS) {
+        const srcDir = path.join(collabTasksDir, statusDir);
+        if (!fsSync.existsSync(srcDir)) continue;
+        try {
+          const files = await fs.readdir(srcDir);
+          for (const file of files) {
+            if (!file.startsWith('TASK_') || !file.endsWith('.yaml')) continue;
+            const id = file.split('_').slice(0, 2).join('_');
+            if (existingIds.has(id)) {
+              stats.skipped++;
+              continue;
+            }
+            try {
+              const src = path.join(srcDir, file);
+              const dst = path.join(this.tasksDir, statusDir, file);
+              await fs.copyFile(src, dst);
+              existingIds.add(id);
+              stats.migrated++;
+            } catch (e) {
+              stats.errors.push(`${file}: ${e.message}`);
+            }
+          }
+        } catch { /* ignore */ }
+      }
+    }
+
+    return stats;
+  }
+
+  /**
+   * 取得統計資訊
+   */
+  async getStatistics(options = {}) {
+    const allData = await this.getAllTasks({ includeArchived: options.includeArchived || false });
+    const tasks = allData.tasks;
+
+    // 按狀態統計
+    const byStatus = {};
+    for (const task of tasks) {
+      const status = task.status || 'unknown';
+      byStatus[status] = (byStatus[status] || 0) + 1;
+    }
+
+    // 按優先級統計
+    const byPriority = {};
+    for (const task of tasks) {
+      const priority = task.priority || 'unknown';
+      byPriority[priority] = (byPriority[priority] || 0) + 1;
+    }
+
+    // 按 role 統計（向後相容 agent_type）
+    const byRole = {};
+    for (const task of tasks) {
+      const role = task.role || task.agent_type || 'unknown';
+      byRole[role] = (byRole[role] || 0) + 1;
+    }
+
+    // 按 tags 統計
+    const byTags = {};
+    for (const task of tasks) {
+      const tags = task.tags || [];
+      for (const tag of tags) {
+        byTags[tag] = (byTags[tag] || 0) + 1;
+      }
+    }
+
+    return {
+      total: tasks.length,
+      byStatus,
+      byPriority,
+      byRole,
+      byTags,
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+
+// ============================================================================
+// TASK_1992/TASK_2104 — Alaya process-lessons echo (best-effort, create-only)
+// ============================================================================
+// Mirrors prompt.js's appendAlayaLessons: same query, same alaya_recall
+// shape, and (TASK_2104) the same TASK_2101 cosine-floor + stack-match
+// gate — loaded from the dependency-free .formation/tools/alaya-gate.js
+// module (require() resolved relative to __dirname; GEN-008) instead of
+// the hand-copied query builder that used to live here with no gate at all.
+// Never affects create's exit code: any failure is swallowed silently.
+// Opt-out: KENAZ_NO_ALAYA_ECHO=1.
+
+// Best-effort: null (not a throw) when unavailable — e.g. a sub-project
+// with no .formation/ checkout — so the caller prints nothing rather than
+// falling back to ungated results.
+function loadAlayaGate() {
+  try {
+    return require('../../.formation/tools/alaya-gate');
+  } catch {
+    return null;
+  }
+}
+
+// fetchImpl/gateImpl: injectable test seams; default to the real fetch and loadAlayaGate().
+async function echoAlayaLessons(taskData, fetchImpl, gateImpl) {
+  if (process.env.KENAZ_NO_ALAYA_ECHO === '1') return;
+
+  const doFetch = fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+  if (!doFetch) return;
+
+  const gate = gateImpl !== undefined ? gateImpl : loadAlayaGate();
+  if (!gate) return; // shared gate unavailable — never print ungated results
+
+  const query = gate.buildTaskContextQuery(taskData);
+  if (!query) return;
+
+  const taskStack = gate.deriveTaskStack((taskData && taskData.scope_paths) || []);
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 3000);
+  try {
+    const payload = JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'tools/call',
+      params: {
+        name: 'alaya_recall',
+        arguments: {
+          query, mode: 'hybrid', seed_types: ['failure_seed', 'lesson_seed'],
+          limit: gate.ALAYA_CANDIDATE_POOL, min_cosine: gate.ALAYA_MIN_COSINE_DEFAULT,
+        },
+      },
+    });
+    const res = await doFetch('http://127.0.0.1:18080/api/mcp', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Accept': 'application/json, text/event-stream' },
+      body: payload,
+      signal: controller.signal,
+    });
+    if (!res || !res.ok) return;
+    const result = await res.json();
+    if (!result || result.error) return;
+
+    const content = result.result && result.result.content;
+    if (!content || !Array.isArray(content)) return;
+    const textPart = content.find(c => c.type === 'text');
+    if (!textPart || !textPart.text) return;
+
+    let recallData;
+    try { recallData = JSON.parse(textPart.text); } catch { return; }
+    if (!recallData) return;
+
+    let bijas = recallData.bijas || [];
+    if (bijas.length === 0) return;
+
+    bijas = gate.dedupBijas(bijas);
+    // TASK_2104: same relevance gate as prompt.js's appendAlayaLessons —
+    // the server already applied min_cosine, but re-checking (+ the
+    // stack-match half, which the server does not apply) keeps this
+    // correct against a stub/older server and drops stack mismatches.
+    bijas = bijas.filter(b => gate.passesAlayaRelevanceGate(b, taskStack, gate.ALAYA_MIN_COSINE_DEFAULT)).slice(0, 3);
+    if (bijas.length === 0) return;
+
+    console.log('   Alaya lessons for this card:');
+    for (const b of bijas) {
+      const preview = (b.content || '').replace(/\s+/g, ' ').trim().slice(0, 160);
+      console.log(`   - [${b.seed_type || 'seed'}/${b.origin || 'unknown'}] ${preview}`);
+    }
+  } catch {
+    // Best-effort: MCP down, timeout, network error, malformed response — silent.
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+// TASK_2257: estimated_hours is a finite number >= 0 or null. '' (flag present, empty value)
+// CLEARS the field (null) -- same "clearable" contract as --description/--notes. Anything
+// non-numeric or negative exits 1 instead of persisting NaN / a nonsense value.
+function parseEstimatedHours(raw, source) {
+  if (raw === null || raw === undefined) return undefined;
+  const text = String(raw).trim();
+  if (text === '') return null;
+  const n = Number(text);
+  if (!Number.isFinite(n) || n < 0) {
+    console.error(`❌ ${source}: estimated hours must be a number >= 0 (got "${text}"); pass an empty value to clear.`);
+    process.exit(1);
+  }
+  return n;
+}
+
+// ============================================================================
+// CLI 入口
+// ============================================================================
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  // Extract --project-path before creating API instance
+  // Supports both: --project-path PATH and --project-path=PATH
+  let cliProjectPath = null;
+  const projectPathIndex = args.indexOf('--project-path');
+  if (projectPathIndex >= 0 && args[projectPathIndex + 1]) {
+    cliProjectPath = args[projectPathIndex + 1];
+    args.splice(projectPathIndex, 2);
+  } else {
+    const eqIndex = args.findIndex(a => a.startsWith('--project-path='));
+    if (eqIndex >= 0) {
+      cliProjectPath = args[eqIndex].split('=').slice(1).join('=');
+      args.splice(eqIndex, 1);
+    }
+  }
+
+  // TASK_2221: Extract --tasks-dir the same way. "Explicit tasksDir always
+  // wins" in resolveTasksDir() -- this lets a caller that already resolved
+  // the directory itself (e.g. inbox.rs's mother self-heal, which checks
+  // orphans against a tasks_dir BEFORE calling create) force this process
+  // to write into that exact same directory instead of letting this
+  // process independently re-derive one from --project-path, which is a
+  // SEPARATE resolution that can land somewhere else (see inbox.rs's
+  // resolve_tasks_dir doc comment for the 2026-10-02T16:18Z incident this
+  // closes).
+  let cliTasksDir = null;
+  const tasksDirIndex = args.indexOf('--tasks-dir');
+  if (tasksDirIndex >= 0 && args[tasksDirIndex + 1]) {
+    cliTasksDir = args[tasksDirIndex + 1];
+    args.splice(tasksDirIndex, 2);
+  } else {
+    const eqIndex = args.findIndex(a => a.startsWith('--tasks-dir='));
+    if (eqIndex >= 0) {
+      cliTasksDir = args[eqIndex].split('=').slice(1).join('=');
+      args.splice(eqIndex, 1);
+    }
+  }
+
+  const apiConfig = {};
+  if (cliProjectPath) apiConfig.projectPath = cliProjectPath;
+  if (cliTasksDir) apiConfig.tasksDir = cliTasksDir;
+  const api = new TaskAPI(apiConfig);
+
+  (async () => {
+    try {
+      if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+        console.log(`
+任務 API v3.5
+
+用法:
+  node task-api.js [--project-path PATH] <command> [options]
+
+全域選項:
+  --project-path PATH    指定專案根目錄（自動偵測 .kenaz/tasks 或 .collaboration/tasks）
+  --tasks-dir PATH       直接指定 tasks 目錄（優先於 --project-path 的自動偵測；TASK_2221）
+
+Commands:
+  node task-api.js list [--status STATUS] [--priority P] [--role ROLE] [--rigor RIGOR] [--tags TAG] [--format json|table] [--include-unmerged] [--no-cancel]
+  node task-api.js get TASK_ID
+  node task-api.js create --title TITLE [options]
+  node task-api.js update TASK_ID [--title T] [--description D] [--priority P] [--role R] [--technical-notes N]...
+    陣列欄位（tags/dependencies/scope-paths/requirements/acceptance-criteria/technical-notes 等）
+    預設為整組取代（會回顯被移除的既有項目）；加 --append 改為追加到既有項目之後（與既有重複的項目會略過並回顯）
+  node task-api.js claim TASK_ID
+  node task-api.js complete TASK_ID [--actual-hours HOURS]
+  node task-api.js move TASK_ID STATUS [--force]
+  node task-api.js delete TASK_ID              (僅限 backlog 狀態)
+  node task-api.js search KEYWORD
+  node task-api.js stats [--format json|table]
+  node task-api.js reload
+  node task-api.js archive [--keep N] [--dry-run]
+  node task-api.js reset-all [--from active,done] [--dry-run]
+  node task-api.js migrate-merge-landed    (one-shot: annotate unmerged tasks in done/)
+
+角色 (role):
+  designer, developer, frontend, pm, sre, team_developer, team_strategy
+
+標籤 (tags):
+  doc, code, plan, fix, refactor, test, design, review
+
+嚴謹度 (rigor):
+  high   - 需要 team 執行（多 Agent 協作）
+  medium - 可選 team 或單一 Agent
+  low    - 單一 Agent 即可
+
+狀態:
+  backlog (pending)    - 待處理
+  active (in_progress) - 進行中
+  done (completed)     - 已完成
+  blocked              - 阻塞中
+  cancel (cancelled)   - 已取消
+
+狀態轉換規則:
+  backlog → active, cancel, blocked
+  active  → done, blocked, cancel, backlog
+  blocked → active, backlog, cancel
+  done    → backlog（重新開啟）
+  cancel  → backlog（重新開啟）
+
+Create 選項:
+  --title TEXT              標題（--args-file 未提供 title 時必填；若兩者皆有，CLI 旗標優先，並會印出警告）
+  --description TEXT        描述
+  --priority P0|P1|P2|P3   優先級（預設 P2）
+  --role ROLE              角色（預設 developer）
+  --rigor high|medium|low  嚴謹度（預設 medium）
+  --complexity simple|medium|complex  複雜度（預設 medium）
+  --tags TAG1,TAG2         標籤（逗號分隔）
+  --dependencies TASK_X,TASK_Y  依賴任務（逗號分隔）
+  --scope-paths PATH1,PATH2    修改範圍（逗號分隔）
+  --requirements "R1" --requirements "R2"  需求（每條重複旗標，最少 3 條）
+  --acceptance-criteria "A1" --acceptance-criteria "A2"  驗收標準（每條重複旗標，最少 3 條）
+  --technical-notes "T1" --technical-notes "T2"  技術備註（每條重複旗標，最少 2 條）
+  --args-file PATH         UTF-8 JSON 物件；支援 camelCase / snake_case，CLI 旗標優先
+                           requirements / acceptance_criteria / technical_notes 使用 JSON 陣列
+                           一般品質門檻：requirements >= 3，acceptance_criteria >= 3，technical_notes >= 2
+  --estimated-hours N      預估工時（小時）
+  --branch NAME            Git 分支
+  --notes TEXT             備註
+  --feature-ids F1,F2      Feature ID（逗號分隔）
+  --keywords K1,K2         關鍵字（逗號分隔）
+  --source NAME            來源標記（寫入 task.source；--origin 為同義旗標，TASK_2147 producer 用）
+  --verification JSON      三層驗證規格（JSON 字串）
+                           格式: {"level_1":["cmd1","cmd2"],"level_2":[{"endpoint":"/health","method":"GET","expect":200}],"level_3":{"scenario":"描述","generates":"playwright/spec.ts"}}
+                           level_1: commands array（CLI 驗證指令）
+                           level_2: API probe specs（{endpoint, method, expect}）
+                           level_3: Playwright scenario（{scenario, generates}）
+
+多專案範例:
+  node task-api.js --project-path /path/to/subproject list
+  node task-api.js --project-path /path/to/subproject get TASK_1
+  node task-api.js --project-path /path/to/subproject create --title "New feature"
+
+範例:
+  node task-api.js list
+  node task-api.js list --status pending --role developer --rigor high --tags code
+  node task-api.js list --tags doc --format json
+  node task-api.js get TASK_171
+  node task-api.js create --title "實作登入功能" --priority P1 --role frontend --rigor high --tags code,doc
+  node task-api.js create --title "系統文檔" --priority P1 --scope-paths ".system/" --dependencies TASK_192,TASK_193 --estimated-hours 0.5
+  node task-api.js claim TASK_171
+  node task-api.js complete TASK_171 --actual-hours 3.5
+  node task-api.js move TASK_171 active
+  node task-api.js search "登入"
+  node task-api.js stats
+  node task-api.js stats --format json
+        `);
+        process.exit(0);
+      }
+
+      const command = args[0];
+
+      if (command === 'worktrees') {
+        // TASK_2297: list worktrees with reclaim eligibility; --reclaim removes eligible ones (manual path).
+        const wr = require(path.join(__dirname, '..', '..', '.formation', 'tools', 'worktree-reclaim.js'));
+        const wtRepo = path.resolve(cliProjectPath || process.cwd());
+        if (args.includes('--reclaim')) {
+          const r = wr.reclaimAllEligible(wtRepo);
+          console.log(`reclaimed ${r.reclaimed.length} worktree(s)`);
+        } else {
+          console.log(wr.formatReport(wr.evaluateWorktrees(wtRepo)));
+        }
+      } else if (command === 'list') {
+        const query = {};
+        const statusIndex = args.indexOf('--status');
+        const priorityIndex = args.indexOf('--priority');
+        const roleIndex = args.indexOf('--role');
+        const rigorIndex = args.indexOf('--rigor');
+        const tagsIndex = args.indexOf('--tags');
+        const formatIndex = args.indexOf('--format');
+
+        if (statusIndex >= 0) query.status = args[statusIndex + 1];
+        if (priorityIndex >= 0) query.priority = args[priorityIndex + 1];
+        if (roleIndex >= 0) query.role = args[roleIndex + 1];
+        if (rigorIndex >= 0) query.rigor = args[rigorIndex + 1];
+        if (tagsIndex >= 0) query.tags = args[tagsIndex + 1].split(',').map(t => t.trim());
+
+        const format = formatIndex >= 0 ? args[formatIndex + 1] : 'table';
+        const showAll = args.includes('--all');
+        const includeArchived = args.includes('--include-archived');
+        const includeUnmerged = args.includes('--include-unmerged');
+        // --no-cancel: omit the per-task list under cancel/ (count still shown in summary).
+        // Cancel rows are mostly historical noise — Phase 0 boot uses this to save context tokens.
+        const skipCancel = args.includes('--no-cancel');
+        const hasStatusFilter = !!query.status;
+
+        // Parse --limit=N or --limit N
+        let recentLimit = RECENT_DEFAULT;
+        for (let i = 0; i < args.length; i++) {
+          if (args[i].startsWith('--limit=')) {
+            recentLimit = parseInt(args[i].split('=')[1], 10) || RECENT_DEFAULT;
+            break;
+          } else if (args[i] === '--limit' && i + 1 < args.length) {
+            recentLimit = parseInt(args[i + 1], 10) || RECENT_DEFAULT;
+            break;
+          }
+        }
+
+        const LARGE_DIRS = includeArchived ? ['done', 'cancel', 'archived'] : ['done', 'cancel'];
+        const SMALL_DIRS = ['active', 'backlog', 'blocked'];
+        // Fast path: no --all, no --status, no other filters — large dirs only load recent N entries
+        const useFastPath = !showAll && !hasStatusFilter &&
+          !query.priority && !query.role && !query.rigor && !query.tags;
+
+        if (useFastPath) {
+          // --- FAST PATH ---
+          // Count files per dir with readdir only (no YAML parsing for stats)
+          const dirCounts = {};
+          for (const dir of [...SMALL_DIRS, ...LARGE_DIRS]) {
+            const dirPath = path.join(api.tasksDir, dir);
+            try {
+              const entries = await fs.readdir(dirPath, { withFileTypes: true });
+              dirCounts[dir] = entries.filter(e => e.name.startsWith('TASK_')).length;
+            } catch (e) {
+              dirCounts[dir] = 0;
+            }
+          }
+          const totalCount = Object.values(dirCounts).reduce((a, b) => a + b, 0);
+          if (totalCount === 0) emitEmptyListDiagnostics(api.tasksDir); // TASK_1778
+
+          // Load tasks: full _scanDir for small dirs, fast path for large dirs
+          const grouped = {};
+
+          for (const dir of SMALL_DIRS) {
+            grouped[dir] = await api._scanDir(path.join(api.tasksDir, dir));
+          }
+
+          for (const dir of LARGE_DIRS) {
+            const dirPath = path.join(api.tasksDir, dir);
+            try {
+              const entries = await fs.readdir(dirPath, { withFileTypes: true });
+              const taskEntries = entries.filter(e => e.name.startsWith('TASK_'));
+              // Sort by TASK_NNNN number descending (most recent first)
+              taskEntries.sort((a, b) => {
+                const na = parseInt((a.name.match(/^TASK_(\d+)/) || [])[1] || '0', 10);
+                const nb = parseInt((b.name.match(/^TASK_(\d+)/) || [])[1] || '0', 10);
+                return nb - na;
+              });
+              const limited = taskEntries.slice(0, recentLimit);
+              const tasks = [];
+              for (const entry of limited) {
+                try {
+                  let task = null;
+                  if (entry.isFile() && (entry.name.endsWith('.yaml') || entry.name.endsWith('.yml'))) {
+                    task = await api._loadTaskFile(path.join(dirPath, entry.name));
+                  } else if (entry.isDirectory()) {
+                    const subEntries = await fs.readdir(path.join(dirPath, entry.name), { withFileTypes: true });
+                    for (const sub of subEntries) {
+                      if (sub.isFile() && (sub.name.endsWith('.yaml') || sub.name.endsWith('.yml'))) {
+                        task = await api._loadTaskFile(path.join(dirPath, entry.name, sub.name));
+                        if (task) break;
+                      }
+                    }
+                  }
+                  if (task) tasks.push(task);
+                } catch (e) {
+                  // skip corrupted entries
+                }
+              }
+              // Filter unmerged done tasks unless --include-unmerged
+              grouped[dir] = (!includeUnmerged && dir === 'done')
+                ? tasks.filter(t => t.merge_landed !== false)
+                : tasks;
+            } catch (e) {
+              grouped[dir] = [];
+            }
+          }
+
+          if (format === 'json') {
+            const allTasks = [...SMALL_DIRS, ...LARGE_DIRS].flatMap(d => grouped[d] || []);
+            console.log(JSON.stringify({
+              tasks: allTasks,
+              statistics: { total: totalCount, byDir: dirCounts, recent_limit: recentLimit }
+            }, null, 2));
+          } else {
+            // Table output (fast path)
+            const statusOrder = ['active', 'backlog', 'blocked', 'done', 'cancel', ...(includeArchived ? ['archived'] : [])];
+            const statusLabels = {
+              'active': 'active', 'backlog': 'backlog', 'blocked': 'blocked',
+              'done': 'done', 'cancel': 'cancel', 'archived': 'archived'
+            };
+
+            const statusSummary = statusOrder
+              .map(s => `${statusLabels[s]}: ${dirCounts[s] || 0}`)
+              .join(' | ');
+            console.log(`任務統計 (${totalCount} total)`);
+            console.log(`  ${statusSummary}`);
+
+            const formatTask = (t) => {
+              const role = t.role || t.agent_type || '-';
+              const rigor = t.rigor || '-';
+              const tags = (t.tags || []).join(',') || '-';
+              const verif = t.verification ? ' [V]' : '';
+              const unmerged = t.merge_landed === false ? ' [UNMERGED]' : '';
+              return `  [${t.id}] ${t.title}  ${t.priority}  ${role}  rigor:${rigor}  ${tags}${verif}${unmerged}`;
+            };
+
+            for (const status of statusOrder) {
+              const group = grouped[status] || [];
+              const totalInDir = dirCounts[status] || 0;
+              if (totalInDir === 0 && !SMALL_DIRS.includes(status)) continue;
+
+              // --no-cancel: count already shown in summary line; skip the section body
+              if (skipCancel && status === 'cancel') continue;
+
+              console.log(`\n--- ${statusLabels[status]} (${totalInDir}) ---`);
+
+              if (totalInDir === 0) {
+                console.log('  (none)');
+                continue;
+              }
+
+              // Large dirs: show loaded tasks; if fewer than total, add "N more" hint
+              // N = totalInDir - loaded (computed from readdir count, not group.length)
+              if (LARGE_DIRS.includes(status) && group.length < totalInDir) {
+                group.forEach(t => console.log(formatTask(t)));
+                const remaining = totalInDir - group.length;
+                console.log(`  ... (${remaining} more, use --status=${status} or --all to show all)`);
+              } else {
+                group.forEach(t => console.log(formatTask(t)));
+              }
+            }
+          }
+
+        } else {
+          // --- SLOW PATH (--all, --status=XXX, or has other query filters) ---
+          const showArchived = includeArchived || query.status === 'archived';
+          const tasks = await api.queryTasks({ ...query, includeArchived: showArchived, includeUnmerged });
+          const stats = await api.getStatistics({ includeArchived: showArchived });
+          if (stats.total === 0) emitEmptyListDiagnostics(api.tasksDir); // TASK_1778
+
+          if (format === 'json') {
+            console.log(JSON.stringify({ tasks, statistics: { ...stats, recent_limit: null } }, null, 2));
+          } else {
+            // 表格格式輸出（預設）— 按狀態分組
+            const DONE_PREVIEW = 5;
+            const CANCEL_PREVIEW = 3;
+
+            const statusOrder = ['active', 'backlog', 'blocked', 'done', 'cancel', ...(showArchived ? ['archived'] : [])];
+            const statusLabels = {
+              'active': 'active',
+              'backlog': 'backlog',
+              'blocked': 'blocked',
+              'done': 'done',
+              'cancel': 'cancel',
+              'archived': 'archived'
+            };
+            // 用目錄名統計（從全局 stats 轉換，不受篩選影響）
+            const byDir = {};
+            for (const [oldStatus, count] of Object.entries(stats.byStatus)) {
+              const dir = CONFIG.STATUS_MAP[oldStatus] || oldStatus;
+              byDir[dir] = (byDir[dir] || 0) + count;
+            }
+            const statusSummary = statusOrder
+              .map(s => `${statusLabels[s]}: ${byDir[s] || 0}`)
+              .join(' | ');
+            console.log(`任務統計 (${stats.total} total)`);
+            console.log(`  ${statusSummary}`);
+
+            // 按狀態分組
+            const grouped = {};
+            for (const t of tasks) {
+              const dir = CONFIG.STATUS_MAP[t.status] || t.status;
+              if (!grouped[dir]) grouped[dir] = [];
+              grouped[dir].push(t);
+            }
+
+            // 格式化單筆任務
+            const formatTask = (t) => {
+              const role = t.role || t.agent_type || '-';
+              const rigor = t.rigor || '-';
+              const tags = (t.tags || []).join(',') || '-';
+              const verif = t.verification ? ' [V]' : '';
+              const unmerged = t.merge_landed === false ? ' [UNMERGED]' : '';
+              return `  [${t.id}] ${t.title}  ${t.priority}  ${role}  rigor:${rigor}  ${tags}${verif}${unmerged}`;
+            };
+
+            // 顯示順序：active → backlog → blocked → done → cancel → archived
+            for (const status of statusOrder) {
+              const group = grouped[status] || [];
+              if (group.length === 0 && !['active', 'backlog', 'blocked'].includes(status)) continue;
+
+              // --no-cancel: count already shown in summary line; skip the section body
+              if (skipCancel && status === 'cancel') continue;
+
+              console.log(`\n--- ${statusLabels[status]} (${group.length}) ---`);
+
+              if (group.length === 0) {
+                console.log('  (none)');
+                continue;
+              }
+
+              const isLargeGroup = ['done', 'cancel', ...(showArchived ? ['archived'] : [])].includes(status);
+              const limit = status === 'cancel' ? CANCEL_PREVIEW : DONE_PREVIEW;
+
+              if (isLargeGroup && !showAll && !hasStatusFilter && group.length > limit) {
+                // 只顯示最近 N 筆
+                const recent = group.slice(-limit);
+                recent.forEach(t => console.log(formatTask(t)));
+                const remaining = group.length - limit;
+                console.log(`  ... (${remaining} more, use --status=${status} or --all to show all)`);
+              } else {
+                group.forEach(t => console.log(formatTask(t)));
+              }
+            }
+          }
+        }
+
+      } else if (command === 'get') {
+        const taskId = args[1];
+        if (!taskId) {
+          console.error('錯誤: 缺少任務 ID');
+          process.exit(1);
+        }
+        const task = await api.getTask(taskId);
+        if (task) {
+          console.log(JSON.stringify(task, null, 2));
+        } else {
+          console.error(`任務不存在: ${taskId}`);
+          process.exit(1);
+        }
+
+      } else if (command === 'create') {
+        // TASK_1599: Windows CreateProcess caps command line at 32767 UTF-16 chars.
+        // Detailed task cards (long description + many requirements) easily exceed this
+        // limit when passed as argv. --args-file <path> provides a JSON file transport
+        // that bypasses the limit entirely. Node reads the UTF-8 file directly --
+        // no codepage sensitivity (known Windows mojibake issue for emoji/CJK on argv).
+
+        const getArg = (flag) => {
+          for (let i = 0; i < args.length; i++) {
+            if (args[i] === flag && args[i + 1]) return args[i + 1];
+            if (args[i].startsWith(flag + '=')) return args[i].slice(flag.length + 1);
+          }
+          return null;
+        };
+        const getCsv = (flag) => {
+          const val = getArg(flag);
+          return val ? val.split(',').map(s => s.trim()).filter(Boolean) : [];
+        };
+        const getMulti = (flag) => {
+          const results = [];
+          for (let i = 0; i < args.length; i++) {
+            if (args[i] === flag && args[i + 1] && !args[i + 1].startsWith('--')) {
+              results.push(args[i + 1]);
+            } else if (args[i].startsWith(flag + '=')) {
+              results.push(args[i].slice(flag.length + 1));
+            }
+          }
+          return results;
+        };
+
+        // --args-file: load task fields from a UTF-8 JSON file (bypasses argv 32K limit).
+        // Explicit CLI flags override args-file values. Supports camelCase and snake_case keys.
+        let fileData = {};
+        const argsFilePath = getArg('--args-file');
+        if (argsFilePath) {
+          const fsSync = require('fs');
+          let raw;
+          try { raw = fsSync.readFileSync(argsFilePath, 'utf8'); }
+          catch (e) { console.error('❌ --args-file: cannot read file "' + argsFilePath + '": ' + e.message); process.exit(1); }
+          try { fileData = JSON.parse(raw); }
+          catch (e) { console.error('❌ --args-file: invalid JSON in "' + argsFilePath + '": ' + e.message); process.exit(1); }
+          if (!fileData || typeof fileData !== 'object' || Array.isArray(fileData)) {
+            console.error('❌ --args-file: expected a JSON object, got ' + (Array.isArray(fileData) ? 'array' : typeof fileData));
+            process.exit(1);
+          }
+        }
+
+        const fromFile = (camel, snake) => {
+          if (camel in fileData) return fileData[camel];
+          if (snake && snake in fileData) return fileData[snake];
+          return undefined;
+        };
+
+        // TASK_2031: --title is documented as required only when --args-file supplies
+        // no title. Warn loudly when both are present and differ (CLI still wins, per
+        // documented precedence), and when neither is present (falls back to placeholder).
+        const cliTitle = getArg('--title');
+        const fileTitle = fromFile('title');
+        if (cliTitle && fileTitle && cliTitle !== fileTitle) {
+          console.error('⚠️  --title "' + cliTitle + '" overrides --args-file title "' + fileTitle + '" -- CLI flag wins.');
+        } else if (!cliTitle && !fileTitle) {
+          console.error('⚠️  no --title and no title in --args-file -- falling back to placeholder "未命名任务".');
+        }
+
+        const taskData = {
+          title: cliTitle || fileTitle || '未命名任务',
+          description: getArg('--description') || fromFile('description') || '',
+          priority: getArg('--priority') || fromFile('priority') || 'P2',
+          role: getArg('--role') || fromFile('role') || 'developer',
+          rigor: getArg('--rigor') || fromFile('rigor') || 'medium',
+          complexity: getArg('--complexity') || fromFile('complexity') || 'medium',
+          tags: (() => { const cli = getCsv('--tags'); return cli.length > 0 ? cli : (fromFile('tags') || []); })(),
+          branch: getArg('--branch') || fromFile('branch') || null,
+          dependencies: (() => {
+            const cli = [...getCsv('--dependencies'), ...getCsv('--deps')];
+            return cli.length > 0 ? cli : (fromFile('dependencies') || []);
+          })(),
+          scope_paths: (() => {
+            const cli = getMulti('--scope-paths').flatMap(v => v.split(',').map(s => s.trim()).filter(Boolean));
+            if (cli.length > 0) return cli;
+            const fv = fromFile('scopePaths', 'scope_paths');
+            return Array.isArray(fv) ? fv : (fv ? String(fv).split(',').map(s => s.trim()).filter(Boolean) : []);
+          })(),
+          estimated_hours: (() => {
+            const cli = getArg('--estimated-hours');
+            if (cli !== null) return parseEstimatedHours(cli, '--estimated-hours');
+            const fv = fromFile('estimatedHours', 'estimated_hours');
+            return fv != null ? parseEstimatedHours(fv, '--args-file estimatedHours') : null;
+          })(),
+          notes: getArg('--notes') || fromFile('notes') || '',
+          feature_ids: (() => { const cli = getCsv('--feature-ids'); return cli.length > 0 ? cli : (fromFile('featureIds', 'feature_ids') || []); })(),
+          keywords: (() => { const cli = getCsv('--keywords'); return cli.length > 0 ? cli : (fromFile('keywords') || []); })(),
+          // TASK_2147: origin tag for tasks created by a non-interactive producer
+          // (e.g. k-cli task submit on behalf of a sub-project process). --origin
+          // is the documented flag name; it maps onto the pre-existing `source`
+          // field that createTask() already promotes onto the task when truthy.
+          source: getArg('--source') || getArg('--origin') || fromFile('source') || fromFile('origin') || null,
+        };
+
+        const reqs = getMulti('--requirements');
+        if (reqs.length > 0) { taskData.requirements = reqs; }
+        else { const fv = fromFile('requirements'); if (Array.isArray(fv) && fv.length > 0) taskData.requirements = fv; }
+
+        const ac = getMulti('--acceptance-criteria');
+        if (ac.length > 0) { taskData.acceptance_criteria = ac; }
+        else { const fv = fromFile('acceptanceCriteria', 'acceptance_criteria'); if (Array.isArray(fv) && fv.length > 0) taskData.acceptance_criteria = fv; }
+
+        const tn = getMulti('--technical-notes');
+        if (tn.length > 0) { taskData.technical_notes = tn; }
+        else { const fv = fromFile('technicalNotes', 'technical_notes'); if (Array.isArray(fv) && fv.length > 0) taskData.technical_notes = fv; }
+
+        const verificationStr = getArg('--verification');
+        if (verificationStr) {
+          try { taskData.verification = JSON.parse(verificationStr); }
+          catch (e) { console.warn('⚠️  --verification JSON 解析失敗，已忽略: ' + e.message); }
+        } else if (fileData.verification) {
+          taskData.verification = fileData.verification;
+        }
+
+        const force = args.includes('--force') || fileData.force === true;
+        const task = await api.createTask(taskData, { force });
+        console.log(`✅ 任務已建立: ${task.id}`);
+        console.log(`Hash: ${task.hash}`);
+        console.log(`標題: ${task.title}`);
+        console.log(`優先級: ${task.priority}`);
+        console.log(`角色: ${task.role}`);
+        console.log(`嚴謹度: ${task.rigor}`);
+        console.log(`複雜度: ${task.complexity}`);
+        if (task.tags.length > 0) console.log(`標籤: ${task.tags.join(', ')}`);
+        if (task.dependencies && task.dependencies.length > 0) console.log(`依賴: ${task.dependencies.join(', ')}`);
+        if (task.scope_paths && task.scope_paths.length > 0) console.log(`範圍: ${task.scope_paths.join(', ')}`);
+        if (task.estimated_hours != null) console.log(`預估工時: ${task.estimated_hours}h`);
+        if (task.branch) console.log(`分支: ${task.branch}`);
+
+        await echoAlayaLessons(taskData);
+
+      } else if (command === 'claim') {
+        const taskId = args[1];
+        if (!taskId) {
+          console.error('錯誤: 缺少任務 ID');
+          process.exit(1);
+        }
+        const forceClaim = args.includes('--force-claim');
+        const task = await api.claimTask(taskId, null, { forceClaim });
+        console.log(`✅ 任務已認領: ${task.id}`);
+
+      } else if (command === 'complete') {
+        const taskId = args[1];
+        if (!taskId) {
+          console.error('錯誤: 缺少任務 ID');
+          process.exit(1);
+        }
+        const actualHoursIndex = args.indexOf('--actual-hours');
+        const options = {};
+        if (actualHoursIndex >= 0) {
+          // TASK_2288: same validation as --estimated-hours (NaN / negative / missing value exit 1
+          // before any write). A missing value is an error here, not a 'clear'.
+          const rawHours = args[actualHoursIndex + 1];
+          const parsedHours = (rawHours === undefined || String(rawHours).startsWith('--'))
+            ? null : parseEstimatedHours(rawHours, '--actual-hours');
+          if (parsedHours === null) {
+            console.error('❌ --actual-hours: requires a number >= 0');
+            process.exit(1);
+          }
+          options.actual_hours = parsedHours;
+        }
+        if (args.includes('--skip-post-complete')) {
+          options.skipPostComplete = true;
+        }
+        const task = await api.completeTask(taskId, options);
+        console.log(`✅ 任務已完成: ${task.id}`);
+        if (task.actual_hours != null) console.log(`實際工時: ${task.actual_hours} 小時`);
+
+      } else if (command === 'move') {
+        const taskId = args[1];
+        const newStatus = args[2];
+        const force = args.includes('--force');
+
+        if (!taskId || !newStatus) {
+          console.error('錯誤: 缺少任務 ID 或目標狀態');
+          process.exit(1);
+        }
+
+        const forceClaim = args.includes('--force-claim');
+        const task = await api.moveTask(taskId, newStatus, null, { skipValidation: force, forceClaim });
+        console.log(`✅ 任務已移動: ${task.id} → ${newStatus}`);
+
+      } else if (command === 'delete') {
+        const taskId = args[1];
+        if (!taskId) {
+          console.error('錯誤: 缺少任務 ID');
+          process.exit(1);
+        }
+        const task = await api.getTask(taskId);
+        if (!task) {
+          console.error(`任務不存在: ${taskId}`);
+          process.exit(1);
+        }
+        if (task.status !== 'backlog' && task.status !== 'pending') {
+          console.error(`❌ 僅允許刪除 backlog 狀態的任務。目前狀態: ${task.status}`);
+          process.exit(1);
+        }
+        const deleted = await api.deleteTask(taskId);
+        if (deleted) {
+          console.log(`✅ 任務已刪除: ${taskId}`);
+        } else {
+          console.error(`❌ 刪除失敗: ${taskId}`);
+          process.exit(1);
+        }
+
+      } else if (command === 'search') {
+        const keyword = args[1];
+        if (!keyword) {
+          console.error('錯誤: 缺少搜尋關鍵字');
+          process.exit(1);
+        }
+        const tasks = await api.queryTasks({ search: keyword });
+        console.log(`找到 ${tasks.length} 個符合 "${keyword}" 的任務:\n`);
+        tasks.forEach(t => {
+          console.log(`  [${t.id}] ${t.title} (${t.status}, ${t.priority})`);
+        });
+
+      } else if (command === 'stats') {
+        const formatIndex = args.indexOf('--format');
+        const format = formatIndex >= 0 ? args[formatIndex + 1] : 'table';
+
+        const stats = await api.getStatistics();
+
+        if (format === 'json') {
+          // JSON 格式輸出
+          console.log(JSON.stringify(stats, null, 2));
+        } else {
+          // 表格格式輸出（預設）
+          console.log('任務統計:\n');
+          console.log('按狀態:');
+          for (const [status, count] of Object.entries(stats.byStatus)) {
+            console.log(`  ${status}: ${count}`);
+          }
+          console.log('\n按優先級:');
+          for (const [priority, count] of Object.entries(stats.byPriority)) {
+            console.log(`  ${priority}: ${count}`);
+          }
+          console.log('\n按角色:');
+          for (const [role, count] of Object.entries(stats.byRole)) {
+            console.log(`  ${role}: ${count}`);
+          }
+          if (Object.keys(stats.byTags).length > 0) {
+            console.log('\n按標籤:');
+            for (const [tag, count] of Object.entries(stats.byTags)) {
+              console.log(`  ${tag}: ${count}`);
+            }
+          }
+          console.log(`\n總計: ${stats.total} 個任務`);
+        }
+
+      } else if (command === 'reload') {
+        const stats = await api.reload();
+        console.log(`✅ Reload 完成`);
+        console.log(`   建立目錄: ${stats.created_dirs.length > 0 ? stats.created_dirs.join(', ') : '(已存在)'}`);
+        console.log(`   遷移任務: ${stats.migrated}`);
+        console.log(`   跳過（已存在）: ${stats.skipped}`);
+        if (stats.errors.length > 0) {
+          console.log(`   錯誤: ${stats.errors.length}`);
+          stats.errors.forEach(e => console.log(`     - ${e}`));
+        }
+
+      } else if (command === 'archive') {
+        // 封存 done 中最舊的任務，保留最新 N 個
+        const keepIndex = args.indexOf('--keep');
+        const keep = keepIndex >= 0 ? parseInt(args[keepIndex + 1], 10) : 10;
+        const dryRun = args.includes('--dry-run');
+
+        const doneDir = path.join(api.tasksDir, 'done');
+        const archivedDir = path.join(api.tasksDir, 'archived');
+
+        if (!dryRun) {
+          await fs.mkdir(archivedDir, { recursive: true });
+        }
+
+        let files = [];
+        try {
+          const entries = await fs.readdir(doneDir);
+          files = entries
+            .filter(f => f.startsWith('TASK_') && f.endsWith('.yaml'))
+            .sort((a, b) => {
+              const numA = parseInt(a.match(/TASK_(\d+)/)?.[1] || '0', 10);
+              const numB = parseInt(b.match(/TASK_(\d+)/)?.[1] || '0', 10);
+              return numA - numB;
+            });
+        } catch (e) {
+          if (e.code !== 'ENOENT') throw e;
+        }
+
+        if (files.length <= keep) {
+          console.log(`✅ Done 任務數 ${files.length}/${keep} — 不需要封存`);
+        } else {
+          const toArchive = files.slice(0, files.length - keep);
+          console.log(`📦 封存 ${toArchive.length} 個任務（保留最新 ${keep} 個）:\n`);
+
+          for (const file of toArchive) {
+            const src = path.join(doneDir, file);
+            const dst = path.join(archivedDir, file);
+            if (dryRun) {
+              console.log(`  [DRY RUN] ${file} → archived/`);
+            } else {
+              await fs.copyFile(src, dst);
+              await fs.unlink(src);
+              console.log(`  ✅ ${file} → archived/`);
+            }
+          }
+        }
+
+      } else if (command === 'reset-all') {
+        // 將 active/ 和 done/ 的任務全部重置回 backlog/
+        const fromIndex = args.indexOf('--from');
+        const fromStatuses = fromIndex >= 0
+          ? args[fromIndex + 1].split(',').map(s => s.trim())
+          : ['active', 'done'];
+        const dryRun = args.includes('--dry-run');
+
+        const statusDirMap = {
+          active: 'active',
+          done: 'done',
+          blocked: 'blocked',
+          cancel: 'cancel',
+        };
+
+        let totalMoved = 0;
+        for (const status of fromStatuses) {
+          const dirName = statusDirMap[status];
+          if (!dirName) {
+            console.error(`⚠️  未知狀態: ${status}（跳過）`);
+            continue;
+          }
+          const dir = path.join(api.tasksDir, dirName);
+          let files = [];
+          try {
+            const entries = await fs.readdir(dir);
+            files = entries.filter(f => f.startsWith('TASK_') && f.endsWith('.yaml'));
+          } catch (e) {
+            if (e.code !== 'ENOENT') throw e;
+          }
+
+          if (files.length === 0) continue;
+
+          console.log(`\n📂 ${status}/ → backlog/ (${files.length} 個任務):`);
+          for (const file of files) {
+            const taskId = file.split('_').slice(0, 2).join('_');
+            if (dryRun) {
+              console.log(`  [DRY RUN] ${taskId}`);
+            } else {
+              try {
+                await api.moveTask(taskId, 'backlog', null, { skipValidation: true });
+                console.log(`  ✅ ${taskId}`);
+              } catch (e) {
+                console.error(`  ❌ ${taskId}: ${e.message}`);
+              }
+            }
+            totalMoved++;
+          }
+        }
+
+        if (totalMoved === 0) {
+          console.log('✅ 沒有需要重置的任務');
+        } else {
+          console.log(`\n${dryRun ? '[DRY RUN] ' : ''}共重置 ${totalMoved} 個任務 → backlog/`);
+        }
+
+      } else if (command === 'update') {
+        const taskId = args[1];
+        if (!taskId) {
+          console.error('❌ 用法: task-api.js update TASK_ID [--field value]...');
+          process.exit(1);
+        }
+
+        // TASK_1599: Windows CreateProcess caps command line at 32767 UTF-16 chars.
+        // Detailed task cards easily exceed this limit when passed as argv.
+        // --args-file <path> provides a JSON file transport bypassing the 32K limit.
+        // Node reads UTF-8 file directly -- no codepage sensitivity for emoji/CJK.
+
+        // TASK_1832: the whole update path used truthiness to decide "was this flag
+        // passed?", which collapses "--flag omitted" and "--flag ''" into the same
+        // falsy answer. The consequence was that NO field could ever be cleared:
+        // `update --dependencies ""` reported success and silently changed nothing.
+        // The three readers below now report absence as null and an explicitly empty
+        // value as an empty string/array, so the gates at "Build updates object" can
+        // tell the two apart. Note the create-path helper of the same shape (~line
+        // 2616) deliberately keeps its own semantics (returns [] for absent) -- this
+        // one is named getCsvOrNull so the two can no longer be confused.
+        const getArg = (flag) => {
+          for (let i = 0; i < args.length; i++) {
+            if (args[i] === flag && args[i + 1] !== undefined) return args[i + 1];
+            if (args[i].startsWith(flag + '=')) return args[i].slice(flag.length + 1);
+          }
+          return null;
+        };
+        // null = flag absent | [] = flag present with an empty value (clear the field)
+        // TASK_1869: collect EVERY occurrence of the flag, not just the first.
+        // `--scope-paths a --scope-paths b` used to keep only [a] and drop b with
+        // zero warning, while `--requirements r1 --requirements r2` (getMulti)
+        // kept both -- two incompatible repeated-flag semantics in one command.
+        // Repeated flags now concatenate, matching getMulti and the create path;
+        // commas inside a single flag value still expand as before.
+        // TASK_1869 follow-on: field -> flag-like tokens that were NOT taken as values.
+        // Declared above getCsvOrNull on purpose -- the CLI entry runs at module scope,
+        // so a const declared below its consumer sits in the temporal dead zone.
+        const csvFlagLikeSkipped = {};
+        const getCsvOrNull = (flag) => {
+          let seen = false;
+          const results = [];
+          for (let i = 0; i < args.length; i++) {
+            let val = null;
+            if (args[i] === flag && args[i + 1] !== undefined) {
+              // TASK_1869 follow-on: a flag-like next token is NOT this flag's value.
+              // getMulti has always guarded this; getCsvOrNull (via getArg) never did,
+              // so `--scope-paths --append` persisted the literal string "--append" as a
+              // scope path AND consumed the --append flag, silently turning an append
+              // into a replace. Measured 2026-08-13. Skip it, and record it so the
+              // skip is not itself silent -- the whole point of this card.
+              if (args[i + 1].startsWith('--')) {
+                if (!csvFlagLikeSkipped[flag]) csvFlagLikeSkipped[flag] = [];
+                csvFlagLikeSkipped[flag].push(args[i + 1]);
+                continue;
+              }
+              val = args[i + 1];
+            } else if (args[i].startsWith(flag + '=')) {
+              val = args[i].slice(flag.length + 1);
+            }
+            if (val !== null) {
+              seen = true;
+              results.push(...val.split(',').map(s => s.trim()).filter(Boolean));
+            }
+          }
+          return seen ? results : null;
+        };
+        const getMulti = (flag) => {
+          const results = [];
+          let seen = false;
+          for (let i = 0; i < args.length; i++) {
+            if (args[i] === flag && args[i + 1] !== undefined && !args[i + 1].startsWith('--')) {
+              seen = true;
+              if (args[i + 1] !== '') results.push(args[i + 1]);
+            } else if (args[i].startsWith(flag + '=')) {
+              seen = true;
+              const v = args[i].slice(flag.length + 1);
+              if (v !== '') results.push(v);
+            }
+          }
+          if (results.length > 0) return results;
+          return seen ? [] : null;
+        };
+        // --args-file: load update fields from a UTF-8 JSON file (bypasses argv 32K limit).
+        // CLI flags override args-file values. Supports camelCase and snake_case keys.
+        let updateFileData = {};
+        const updateArgsFilePath = getArg('--args-file');
+        if (updateArgsFilePath) {
+          const fsSync = require('fs');
+          let raw;
+          try { raw = fsSync.readFileSync(updateArgsFilePath, 'utf8'); }
+          catch (e) { console.error('❌ --args-file: cannot read ' + updateArgsFilePath + ': ' + e.message); process.exit(1); }
+          try { updateFileData = JSON.parse(raw); }
+          catch (e) { console.error('❌ --args-file: invalid JSON in ' + updateArgsFilePath + ': ' + e.message); process.exit(1); }
+          if (!updateFileData || typeof updateFileData !== 'object' || Array.isArray(updateFileData)) {
+            console.error('❌ --args-file: expected a JSON object'); process.exit(1);
+          }
+        }
+
+        const fromUpdateFile = (camel, snake) => {
+          if (camel in updateFileData) return updateFileData[camel];
+          if (snake && snake in updateFileData) return updateFileData[snake];
+          return undefined;
+        };
+
+        // Build updates object -- args-file base values first, CLI flags override
+        const updates = {};
+        if (updateArgsFilePath) {
+          if (fromUpdateFile('title') != null) updates.title = fromUpdateFile('title');
+          if (fromUpdateFile('description') != null) updates.description = fromUpdateFile('description');
+          if (fromUpdateFile('priority') != null) updates.priority = fromUpdateFile('priority');
+          if (fromUpdateFile('role') != null) updates.role = fromUpdateFile('role');
+          if (fromUpdateFile('rigor') != null) updates.rigor = fromUpdateFile('rigor');
+          if (fromUpdateFile('complexity') != null) updates.complexity = fromUpdateFile('complexity');
+          const fT = fromUpdateFile('tags'); if (fT != null) updates.tags = fT;
+          const fD = fromUpdateFile('dependencies'); if (fD != null) updates.dependencies = fD;
+          const fSc = fromUpdateFile('scopePaths', 'scope_paths'); if (fSc != null) updates.scope_paths = fSc;
+          const fH = fromUpdateFile('estimatedHours', 'estimated_hours'); if (fH != null) updates.estimated_hours = parseEstimatedHours(fH, '--args-file estimatedHours');
+          if (fromUpdateFile('notes') != null) updates.notes = fromUpdateFile('notes');
+          const fFt = fromUpdateFile('featureIds', 'feature_ids'); if (Array.isArray(fFt)) updates.feature_ids = fFt;
+          const fKw = fromUpdateFile('keywords'); if (Array.isArray(fKw)) updates.keywords = fKw;
+          const fRq = fromUpdateFile('requirements'); if (fRq != null) updates.requirements = fRq;
+          const fAc = fromUpdateFile('acceptanceCriteria', 'acceptance_criteria'); if (fAc != null) updates.acceptance_criteria = fAc;
+          const fTn = fromUpdateFile('technicalNotes', 'technical_notes'); if (fTn != null) updates.technical_notes = fTn;
+          const fMl = fromUpdateFile('mergeLanded', 'merge_landed'); if (fMl != null) updates.merge_landed = Boolean(fMl);
+        }
+        // CLI flags (higher priority -- overwrite file values)
+        // TASK_1832: identity fields cannot be blanked -- an empty title/priority/role
+        // would corrupt the card. Reject loudly rather than ignoring silently; a silent
+        // no-op is the exact defect this task exists to remove.
+        for (const flag of ['--title', '--priority', '--role', '--rigor', '--complexity']) {
+          if (getArg(flag) === '') {
+            console.error(`❌ ${flag} cannot be set to an empty value (this field has no "cleared" state).`);
+            process.exit(1);
+          }
+        }
+        const title = getArg('--title'); if (title) updates.title = title;
+        // Clearable text fields: '' is a legitimate value, so gate on presence (!== null).
+        const desc = getArg('--description'); if (desc !== null) updates.description = desc;
+        const priority = getArg('--priority'); if (priority) updates.priority = priority;
+        const role = getArg('--role'); if (role) updates.role = role;
+        const rigor = getArg('--rigor'); if (rigor) updates.rigor = rigor;
+        const complexity = getArg('--complexity'); if (complexity) updates.complexity = complexity;
+        const tags = getCsvOrNull('--tags'); if (tags !== null) updates.tags = tags;
+        const deps = getCsvOrNull('--dependencies') ?? getCsvOrNull('--deps'); if (deps !== null) updates.dependencies = deps;
+        const scopePaths = getCsvOrNull('--scope-paths'); if (scopePaths !== null) updates.scope_paths = scopePaths;
+        const predictedSymbols = getCsvOrNull('--predicted-symbols'); if (predictedSymbols !== null) updates.predicted_symbols = predictedSymbols;
+        const hours = getArg('--estimated-hours'); if (hours !== null) updates.estimated_hours = parseEstimatedHours(hours, '--estimated-hours');
+        const notes = getArg('--notes'); if (notes !== null) updates.notes = notes;
+        const featureIds = getCsvOrNull('--feature-ids'); if (featureIds !== null) updates.feature_ids = featureIds;
+        const keywords = getCsvOrNull('--keywords'); if (keywords !== null) updates.keywords = keywords;
+        const reqs = getMulti('--requirements'); if (reqs) updates.requirements = reqs;
+        const ac = getMulti('--acceptance-criteria'); if (ac) updates.acceptance_criteria = ac;
+        const tn = getMulti('--technical-notes'); if (tn) updates.technical_notes = tn;
+        const mergeLandedArg = getArg('--merge-landed');
+        if (mergeLandedArg !== null) updates.merge_landed = (mergeLandedArg === 'true');
+
+        if (Object.keys(updates).length === 0) {
+          console.error('❌ 未指定任何更新欄位');
+          process.exit(1);
+        }
+
+        // TASK_1851: every array field on the update path REPLACES the whole array
+        // (updateTask spreads `...updates` over `...task`). Passing a single
+        // --technical-notes onto a card that already had N entries silently dropped
+        // the other N -- the CLI echoed only the new value and reported ✅ success.
+        // Replace semantics are kept (passing N values at once still stores exactly
+        // N, unchanged), but the loss is no longer invisible:
+        //   --append   : this invocation appends to existing entries instead
+        //   (default)  : replace, but removed existing entries are echoed after
+        //                the update so truncation is observable from the CLI.
+        // Covers ALL array fields, not just technical_notes.
+        const ARRAY_FIELDS = ['tags', 'dependencies', 'scope_paths', 'predicted_symbols',
+          'feature_ids', 'keywords', 'requirements', 'acceptance_criteria', 'technical_notes'];
+        const appendMode = args.includes('--append');
+        const touchedArrayFields = ARRAY_FIELDS.filter(k => k in updates);
+        if (appendMode && touchedArrayFields.length === 0) {
+          console.error('❌ --append 只作用於陣列欄位，本次未指定任何陣列欄位');
+          process.exit(1);
+        }
+        const replacedItems = {}; // field -> existing entries removed by the replace
+        const appendSkipped = {}; // TASK_1867: field -> appended entries skipped as duplicates
+        if (touchedArrayFields.length > 0) {
+          const before = await api.getTask(taskId); // null → updateTask 會丟出任務不存在
+          if (before) {
+            for (const k of touchedArrayFields) {
+              const oldArr = Array.isArray(before[k]) ? before[k]
+                : (before[k] == null || before[k] === '' ? [] : [before[k]]);
+              if (appendMode) {
+                // TASK_1867: appending a value identical to an existing entry used to
+                // write the duplicate silently (✅ 已更新, no warning) — downstream the
+                // dashboard rendered duplicate React keys. Skip exact duplicates and
+                // echo them, mirroring the TASK_1851 replace-path echo.
+                const seen = new Set(oldArr.map(v => String(v)));
+                const merged = [...oldArr];
+                for (const v of updates[k]) {
+                  if (seen.has(String(v))) {
+                    if (!appendSkipped[k]) appendSkipped[k] = [];
+                    appendSkipped[k].push(v);
+                  } else {
+                    seen.add(String(v));
+                    merged.push(v);
+                  }
+                }
+                updates[k] = merged;
+              } else {
+                const kept = new Set(updates[k].map(v => String(v)));
+                const removed = oldArr.filter(v => !kept.has(String(v)));
+                if (removed.length > 0) replacedItems[k] = removed;
+              }
+            }
+          }
+        }
+
+        const updated = await api.updateTask(taskId, updates);
+        console.log(`✅ 已更新: ${updated.id}`);
+        for (const [key, val] of Object.entries(updates)) {
+          const display = Array.isArray(val) ? val.join(', ') : val;
+          const displayStr = String(display).length > 80 ? String(display).substring(0, 77) + '...' : display;
+          console.log(`   ${key}: ${displayStr}`);
+        }
+        // TASK_1851: make the replace visible -- echo what was removed.
+        for (const [key, removed] of Object.entries(replacedItems)) {
+          console.log(`   ⚠️ ${key}: 取代模式移除了 ${removed.length} 條既有項目（追加請用 --append）:`);
+          for (const item of removed) {
+            const s = String(item);
+            console.log(`      - ${s.length > 80 ? s.substring(0, 77) + '...' : s}`);
+          }
+        }
+        // TASK_1867: make the append-path dedupe visible -- echo what was skipped.
+        for (const [key, skipped] of Object.entries(appendSkipped)) {
+          console.log(`   ⚠️ ${key}: 追加模式略過 ${skipped.length} 條與既有重複的項目:`);
+          for (const item of skipped) {
+            const s = String(item);
+            console.log(`      - ${s.length > 80 ? s.substring(0, 77) + '...' : s}`);
+          }
+        }
+        // TASK_1869 follow-on: a flag-like token was never taken as a value. Say so --
+        // the field is left untouched, which without this line looks like success.
+        for (const [flag, tokens] of Object.entries(csvFlagLikeSkipped)) {
+          console.log(`   ⚠️ ${flag}: 忽略了 ${tokens.length} 個看起來是 flag 的值（該欄位未被修改）: ${tokens.join(', ')}`);
+        }
+
+      } else if (command === 'migrate-merge-landed') {
+        // One-shot migration: annotate done/ and archived/ tasks that have evidence of
+        // merge failure with merge_landed=false. Safe to re-run (already-annotated skipped).
+        let annotated = 0, alreadySet = 0, skipped = 0;
+        for (const dirName of ['done', 'archived']) {
+          const dirPath = path.join(api.tasksDir, dirName);
+          const dirTasks = await api._scanDir(dirPath);
+          for (const task of dirTasks) {
+            if (task.merge_landed !== undefined) { alreadySet++; continue; }
+            const vmlFailed = task.vitals?.verify_merge_landed === false;
+            const outcomeFailed = task.outcome?.success === false;
+            if (vmlFailed || outcomeFailed) {
+              try {
+                await api.updateTask(task.id, { merge_landed: false });
+                console.log(`  [${task.id}] (${dirName}) merge_landed=false`);
+                annotated++;
+              } catch (e) {
+                console.log(`  [${task.id}] update failed: ${e.message}`);
+              }
+            } else {
+              skipped++;
+            }
+          }
+        }
+        console.log(`migrate-merge-landed: ${annotated} annotated, ${alreadySet} already set, ${skipped} skipped (no failure evidence)`);
+
+      } else if (command === 'boost-by-fires') {
+        // TASK_895: Thalamus fire → task priority auto-boost
+        // Usage: node task-api.js boost-by-fires --symbols '[{"symbolId":"file::fn","fireCount":5}]'
+        const symbolsArg = args.find((a, i) => args[i - 1] === '--symbols') || '[]';
+        let firedSymbols;
+        try {
+          firedSymbols = JSON.parse(symbolsArg);
+        } catch {
+          console.error('❌ Invalid --symbols JSON');
+          process.exit(1);
+        }
+        const result = await api.boostByFiredSymbols(firedSymbols);
+        console.log(JSON.stringify(result));
+
+      } else {
+        console.error(`未知命令: ${command}`);
+        console.error('使用 --help 查看用法');
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(`❌ 錯誤: ${error.message}`);
+      process.exit(1);
+    }
+  })();
+}
+
+// ============================================================================
+// 導出
+// ============================================================================
+
+module.exports = {
+  TaskAPI,
+  CONFIG,
+  parseYAML,
+  toYAML,
+  resolveTasksDir,
+  // TASK_1992/TASK_2104: exported for direct unit-testing with a mocked
+  // fetch (and an injectable alaya-gate module) — no live MCP dependency.
+  loadAlayaGate,
+  echoAlayaLessons,
+  // TASK_2142 R2: test seam for injecting a fake pool-status-push module.
+  setPoolStatusPush,
+};
+// thalamus cascade test 1775057515