kenaz 0.3.10 → 0.3.12

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

@@ -170,101 +170,6 @@ function releaseClaimMarker(taskId, projectRoot) {
   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.
@@ -311,6 +216,9 @@ function getTaskSync() {
   return _taskSync;
 }
 
+// TASK_2421: shared-room card replicas (relay) -- pure helper module, safe to require eagerly.
+const taskReplica = require('./task-replica');
+
 // 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
@@ -582,6 +490,11 @@ function emitEmptyListDiagnostics(tasksDir) {
   } catch { /* never break list */ }
 }
 
+/** TASK_2421: is this api's project in an active shared room (relay-leased ids)? */
+function taskReplicaIsShared(api) {
+  return taskReplica.isSharedRoom(api._loadYggdrasilConfigSync());
+}
+
 class TaskAPI {
   /**
    * @param {Object} config
@@ -1663,6 +1576,14 @@ class TaskAPI {
     // { 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_2421: plan-document id (e.g. 791-17) that maps onto this TASK id
+    if (taskData.alias && String(taskData.alias).trim()) {
+      task.alias = String(taskData.alias).trim();
+      const dup = await this._findAliasOwner(task.alias);
+      if (dup) console.warn(`⚠️  alias "${task.alias}" is already used by ${dup} -- alias lookups resolve to the first match`);
+    }
+    const replicaCtx = this._replicaCtx();
+    if (replicaCtx) task.shared_replica = true; // marker: later status changes keep the relay replica current
 
     // TASK_1110: parallel scope overlap warning (non-blocking).
     // When two tasks declare overlapping scope_paths / file references in
@@ -1699,16 +1620,146 @@ class TaskAPI {
     task._file_path = filePath;
     task._status_dir = 'backlog';
 
+    // TASK_2421: id came from the local counter inside a shared room -> loud warning.
+    if (idAllocStamp && taskReplicaIsShared(this)) {
+      const w = `${taskId} was allocated locally because the relay is unreachable -- this id may collide with one allocated by another node in the shared room. Re-check before pushing, and rename the card if another node reports the same id.`;
+      task.warnings = [...(task.warnings || []), w];
+      console.warn(`⚠️  ID COLLISION RISK: ${w}`);
+    }
+
+    // TASK_2421: publish a read-only replica to the shared room (best-effort).
+    if (replicaCtx) {
+      const r = await taskReplica.publishReplica(replicaCtx, task, 'backlog');
+      task.replica_published = r.ok;
+      if (!r.ok) {
+        const w = `card replica not published to the shared room (${r.error}); other nodes cannot read ${taskId} until a later update re-publishes it`;
+        task.warnings = [...(task.warnings || []), w];
+        console.warn(`⚠️  ${w}`);
+      }
+    }
+
     return task;
   }
 
+  // ---- TASK_2421: shared-room replicas, alias, import ----
+
+  /** Context for relay replica publishing, or null when not in a shared room / opted out. */
+  _replicaCtx() {
+    const yggConfig = this._loadYggdrasilConfigSync();
+    if (!taskReplica.shouldShareCards(yggConfig)) return null;
+    return this._buildReplicaCtx(yggConfig);
+  }
+
+  /** Read-side context: any shared room (share_cards only gates publishing). */
+  _replicaReadCtx() {
+    const yggConfig = this._loadYggdrasilConfigSync();
+    if (!taskReplica.isSharedRoom(yggConfig)) return null;
+    return this._buildReplicaCtx(yggConfig);
+  }
+
+  _buildReplicaCtx(yggConfig) {
+    return {
+      yggConfig,
+      key: this._readPublishableKey(),
+      projectRoot: this._resolveProjectRoot(),
+      node: taskReplica.nodeOf(yggConfig, this._getGitUser().name),
+      toYAML,
+    };
+  }
+
+  /** Keep the relay replica current (status + content). Never throws. */
+  async _syncReplica(task, statusDir) {
+    try {
+      if (!task || !task.shared_replica) return;
+      const ctx = this._replicaCtx();
+      if (!ctx) return;
+      const r = await taskReplica.syncReplica(ctx, task, statusDir);
+      // Row missing (create-time publish failed, or retention removed it): re-publish.
+      if (!r.ok) await taskReplica.publishReplica(ctx, task, statusDir || task._status_dir || 'backlog');
+    } catch { /* best-effort */ }
+  }
+
+  async _findAliasOwner(alias) {
+    try {
+      const want = String(alias).toLowerCase();
+      const all = await this.getAllTasks({ includeArchived: true });
+      const hit = all.tasks.find(t => t.alias && String(t.alias).toLowerCase() === want);
+      return hit ? hit.id : null;
+    } catch { return null; }
+  }
+
+  /** Map an alias (e.g. "791-17") to a TASK id; a TASK id or unknown input is returned unchanged. */
+  async resolveTaskRef(ref) {
+    if (!ref || this.validateTaskID(ref)) return ref;
+    return (await this._findAliasOwner(ref)) || ref;
+  }
+
+  /** Relay lookup by id or alias. Returns {found, row, replica}; never throws. */
+  async lookupReplica(ref) {
+    const ctx = this._replicaReadCtx();
+    if (!ctx) return { found: false };
+    return taskReplica.fetchReplica(ctx, ref, parseYAML);
+  }
+
+  /** Error for a command on an id missing locally; names the replica owner when the relay has the card. */
+  async _missingTaskError(taskId) {
+    const r = await this.lookupReplica(taskId);
+    if (r.found) {
+      const e = new Error(`任務不存在於本機: ${taskId} -- ${taskReplica.replicaNotice(taskId, r.row, r.replica)}. ` +
+        `This node cannot modify the owner's card.`);
+      e.replica = r;
+      return e;
+    }
+    return new Error(`任務不存在: ${taskId}`);
+  }
+
+  /** Import a relay replica as a local card marked with its origin node. */
+  async pullTask(taskId) {
+    await this._ensureStatusDirs();
+    const local = await this.getTask(taskId).catch(() => null);
+    if (local) throw new Error(`${taskId} already exists locally (${local._file_path}); nothing to import`);
+    const r = await this.lookupReplica(taskId);
+    if (!r.found) {
+      throw new Error(r.error ? `relay lookup failed: ${r.error}` : `任務不存在: ${taskId} (not among this shared room's replicas either)`);
+    }
+    const rep = r.replica || {};
+    const gitUser = this._getGitUser();
+    const origin = rep.origin_node || (r.row && r.row.created_by) || 'unknown';
+    const card = {
+      id: r.row.task_id,
+      hash: randomUUID(),
+      title: rep.title || r.row.title || '未命名任務',
+      description: rep.description || r.row.description || '',
+      priority: rep.priority || r.row.priority || 'P2',
+      status: 'pending',
+      role: rep.role || 'developer',
+      tags: [],
+      dependencies: [],
+      scope_paths: [],
+      requirements: toTextArray(rep.requirements),
+      acceptance_criteria: toTextArray(rep.acceptance_criteria),
+      technical_notes: [],
+      created_by: rep.created_by || { name: origin, git_user: origin, timestamp: new Date().toISOString() },
+      executed_by: null,
+      origin_node: origin,
+      imported_from_replica: { relay_status: r.row.status, imported_by: gitUser.name, imported_at: new Date().toISOString() },
+    };
+    if (rep.alias) card.alias = rep.alias;
+    const filePath = path.join(this.tasksDir, 'backlog', `${card.id}_${gitUser.git_user}.yaml`);
+    await fs.writeFile(filePath, toYAML(card));
+    await this._verifyPersisted(filePath, card);
+    card._file_path = filePath;
+    card._status_dir = 'backlog';
+    return card;
+  }
+
   /**
    * 更新任務
    */
   async updateTask(taskId, updates) {
     const task = await this.getTask(taskId);
     if (!task) {
-      throw new Error(`任務不存在: ${taskId}`);
+      throw await this._missingTaskError(taskId);
     }
 
     // TASK_1771: coerce array-typed fields so a raw-string update can never
@@ -1762,6 +1813,8 @@ class TaskAPI {
     // 垃圾值只污染回傳值，不落 YAML（toYAML 過濾底線鍵 + 寫檔前已 delete）。
     updatedTask._status_dir = this._resolveStatusDirName(filePath);
 
+    await this._syncReplica(updatedTask, undefined); // TASK_2421: content refresh (title/alias/...)
+
     return updatedTask;
   }
 
@@ -1770,16 +1823,14 @@ class TaskAPI {
    */
   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;
+    const { skipValidation = false, forceClaim = false } = options;
 
     // 取得任務資料
     let task = taskData;
     if (!task) {
       task = await this.getTask(taskId);
       if (!task) {
-        throw new Error(`任務不存在: ${taskId}`);
+        throw await this._missingTaskError(taskId);
       }
     }
 
@@ -1919,20 +1970,6 @@ class TaskAPI {
       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) {
@@ -1955,6 +1992,9 @@ class TaskAPI {
       projectPath: this.projectPath,
     }).catch(() => {});
 
+    // TASK_2421: keep the shared-room replica's status current (best-effort, bounded by the relay timeout).
+    await this._syncReplica(updatedTask, targetDir);
+
     return updatedTask;
   }
 
@@ -1985,7 +2025,7 @@ class TaskAPI {
 
     const task = await this.getTask(taskId);
     if (!task) {
-      throw new Error('任務不存在: ' + taskId);
+      throw await this._missingTaskError(taskId);
     }
 
     // M1: acquire claim marker (wx atomic — no TOCTOU)
@@ -2086,7 +2126,7 @@ class TaskAPI {
 
     const task = await this.getTask(taskId);
     if (!task) {
-      throw new Error(`任務不存在: ${taskId}`);
+      throw await this._missingTaskError(taskId);
     }
 
     // TASK_2233: backlog → done is not an allowed transition; say what to do instead
@@ -2126,13 +2166,9 @@ class TaskAPI {
       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).
-    // 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 });
+    let postCompleteSummary = null;
+    const result = await this.moveTask(taskId, 'done', updatedTask);
 
     try {
       this._autoPopThoughtsForCompletedTask(taskId, now);
@@ -2156,7 +2192,7 @@ class TaskAPI {
       try {
         const { postComplete } = require('../../.formation/tools/post-complete.js');
         console.log(`\n🔗 自動執行 post-complete for ${taskId}...\n`);
-        await postComplete({
+        const pc = await postComplete({
           taskId,
           keep: options.keep || 10,
           skipArchive: options.skipArchive || false,
@@ -2164,13 +2200,19 @@ class TaskAPI {
           dryRun: options.dryRun || false,
           message: options.message,
           projectPath: this.projectPath,
+          noSource: options.noSource || false,
         });
+        postCompleteSummary = (pc && pc.summary) || null;
       } catch (error) {
         console.error(`⚠️  post-complete 失敗: ${error.message}`);
-        console.error('   任務已完成，但 post-complete 需要手動執行');
+        // TASK_2420: surface the failure to the caller instead of a bare "completed".
+        postCompleteSummary = { outcome: 'not_completed', cardState: 'done_unreconciled', warnings: [],
+          steps: [{ step: 'post_complete', status: 'failed', reason: error.message }] };
       }
     }
 
+    // TASK_2420: non-enumerable so it never leaks into YAML / JSON serialisation of the task.
+    Object.defineProperty(result, 'postComplete', { value: postCompleteSummary, enumerable: false });
     return result;
   }
 
@@ -2227,7 +2269,8 @@ class TaskAPI {
         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);
+        const alias = String(t.alias || '').toLowerCase(); // TASK_2421
+        return title.includes(searchLower) || desc.includes(searchLower) || id.includes(searchLower) || tags.includes(searchLower) || (alias !== '' && alias.includes(searchLower));
       });
     }
 
@@ -2520,100 +2563,6 @@ class TaskAPI {
   }
 }
 
-// ============================================================================
-// 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.
@@ -2698,6 +2647,7 @@ Commands:
   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 pull TASK_ID                 匯入共享 room 的唯讀 replica 為本機卡片（標記 origin_node；TASK_2421）
   node task-api.js claim TASK_ID
   node task-api.js complete TASK_ID [--actual-hours HOURS]
   node task-api.js reconcile [--remote origin] [--base main] [--apply] [--worktrees]   關閉分支已併入 base 的 active 任務（預設 dry-run）
@@ -2751,6 +2701,7 @@ Create 選項:
   --args-file PATH         UTF-8 JSON 物件；支援 camelCase / snake_case，CLI 旗標優先
                            requirements / acceptance_criteria / technical_notes 使用 JSON 陣列
                            一般品質門檻：requirements >= 3，acceptance_criteria >= 3，technical_notes >= 2
+  --alias PLAN_ID          計畫文件編號（如 791-17），get/update/move/complete/search 皆可用（TASK_2421）
   --estimated-hours N      預估工時（小時）
   --branch NAME            Git 分支
   --notes TEXT             備註
@@ -2787,6 +2738,11 @@ Create 選項:
 
       const command = args[0];
 
+      // TASK_2421: a plan-document alias (e.g. 791-17) works anywhere a TASK id does.
+      if (['get', 'update', 'move', 'complete', 'claim', 'pull'].includes(command) && args[1] && !args[1].startsWith('--')) {
+        args[1] = await api.resolveTaskRef(args[1]);
+      }
+
       if (command === 'reconcile') {
         // TASK_2404: close active cards whose branches already landed on <remote>/<base>
         const argOf = (n, d) => { const i = args.indexOf(n); return i >= 0 && args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : d; };
@@ -3056,14 +3012,32 @@ Create 選項:
           console.error('錯誤: 缺少任務 ID');
           process.exit(1);
         }
-        const task = await api.getTask(taskId);
+        // TASK_2421: a non-TASK ref (relay-only alias) skips the local lookup (getTask throws on it)
+        const task = api.validateTaskID(taskId) ? await api.getTask(taskId) : null;
         if (task) {
           console.log(JSON.stringify(task, null, 2));
         } else {
-          console.error(`任務不存在: ${taskId}`);
-          process.exit(1);
+          // TASK_2421: id unknown locally -> look for a read-only replica in the shared room
+          const rep = await api.lookupReplica(taskId);
+          if (rep.found) {
+            const out = { ...rep.replica, id: rep.row.task_id, relay_status: rep.row.status, read_only_replica: true,
+              replica_notice: require('./task-replica').replicaNotice(taskId, rep.row, rep.replica) };
+            console.log(JSON.stringify(out, null, 2));
+            console.error(`ℹ️  ${taskId}: ${out.replica_notice}`);
+          } else {
+            console.error(`任務不存在: ${taskId}`);
+            if (rep.error) console.error(`   (shared-room replica lookup failed: ${rep.error})`);
+            process.exit(1);
+          }
         }
 
+      } else if (command === 'pull') {
+        // TASK_2421: import a shared-room replica as a local card marked with its origin node
+        const taskId = args[1];
+        if (!taskId) { console.error('錯誤: 缺少任務 ID'); process.exit(1); }
+        const card = await api.pullTask(taskId);
+        console.log(`✅ 已匯入: ${card.id} (origin node: ${card.origin_node}) -> ${card._file_path}`);
+
       } 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
@@ -3161,6 +3135,7 @@ Create 選項:
           // 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,
+          alias: getArg('--alias') || fromFile('alias') || undefined, // TASK_2421
         };
 
         const reqs = getMulti('--requirements');
@@ -3197,8 +3172,9 @@ Create 選項:
         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);
+        if (task.alias) console.log(`別名: ${task.alias}`);
+        if (task.replica_published) console.log(`共享: replica published to the shared room (read-only for other nodes)`);
+        for (const w of task.warnings || []) console.log(`⚠️  ${w}`);
 
       } else if (command === 'claim') {
         const taskId = args[1];
@@ -3233,9 +3209,29 @@ Create 選項:
         if (args.includes('--skip-post-complete')) {
           options.skipPostComplete = true;
         }
+        // TASK_2420: runtime/config tasks with no branch — git merge/verify reported as skipped
+        if (args.includes('--no-source')) {
+          options.noSource = true;
+        }
         const task = await api.completeTask(taskId, options);
-        console.log(`✅ 任務已完成: ${task.id}`);
-        if (task.actual_hours != null) console.log(`實際工時: ${task.actual_hours} 小時`);
+        const pcs = task.postComplete;
+        const stepLines = pcs ? (pcs.steps || []).map(st => `  ${st.status === 'failed' ? '❌' : st.status === 'skipped' ? '⏭' : '✅'} ${st.step}: ${st.status}${st.reason ? ' — ' + st.reason : ''}`) : [];
+        if (pcs && pcs.outcome === 'not_completed') {
+          // The card was NOT delivered: say so, with the real cause, and fail the command.
+          console.error(`❌ 任務未完成: ${task.id} — ${pcs.cardState === 'blocked' ? '已移至 blocked/' : pcs.cardState === 'active' ? '留在 active/' : '卡片仍在 done/ 但交付失敗（需人工處理）'}`);
+          for (const l of stepLines) console.error(l);
+          console.error(`  若此任務沒有 source 變更（runtime/config 修復），請改用: complete ${task.id} --no-source`);
+          process.exitCode = 1;
+        } else {
+          console.log(`✅ 任務已完成${pcs && pcs.outcome === 'completed_with_warnings' ? '（含警告）' : ''}: ${task.id}`);
+          if (pcs && pcs.outcome === 'completed_with_warnings') {
+            for (const l of stepLines) console.log(l);
+            for (const w of pcs.warnings) console.log(`  ⚠️  ${w}`);
+          } else {
+            for (const l of stepLines.filter(l => l.includes('⏭'))) console.log(l);
+          }
+          if (task.actual_hours != null) console.log(`實際工時: ${task.actual_hours} 小時`);
+        }
 
       } else if (command === 'move') {
         const taskId = args[1];
@@ -3586,6 +3582,7 @@ Create 選項:
         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 aliasArg = getArg('--alias'); if (aliasArg !== null) updates.alias = aliasArg; // TASK_2421
         const mergeLandedArg = getArg('--merge-landed');
         if (mergeLandedArg !== null) updates.merge_landed = (mergeLandedArg === 'true');
 
@@ -3737,10 +3734,6 @@ module.exports = {
   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,
 };