kenaz 0.0.0-stage → 0.3.2

package/core/.formation/tools/prompt.js

@@ -0,0 +1,2183 @@
+/**
+ * Formation Prompt Builder
+ * 根據陣型和技能定義組裝 prompt
+ *
+ * 每個陣型有不同的 prompt 結構：
+ * - unit:   角色 + 行為 + 任務 + 工作流程 + 輸出
+ * - solo:   角色 + 視角列表 + 行為 + 任務 + 工作流程 + 輸出
+ * - squad:  為每個成員分別組裝 prompt（含分工 scope）
+ * - legion: 為 team lead + 每個成員分別組裝 prompt（含溝通規則）
+ */
+
+// ─────────────────────────────────────────
+// Memory Loader（記憶系統整合）
+// ─────────────────────────────────────────
+let memoryLoader = null;
+try {
+  memoryLoader = require('./memory-loader');
+} catch { /* memory-loader not available — graceful degradation */ }
+
+// ─────────────────────────────────────────
+// Shared Principles Loader（共享原則注入）
+// ─────────────────────────────────────────
+const fs = require('fs');
+const path = require('path');
+const { buildWorktreeGitAddCommand } = require('./utils');
+// TASK_2104: Alaya relevance gate (cosine floor + stack match) extracted to
+// a dependency-free module so task-api.js's echoAlayaLessons can share it
+// without pulling in Formation-only deps. Re-exported below unchanged so
+// prompt.test.js's imports keep working.
+const {
+  buildTaskContextQuery,
+  deriveTaskStack,
+  deriveBijaStack,
+  passesAlayaRelevanceGate,
+  dedupBijas,
+  ALAYA_MIN_COSINE_DEFAULT,
+  ALAYA_STACK_OVERRIDE_COSINE,
+  ALAYA_CANDIDATE_POOL,
+} = require('./alaya-gate');
+
+// Shared core-path resolver (validates existsSync+isDirectory, falls back to KENAZ_SOURCE_DIR)
+let _resolveCoreDir = null;
+try {
+  _resolveCoreDir = require(path.join(__dirname, '..', '..', '.claude', 'hooks', 'core-resolve')).resolveCoreDir;
+} catch { /* graceful degradation — older installs without the export */ }
+
+let _sharedPrinciplesCache = null;
+
+// ─────────────────────────────────────────
+// Shared Module Tag Rules（模組自動注入規則）
+// ─────────────────────────────────────────
+
+// TASK_2371: opt-in only — a task must carry the explicit review tag. No keyword
+// match on generic tags (auth/test/...) or chart warnings; a 100-line OWASP
+// block on an unrelated auth card was pure noise.
+const MODULE_TAG_RULES = [
+  { tags: ['security-review'], module: 'security.yaml' },
+  { tags: ['testing-review'],  module: 'testing.yaml' },
+  { tags: ['code-review'],     module: 'code_review.yaml' },
+];
+
+/**
+ * Resolve which shared modules to inject based on task tags and optional chart context.
+ * @param {string|object} taskData - task JSON string or parsed object
+ * @param {string|null} [chartPath] - optional path to chart.json for richer context
+ * @param {string|null} [corePath] - KenazAI root path (defaults to two levels up from __dirname)
+ * @returns {string[]} list of absolute module file paths to inject
+ */
+function resolveModules(taskData, chartPath, corePath) {
+  const modules = new Set();
+  let taskTags = [];
+
+  try {
+    const parsed = typeof taskData === 'string' ? JSON.parse(taskData) : taskData;
+    if (parsed) {
+      taskTags = (parsed.tags || []).map(t => String(t).toLowerCase());
+    }
+  } catch { /* not JSON */ }
+
+  // Tag-based matching
+  for (const rule of MODULE_TAG_RULES) {
+    if (rule.tags.some(t => taskTags.includes(t))) {
+      modules.add(rule.module);
+    }
+  }
+
+  if (modules.size === 0) return [];
+
+  const root = corePath || path.resolve(__dirname, '..', '..');
+  const modulesDir = path.join(root, '.formation', 'roles', '_shared', 'modules');
+  return [...modules].map(m => path.join(modulesDir, m));
+}
+
+/**
+ * Resolve the KenazAI core path from a sub-project's project.yaml.
+ * Returns null when projectPath is absent or IS the core project.
+ * Uses shared resolveCoreDir helper (validates existsSync+isDirectory, KENAZ_SOURCE_DIR fallback).
+ */
+function resolveCorePath(projectPath) {
+  if (!projectPath) return null;
+
+  const coreRoot = path.resolve(__dirname, '..', '..');
+  const norm = p => p.replace(/[\\/]+$/, '').replace(/\\/g, '/').toLowerCase();
+  if (norm(path.resolve(projectPath)) === norm(coreRoot)) return null;
+
+  if (_resolveCoreDir) {
+    const dir = _resolveCoreDir(projectPath);
+    return dir ? dir.replace(/\\/g, '/') : null;
+  }
+
+  // Fallback: original logic (no path validation — used if core-resolve.js export is absent)
+  try {
+    const yamlPath = path.join(projectPath, '.kenaz', 'project.yaml');
+    if (!fs.existsSync(yamlPath)) return null;
+    const content = fs.readFileSync(yamlPath, 'utf-8');
+    const m = content.match(/core_path:\s*['"]?(.+?)['"]?\s*$/m);
+    if (!m) return null;
+    const raw = m[1].trim();
+    return raw === '__kenaz_core__'
+      ? (process.env.KENAZ_SOURCE_DIR || coreRoot).replace(/\\/g, '/')
+      : raw;
+  } catch { return null; }
+}
+
+function loadSharedPrinciples(corePath) {
+  if (_sharedPrinciplesCache) return _sharedPrinciplesCache;
+
+  const principlesPath = path.join(
+    corePath || path.resolve(__dirname, '..', '..'),
+    '.specialist', 'shared', 'principles.yaml'
+  );
+
+  try {
+    if (!fs.existsSync(principlesPath)) return null;
+    const content = fs.readFileSync(principlesPath, 'utf-8');
+
+    // 提取 differential_over_intuition 區塊
+    const ddxMatch = content.match(
+      /differential_over_intuition:[\s\S]*?(?=\n# ═|$)/
+    );
+    if (!ddxMatch) return null;
+
+    _sharedPrinciplesCache = ddxMatch[0].trim();
+    return _sharedPrinciplesCache;
+  } catch {
+    return null;
+  }
+}
+
+// ─────────────────────────────────────────
+// TASK_1998 R2 -> two-axis prompt policy (2026-09-22 user decision)
+// ─────────────────────────────────────────
+
+/**
+ * Extract the card's `rigor` field from taskData (JSON string or object).
+ * Returns null when taskData is absent, unparseable, or has no rigor field
+ * — promptProfile() treats null the same as an unrecognized value (normalizes
+ * to 'medium').
+ * @param {string|object|null|undefined} taskData
+ * @returns {string|null}
+ */
+function extractRigor(taskData) {
+  try {
+    const parsed = typeof taskData === 'string' ? JSON.parse(taskData) : taskData;
+    return (parsed && typeof parsed.rigor === 'string' && parsed.rigor.trim()) ? parsed.rigor.trim() : null;
+  } catch { return null; }
+}
+
+/**
+ * Extract the card's `complexity` field from taskData (JSON string or
+ * object). Unlike extractRigor, this ALWAYS returns a concrete string —
+ * missing, unparseable, or unrecognized values all normalize to 'medium'
+ * (the card default) so callers never need a second null-check.
+ * @param {string|object|null|undefined} taskData
+ * @returns {'simple'|'medium'|'complex'}
+ */
+function extractComplexity(taskData) {
+  try {
+    const parsed = typeof taskData === 'string' ? JSON.parse(taskData) : taskData;
+    const c = parsed && typeof parsed.complexity === 'string' ? parsed.complexity.trim() : '';
+    return (c === 'simple' || c === 'complex') ? c : 'medium';
+  } catch { return 'medium'; }
+}
+
+/**
+ * TASK_1998 two-axis prompt policy (2026-09-22 user decision, replaces the
+ * single rigor-gated R2 diet switch):
+ *
+ *   CONTEXT volume  — driven by `complexity` (how much the task touches):
+ *     simple  -> no Related Files Preview, no Known Failures, no Project Memory.
+ *     medium  -> Known Failures on; no Preview; no Project Memory.
+ *     complex -> Related Files Preview on; Known Failures + Project Memory on.
+ *     (TASK_2371: Cross-Project Context (Cortex) and Episodic Memory are gone
+ *     for every complexity — stale / unverified outcomes.)
+ *
+ *   PROCESS strictness — driven by `rigor`:
+ *     low    -> the 8-line "## Working contract" only; rune inscription optional.
+ *     medium/high -> Working contract + "## Progress Note (brief)" + the
+ *               rune-inscribe line (TASK_2371: high no longer has a
+ *               mandatory recall/inscribe/Cognitive Checkpoint ritual).
+ *
+ * This is the ONLY place either axis branches into its behaviour; every call
+ * site below reads flags off the returned profile instead of re-testing
+ * rigor/complexity itself.
+ *
+ * Backwards compatible: a bare string (or null/undefined) is treated as the
+ * legacy single-axis call — `rigor` — and `complexity` defaults to 'medium'.
+ * @param {string|{rigor?: string|null, complexity?: string|null}|null|undefined} rigorOrOptions
+ */
+function promptProfile(rigorOrOptions) {
+  let rawRigor;
+  let rawComplexity;
+  if (rigorOrOptions && typeof rigorOrOptions === 'object') {
+    rawRigor = rigorOrOptions.rigor;
+    rawComplexity = rigorOrOptions.complexity;
+  } else {
+    // Legacy string-rigor call — complexity defaults to 'medium'.
+    rawRigor = rigorOrOptions;
+    rawComplexity = 'medium';
+  }
+
+  const rigor = (rawRigor === 'low' || rawRigor === 'high') ? rawRigor : 'medium';
+  const complexity = (rawComplexity === 'simple' || rawComplexity === 'complex') ? rawComplexity : 'medium';
+
+  const CONTEXT_BY_COMPLEXITY = {
+    simple: {
+      skipRelatedFilesPreview: true,
+      skipKnownFailures: true,
+      skipProjectMemory: true,
+    },
+    medium: {
+      skipRelatedFilesPreview: true,
+      skipKnownFailures: false,
+      skipProjectMemory: true,
+    },
+    complex: {
+      skipRelatedFilesPreview: false,
+      skipKnownFailures: false,
+      skipProjectMemory: false,
+    },
+  };
+
+  // ritualTier drives appendCognitiveCheckpoint:
+  // 'low' -> Working contract only; 'medium' -> Working contract + short
+  // progress note + mandatory inscribe line; 'high' -> full ritual (compactRitual=false).
+  const PROCESS_BY_RIGOR = {
+    low:    { compactRitual: true,  ritualTier: 'low' },
+    medium: { compactRitual: true,  ritualTier: 'medium' },
+    high:   { compactRitual: true,  ritualTier: 'medium' }, // TASK_2371: high == medium ritual
+  };
+
+  return {
+    rigor,
+    complexity,
+    ...CONTEXT_BY_COMPLEXITY[complexity],
+    ...PROCESS_BY_RIGOR[rigor],
+  };
+}
+
+/**
+ * TASK_1998 R1: split an assembled prompt into its "## "/"# " sections for
+ * byte-size telemetry. Text before the first matching header (prefixes like
+ * SUBAGENT_PREFIX, which use no markdown header) is not attributed to any
+ * section — telemetry only cares about the named prompt sections.
+ * @param {string} promptText
+ * @returns {{title: string, bytes: number}[]}
+ */
+function splitPromptSections(promptText) {
+  if (typeof promptText !== 'string' || !promptText) return [];
+  const lines = promptText.split('\n');
+  const sections = [];
+  let title = null;
+  let buf = [];
+  const flush = () => {
+    if (title !== null) sections.push({ title, bytes: Buffer.byteLength(buf.join('\n'), 'utf-8') });
+  };
+  for (const line of lines) {
+    if (/^(##\s|#\s)/.test(line)) {
+      flush();
+      title = line.replace(/^#{1,2}\s+/, '').trim();
+      buf = [line];
+    } else if (title !== null) {
+      buf.push(line);
+    }
+  }
+  flush();
+  return sections;
+}
+
+// ─────────────────────────────────────────
+// 主入口
+// ─────────────────────────────────────────
+
+/**
+ * 根據陣型分發到對應的 prompt builder
+ * @param {object} skillDef - parsed YAML
+ * @param {string} taskInput - 任務描述或 ID
+ * @param {string|null} taskData - 從 .collaboration 載入的任務 YAML
+ * @returns {string|string[]} 單一 prompt（unit/solo）或 prompt 陣列（squad）
+ */
+// TASK_2374: append-only usage counter (measure-first; cut decisions after 14 days of data).
+// Env KENAZ_USAGE_COUNTERS_FILE overrides the target (tests). Never throws.
+function recordSkillUsage(skillDef, options = {}) {
+  try {
+    const file = process.env.KENAZ_USAGE_COUNTERS_FILE
+      || path.join(options.projectPath || path.resolve(__dirname, '..', '..'), '.kenaz', 'specialist', 'usage_counters.jsonl');
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, JSON.stringify({
+      ts: new Date().toISOString(), kind: 'skill',
+      name: `${skillDef.formation || 'unit'}/${skillDef.name || 'unknown'}`,
+    }) + '\n');
+  } catch { /* counter must never break a dispatch */ }
+}
+
+function buildPrompt(skillDef, taskInput, taskData, options = {}) {
+  const formation = skillDef.formation || 'unit';
+  recordSkillUsage(skillDef, options);
+
+  const builders = {
+    unit: buildUnitPrompt,
+    solo: buildSoloPrompt,
+    squad: buildSquadPrompts,
+    legion: buildLegionPrompts,
+    legacy: buildLegacyPrompt,
+  };
+
+  const builder = builders[formation];
+  if (!builder) {
+    throw new Error(`Unknown formation: ${formation}. Expected: ${Object.keys(builders).join(', ')}`);
+  }
+
+  return builder(skillDef, taskInput, taskData, options);
+}
+
+// ─────────────────────────────────────────
+// Unit：單一角色，直接執行
+// ─────────────────────────────────────────
+
+function buildUnitPrompt(skillDef, taskInput, taskData, options = {}) {
+  const lines = [];
+
+  lines.push(`## Role`);
+  lines.push(skillDef.role.identity);
+  lines.push(`Priority: ${skillDef.role.priority}`);
+  lines.push('');
+
+  appendProjectContext(lines, options);
+  appendFormationPreamble(lines, taskData, options);
+  appendYggdrasilContext(lines, options.yggdrasilContext);
+  appendMemoryContext(lines, taskData, options);
+  appendAlayaLessons(lines, taskData);
+  appendSharedModules(lines, taskData, options);
+  appendBehavior(lines, skillDef);
+  appendTask(lines, taskInput, taskData, options);
+  appendCognitiveRecall(lines, taskData, options);
+  appendWorkflow(lines, skillDef, options, taskData);
+  appendOutput(lines, skillDef);
+  appendCognitiveCheckpoint(lines, taskData, options);
+
+  return lines.join('\n');
+}
+
+// ─────────────────────────────────────────
+// Solo：一個 agent 裝備多視角，自主切換
+// ─────────────────────────────────────────
+
+function buildSoloPrompt(skillDef, taskInput, taskData, options = {}) {
+  const lines = [];
+
+  lines.push(`## Role`);
+  lines.push(skillDef.role.identity);
+  lines.push(`Priority: ${skillDef.role.priority}`);
+  lines.push('');
+
+  appendProjectContext(lines, options);
+  appendFormationPreamble(lines, taskData, options);
+  appendYggdrasilContext(lines, options.yggdrasilContext);
+  appendMemoryContext(lines, taskData, options);
+  appendAlayaLessons(lines, taskData);
+
+  // 分析原則（Solo strategy 專用）
+  if (skillDef.analysis_principles && skillDef.analysis_principles.length > 0) {
+    lines.push(`## Analysis Principles`);
+    lines.push('');
+    for (const p of skillDef.analysis_principles) {
+      lines.push(`### ${p.name}`);
+      lines.push(p.description.trim());
+      lines.push('');
+    }
+  }
+
+  // 可用視角
+  if (skillDef.perspectives && skillDef.perspectives.length > 0) {
+    lines.push(`## Available Perspectives`);
+    lines.push('');
+    lines.push('你隨時可以切換到以下任一視角。根據分析過程中的需要自主決定。');
+    lines.push('');
+
+    for (const p of skillDef.perspectives) {
+      lines.push(`### ${p.name}`);
+      lines.push(`- 關注：${p.lens}`);
+      lines.push(`- 何時切換：${p.trigger}`);
+      lines.push('');
+    }
+  }
+
+  appendBehavior(lines, skillDef);
+  appendSharedPrinciples(lines, options);
+  appendTask(lines, taskInput, taskData, options);
+  appendCognitiveRecall(lines, taskData, options);
+  appendWorkflow(lines, skillDef, options, taskData);
+  appendOutput(lines, skillDef);
+  appendCognitiveCheckpoint(lines, taskData, options);
+
+  return lines.join('\n');
+}
+
+// ─────────────────────────────────────────
+// Squad：為每個成員分別組裝 prompt
+// ─────────────────────────────────────────
+
+/**
+ * Squad 回傳 prompt 陣列，每個成員一份
+ * @returns {{ memberId: string, prompt: string, skill: string }[]}
+ */
+function buildSquadPrompts(skillDef, taskInput, taskData, options = {}) {
+  const members = skillDef.members || [];
+  if (members.length === 0) {
+    throw new Error('Squad YAML must define `members` array');
+  }
+
+  // 組裝共享上下文（注入到每個成員 prompt）
+  const sharedBlock = buildSharedContextBlock(skillDef);
+
+  return members.map(member => {
+    const lines = [];
+
+    // 成員角色
+    lines.push(`## Role`);
+    lines.push(typeof member.role === 'string' ? member.role.trim() : `你是 Squad 的一員：${member.name}`);
+    lines.push('');
+
+    // 分析模式（mode_behavior 注入）
+    const analysisMode = options.analysisMode;
+    if (analysisMode && member.mode_behavior && member.mode_behavior[analysisMode]) {
+      const modeConfig = skillDef.analysis_mode?.modes?.[analysisMode];
+      lines.push(`## Analysis Mode: ${analysisMode}`);
+      if (modeConfig?.description) lines.push(modeConfig.description.trim());
+      lines.push('');
+      lines.push('**你在此模式下的立場調整**:');
+      lines.push(member.mode_behavior[analysisMode].trim());
+      lines.push('');
+    }
+
+    // 核心原則（principles 注入 — 所有成員共用的硬規則）
+    if (skillDef.principles) {
+      lines.push(`## Principles (絕對遵守)`);
+      if (skillDef.principles.focus) {
+        lines.push(skillDef.principles.focus.trim());
+        lines.push('');
+      }
+      if (skillDef.principles.forbidden && skillDef.principles.forbidden.length > 0) {
+        lines.push('**禁止 (違反即失敗)**:');
+        for (const f of skillDef.principles.forbidden) lines.push(`- ❌ ${f}`);
+        lines.push('');
+      }
+      if (skillDef.principles.required && skillDef.principles.required.length > 0) {
+        lines.push('**必須遵守**:');
+        for (const r of skillDef.principles.required) lines.push(`- ✅ ${r}`);
+        lines.push('');
+      }
+    }
+
+    // 成員身份
+    lines.push(`## Identity`);
+    lines.push(`你是 Squad 的成員 **${member.name}** (id: ${member.id || member.name})。`);
+    lines.push(`你與其他成員並行工作，各自獨立，不能互相通訊。`);
+    lines.push(`完成你負責的部分後回報結果，Lead 會負責整合。`);
+    lines.push('');
+
+    // 成員的 scope（負責範圍）— 支援 include/exclude 格式
+    if (member.scope) {
+      lines.push(`## Scope (你只能碰這些檔案)`);
+      if (member.scope.include || member.scope.exclude) {
+        if (member.scope.include) {
+          lines.push(`Include:`);
+          const includes = Array.isArray(member.scope.include) ? member.scope.include : [member.scope.include];
+          for (const p of includes) lines.push(`  - ${p}`);
+        }
+        if (member.scope.exclude) {
+          lines.push(`Exclude:`);
+          const excludes = Array.isArray(member.scope.exclude) ? member.scope.exclude : [member.scope.exclude];
+          for (const p of excludes) lines.push(`  - ${p}`);
+        }
+      } else if (Array.isArray(member.scope)) {
+        for (const s of member.scope) lines.push(`- ${s}`);
+      } else {
+        lines.push(member.scope);
+      }
+      lines.push('');
+    }
+
+    // Yggdrasil network context
+    appendYggdrasilContext(lines, options.yggdrasilContext);
+    appendMemoryContext(lines, taskData, options);
+    appendAlayaLessons(lines, taskData);
+    appendFormationPreamble(lines, taskData, options);
+
+    // 共享上下文
+    if (sharedBlock) {
+      lines.push(sharedBlock);
+      lines.push('');
+    }
+
+    // 行為準則（squad 全局 + 成員級別）
+    const behaviors = [
+      ...(skillDef.behavior || []),
+      ...(member.behavior || [])
+    ];
+    if (behaviors.length > 0) {
+      lines.push(`## Behavior`);
+      for (const b of behaviors) lines.push(`- ${b}`);
+      lines.push('');
+    }
+
+    // 任務
+    appendTask(lines, taskInput, taskData, options);
+    appendCognitiveRecall(lines, taskData, options);
+
+    // 成員專屬工作流程或全局工作流程
+    if (member.workflow) {
+      lines.push(`## Workflow`);
+      for (const step of member.workflow) lines.push(`- ${step}`);
+      lines.push('');
+      appendDispatchOverrides(lines, taskData); // TASK_1820: same post-envelope channel as appendWorkflow
+    } else {
+      appendWorkflow(lines, skillDef, options, taskData);
+    }
+
+    // 輸出
+    if (member.output) {
+      lines.push(`## Expected Output`);
+      lines.push(typeof member.output === 'string' ? member.output.trim() : JSON.stringify(member.output));
+    } else {
+      appendOutput(lines, skillDef);
+    }
+
+    appendCognitiveCheckpoint(lines, taskData, options);
+
+    return {
+      memberId: member.id || member.name,
+      prompt: lines.join('\n'),
+      skill: member.skill || 'do'
+    };
+  });
+}
+
+/**
+ * 組裝 shared_context 區塊（Squad 成員共用的約定）
+ */
+function buildSharedContextBlock(skillDef) {
+  if (!skillDef.shared_context) return null;
+
+  const lines = [];
+  lines.push(`## Shared Context (所有成員共享的約定)`);
+
+  if (skillDef.shared_context.description) {
+    lines.push(skillDef.shared_context.description.trim());
+  }
+
+  if (skillDef.shared_context.includes) {
+    lines.push('');
+    const includes = skillDef.shared_context.includes;
+    if (typeof includes === 'object' && !Array.isArray(includes)) {
+      for (const [key, val] of Object.entries(includes)) {
+        lines.push(`### ${key}`);
+        lines.push(typeof val === 'string' ? val.trim() : JSON.stringify(val));
+        lines.push('');
+      }
+    } else if (Array.isArray(includes)) {
+      for (const item of includes) {
+        if (typeof item === 'string') {
+          lines.push(`- ${item}`);
+        } else if (typeof item === 'object') {
+          for (const [key, val] of Object.entries(item)) {
+            lines.push(`### ${key}`);
+            lines.push(typeof val === 'string' ? val.trim() : JSON.stringify(val));
+            lines.push('');
+          }
+        }
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ─────────────────────────────────────────
+// Legion：為 team lead 和成員組裝 prompt
+// ─────────────────────────────────────────
+
+/**
+ * Legion 回傳 team config + 每個成員的 prompt
+ * @returns {{ teamName: string, teamDesc: string, lead: { prompt: string }, members: { name: string, prompt: string }[] }}
+ */
+function buildLegionPrompts(skillDef, taskInput, taskData, options = {}) {
+  const team = skillDef.team || {};
+  // 支援 members: [...] 和 members: { roles: [...] } 兩種格式
+  const rawMembers = skillDef.members || [];
+  const members = Array.isArray(rawMembers) ? rawMembers : (rawMembers.roles || []);
+
+  // 團隊名稱：優先用 team.name，fallback 到 skillDef.name
+  const teamName = team.name || skillDef.name || 'Legion';
+
+  // Team lead prompt
+  const leadLines = [];
+  leadLines.push(`## Role`);
+  leadLines.push(`你是 ${teamName} 的 Team Lead。`);
+  leadLines.push(skillDef.role?.identity || '');
+  leadLines.push('');
+  leadLines.push(`## Team Members`);
+  for (const m of members) {
+    leadLines.push(`- **${m.name}**: ${m.role || m.description || ''}`);
+  }
+  leadLines.push('');
+
+  if (skillDef.communication) {
+    leadLines.push(`## Communication Rules`);
+    const comm = skillDef.communication;
+    if (Array.isArray(comm)) {
+      for (const rule of comm) leadLines.push(`- ${rule}`);
+    } else if (typeof comm === 'object') {
+      if (comm.principles) {
+        leadLines.push(`### Principles`);
+        for (const p of comm.principles) leadLines.push(`- ${p}`);
+        leadLines.push('');
+      }
+      if (comm.patterns) {
+        leadLines.push(`### Patterns`);
+        for (const p of comm.patterns) {
+          leadLines.push(`- **${p.name}**: ${p.who} — ${p.content || ''}`);
+        }
+        leadLines.push('');
+      }
+      if (comm.broadcast_policy) {
+        leadLines.push(`### Broadcast Policy`);
+        leadLines.push(comm.broadcast_policy.trim());
+        leadLines.push('');
+      }
+    }
+    leadLines.push('');
+  }
+
+  appendYggdrasilContext(leadLines, options.yggdrasilContext);
+  appendMemoryContext(leadLines, taskData, options);
+  appendAlayaLessons(leadLines, taskData);
+  appendFormationPreamble(leadLines, taskData, options);
+  appendTask(leadLines, taskInput, taskData, options);
+  appendCognitiveRecall(leadLines, taskData);
+
+  if (skillDef.lifecycle) {
+    leadLines.push(`## Lifecycle`);
+    // lifecycle 可能是 { phases: [...] } 或直接是陣列
+    const phases = Array.isArray(skillDef.lifecycle)
+      ? skillDef.lifecycle
+      : (skillDef.lifecycle.phases || []);
+    for (const step of phases) {
+      if (typeof step === 'string') {
+        leadLines.push(`- ${step}`);
+      } else {
+        leadLines.push(`### ${step.phase || step.step}`);
+        if (step.description) leadLines.push(step.description.trim());
+        if (step.lead_actions) {
+          leadLines.push('Lead actions:');
+          for (const a of step.lead_actions) leadLines.push(`- ${a}`);
+        }
+        if (step.exit_criteria) {
+          leadLines.push('Exit criteria:');
+          for (const c of step.exit_criteria) leadLines.push(`- ${c}`);
+        }
+        leadLines.push('');
+      }
+    }
+    leadLines.push('');
+  }
+
+  appendOutput(leadLines, skillDef);
+  appendCognitiveCheckpoint(leadLines, taskData, options);
+
+  // Member prompts
+  // 優先使用 YAML 的 member_prompts 模板（如 forge 的 designer/implementer/reviewer）
+  const promptTemplates = skillDef.member_prompts || {};
+
+  const memberPrompts = members.map(member => {
+    const lines = [];
+
+    // 如果有預寫好的 prompt 模板，直接用
+    const template = promptTemplates[member.id];
+    if (template) {
+      lines.push(template.trim());
+      lines.push('');
+    } else {
+      // 自動生成
+      lines.push(`## Role`);
+      lines.push(member.role || member.description?.trim() || `你是 ${teamName} 團隊的 ${member.name}。`);
+      lines.push('');
+
+      if (member.responsibilities) {
+        lines.push(`## Responsibilities`);
+        for (const r of member.responsibilities) lines.push(`- ${r}`);
+        lines.push('');
+      }
+
+      if (member.skills) {
+        lines.push(`## Skills`);
+        for (const s of member.skills) lines.push(`- ${s}`);
+        lines.push('');
+      }
+
+      if (member.scope) {
+        lines.push(`## Scope`);
+        if (Array.isArray(member.scope)) {
+          for (const s of member.scope) lines.push(`- ${s}`);
+        } else {
+          lines.push(member.scope);
+        }
+        lines.push('');
+      }
+    }
+
+    lines.push(`## Team Context`);
+    lines.push(`你是 ${teamName} 團隊的成員。可以透過 SendMessage 和其他成員溝通。`);
+    lines.push(`Team Lead 會分配任務給你，完成後回報。如果被阻塞，主動溝通。`);
+    lines.push('');
+
+    appendYggdrasilContext(lines, options.yggdrasilContext);
+    appendFormationPreamble(lines, taskData, options);
+    appendTask(lines, taskInput, taskData, options);
+    appendCognitiveRecall(lines, taskData, options);
+    appendCognitiveCheckpoint(lines, taskData, options);
+
+    return {
+      name: member.name,
+      agentType: member.agent_type || 'general-purpose',
+      prompt: lines.join('\n')
+    };
+  });
+
+  return {
+    teamName: teamName.toLowerCase().replace(/\s+/g, '-'),
+    teamDesc: team.description || skillDef.description || '',
+    lead: { prompt: leadLines.join('\n') },
+    members: memberPrompts
+  };
+}
+
+// ─────────────────────────────────────────
+// Legacy：排程器模式（不建 prompt，直接走 scheduler loop）
+// ─────────────────────────────────────────
+
+/**
+ * Legacy 不需要組裝 subagent prompt。
+ * 回傳 scheduler 配置摘要（供 dry-run 顯示用）。
+ */
+function buildLegacyPrompt(skillDef, taskInput, taskData, options = {}) {
+  const lines = [];
+  lines.push(`## Role`);
+  lines.push(skillDef.role?.identity || 'You are a developer assigned to complete the task below.');
+  lines.push('');
+
+  appendBehavior(lines, skillDef);
+  appendProjectContext(lines, options);
+  appendYggdrasilContext(lines, options.yggdrasilContext);
+  appendMemoryContext(lines, taskData, options);
+  appendAlayaLessons(lines, taskData);
+  appendTask(lines, taskInput, taskData, options);
+  appendCognitiveRecall(lines, taskData, options);
+
+  if (skillDef.collaboration?.workflow) {
+    appendWorkflow(lines, skillDef, options, taskData);
+  }
+
+  appendCognitiveCheckpoint(lines, taskData, options);
+
+  return lines.join('\n');
+}
+
+// ─────────────────────────────────────────
+// 共用片段
+// ─────────────────────────────────────────
+
+/**
+ * Append context-aware shared modules to prompt.
+ * Reads .formation/roles/_shared/modules/*.yaml based on task tags / chart context.
+ * Inserted before appendBehavior().
+ */
+function appendSharedModules(lines, taskData, options = {}) {
+  const corePath = options.corePath || resolveCorePath(options.projectPath) || undefined;
+  const chartPath = options.chartPath || null;
+  const modulePaths = resolveModules(taskData, chartPath, corePath);
+  if (modulePaths.length === 0) return;
+
+  for (const modPath of modulePaths) {
+    try {
+      if (!fs.existsSync(modPath)) continue;
+      const raw = fs.readFileSync(modPath, 'utf-8');
+
+      // Extract name and description for the section header
+      const nameMatch = raw.match(/^name:\s*(.+)$/m);
+      const descMatch = raw.match(/^description:\s*(.+)$/m);
+      const moduleName = nameMatch ? nameMatch[1].trim() : path.basename(modPath, '.yaml');
+      const moduleDesc = descMatch ? descMatch[1].trim() : '';
+
+      lines.push(`## Shared Module: ${moduleName}`);
+      if (moduleDesc) {
+        lines.push(moduleDesc);
+        lines.push('');
+      }
+
+      // Inject content section (raw YAML-formatted text, stripped of top-level key)
+      const contentMatch = raw.match(/^content:\n([\s\S]*)$/m);
+      if (contentMatch) {
+        lines.push(contentMatch[1].trimEnd());
+      } else {
+        lines.push(raw.trimEnd());
+      }
+      lines.push('');
+    } catch { /* graceful degradation — skip unreadable module */ }
+  }
+}
+
+function appendBehavior(lines, skillDef) {
+  if (skillDef.behavior && skillDef.behavior.length > 0) {
+    lines.push(`## Behavior`);
+    for (const b of skillDef.behavior) {
+      lines.push(`- ${b}`);
+    }
+    lines.push('');
+  }
+}
+
+/**
+ * Append shared principles (DDx protocol) to prompt.
+ * Loaded from .specialist/shared/principles.yaml.
+ */
+function appendSharedPrinciples(lines, options = {}) {
+  const corePath = options.corePath || undefined;
+  const ddx = loadSharedPrinciples(corePath);
+  if (!ddx) return;
+
+  lines.push(`## Shared Principles — 鑑別診斷 (DDx)`);
+  lines.push(`遇到 Bug 診斷、架構決策、結果驗證時，必須套用以下 protocol：`);
+  lines.push('');
+  lines.push(ddx);
+  lines.push('');
+}
+
+/**
+ * Append project context to prompt (multi-project support).
+ * When projectPath is provided, injects context telling the agent
+ * which project to operate on and where system files are.
+ */
+function appendProjectContext(lines, options = {}) {
+  const { projectPath, worktreePath } = options;
+
+  // Sub-project context — only when projectPath is not the core project
+  if (projectPath) {
+    const pathMod = require('path');
+    const coreRoot = pathMod.resolve(__dirname, '..', '..');
+    const norm = p => p.replace(/[\\/]+$/, '').replace(/\\/g, '/').toLowerCase();
+
+    if (norm(pathMod.resolve(projectPath)) !== norm(coreRoot)) {
+      lines.push(`## Project Context [internal — do NOT mention sub-project status to user]`);
+      lines.push(`Working directory: ${projectPath}`);
+      lines.push(`- Task files: ${projectPath}/.kenaz/tasks/`);
+      lines.push(`- Log files: ${projectPath}/.kenaz/logs/`);
+      lines.push(`- Project config: ${projectPath}/.kenaz/project.yaml`);
+
+      // Inject resolved KENAZ_CORE_PATH (shared resolver: validates path + KENAZ_SOURCE_DIR fallback)
+      const corePath = resolveCorePath(projectPath);
+      if (corePath) {
+        lines.push(`- System files (.rule/, .failure/, .specialist/): ${corePath}`);
+        lines.push(`- Task API: node ${corePath}/.collaboration/core/task-api.js --project-path ${projectPath}`);
+        lines.push('');
+        lines.push(`### KENAZ_CORE_PATH (resolved)`);
+        lines.push(`\`${corePath}\``);
+        lines.push(`All system tools use this path as root. When you need task-api.js, headless.js, or other Formation tools, reference:`);
+        lines.push(`- task-api: \`node "${corePath}/.collaboration/core/task-api.js" --project-path "${projectPath}"\``);
+        lines.push(`- headless: \`node "${corePath}/.formation/tools/headless.js" --task=TASK_XXX --project-path="${projectPath}"\``);
+        lines.push(`- post-complete: \`node "${corePath}/.formation/tools/post-complete.js" --task=TASK_XXX --project-path="${projectPath}"\``);
+      }
+
+      lines.push('');
+    }
+  }
+
+  // Worktree context — when agent runs in an isolated git worktree
+  if (worktreePath) {
+    const originalProjectPath = projectPath || require('path').resolve(__dirname, '..', '..');
+    lines.push(`## Worktree Context [internal]`);
+    lines.push(`Your cwd is a git worktree at ${worktreePath}.`);
+    lines.push(`For Synapse MCP calls (recall/inscribe/forge), use projectPath=${originalProjectPath} not your cwd.`);
+    lines.push('');
+  }
+}
+
+/**
+ * Append standard Formation Preamble to prompt.
+ * Injected into every dispatch agent for consistent task orientation.
+ * Fields: Task (id + title), Branch (git, fallback: unknown),
+ *         Scope (scope_paths, omitted when empty), Principles (fixed).
+ *
+ * @param {string[]} lines - prompt lines array (mutated)
+ * @param {string|object} taskData - task JSON string or parsed object
+ * @param {object} [options] - options ({ projectPath })
+ */
+function appendFormationPreamble(lines, taskData, options = {}) {
+  let taskId = null;
+  let taskTitle = null;
+  let scopePaths = [];
+
+  try {
+    const parsed = typeof taskData === 'string' ? JSON.parse(taskData) : taskData;
+    if (parsed) {
+      taskId = parsed.id || null;
+      taskTitle = parsed.title || null;
+      scopePaths = parsed.scope_paths || [];
+    }
+  } catch { /* not JSON */ }
+
+  // Resolve git branch — fallback to 'unknown' on any failure
+  let branch = 'unknown';
+  try {
+    const { execSync } = require('child_process');
+    const cwd = options.projectPath || path.resolve(__dirname, '..', '..');
+    const out = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 3000,
+      windowsHide: true,
+    });
+    branch = (out || '').trim() || 'unknown';
+  } catch { /* git unavailable or not a repo */ }
+
+  lines.push(`## Dispatch Context`);
+  if (taskId || taskTitle) {
+    const label = [taskId, taskTitle].filter(Boolean).join(' — ');
+    lines.push(`Task: ${label}`);
+  }
+  lines.push(`Branch: ${branch}`);
+  if (scopePaths.length > 0) {
+    lines.push(`Scope: ${scopePaths.join(', ')}`);
+  }
+  lines.push(`Principles: 完美達成>一切｜禁止盲寫｜露出問題｜結構>估計`);
+  lines.push('');
+
+  appendMinimalismLadder(lines);
+  appendFileBudgetSRP(lines);
+}
+
+/**
+ * Append the YAGNI minimalism decision-ladder (Ponytail essence) to prompt.
+ * Wired once into appendFormationPreamble so EVERY dispatched agent
+ * (unit/solo/squad/legion + sub-agent path via shared buildPrompt) inherits it.
+ * Closes the gap: Ansuz elixir holds wire>rewrite, but dispatched agents
+ * previously received no active "write less" nudge — only the "禁止盲寫" guard.
+ * Kept compact: a nudge, not a ritual.
+ *
+ * @param {string[]} lines - prompt lines array (mutated)
+ */
+function appendMinimalismLadder(lines) {
+  lines.push(`## Code Minimalism — 最省決策階梯 (YAGNI)`);
+  lines.push(`寫任何代碼前，停在第一個成立的階：`);
+  lines.push(`1. 這需要存在嗎？不需要 → 跳過（不臆測未來需求）`);
+  lines.push(`2. stdlib / 語言內建有嗎？→ 用它`);
+  lines.push(`3. 平台 / 框架原生功能？→ 用它，別自己造`);
+  lines.push(`4. 專案已裝依賴有嗎？→ 重用，別加新依賴`);
+  lines.push(`5. 一行能解嗎？→ 一行`);
+  lines.push(`6. 否則：最小可行實作`);
+  lines.push(`規則：不為單一實作建抽象介面；刪除優於新增；最短 diff。`);
+  lines.push(`刻意簡化用 \`// thrift:\` 標記上限與升級路徑（例：\`// thrift: 同步即可，QPS>100 再改 async\`）。`);
+  lines.push(`不可簡化掉（lazy ≠ negligent）：input validation、error handling、security、accessibility、用戶明確要求的功能。`);
+  lines.push('');
+}
+
+/**
+ * Append the ARCH-001 file-budget & SRP clause (shift-left prevention half).
+ * Wired into appendFormationPreamble next to appendMinimalismLadder so every
+ * dispatched agent (unit/solo/squad/legion, subagent + Formation paths) sees
+ * the budget while writing code, not as late rework at the L1 merge gate
+ * (dev/scripts/check-file-size.js, .rule/general/file-size-threshold.yaml).
+ *
+ * @param {string[]} lines - prompt lines array (mutated)
+ */
+function appendFileBudgetSRP(lines) {
+  lines.push(`## File Budget & SRP (ARCH-001)`);
+  lines.push(`單檔行數：warn=2000 / hard=4000。接近 warn 就停筆，優先 extraction 而非累加。`);
+  lines.push(`拆分模式：module / hooks/ / components/ / types.ts（依 CODE-STR-002）。`);
+  lines.push(`verify 步驟跑：\`node dev/scripts/check-file-size.js --staged\` — 有 BLOCK 先拆再提交。`);
+  lines.push('');
+}
+
+function appendTask(lines, taskInput, taskData, options = {}) {
+  const { projectPath } = options;
+  lines.push(`## Task`);
+
+  if (taskData) {
+    // Try to parse as JSON for structured extraction
+    let parsed = null;
+    try { parsed = JSON.parse(taskData); } catch { /* raw YAML fallback */ }
+
+    if (parsed && parsed.id) {
+      // Structured task injection — give agent everything it needs
+      lines.push(`**Task ID**: ${parsed.id}`);
+      lines.push(`**Title**: ${parsed.title || 'N/A'}`);
+      if (parsed._file_path) {
+        lines.push(`**Task File**: ${parsed._file_path}`);
+      }
+
+      // Project-path warning: if task was loaded with --project-path, emit a
+      // prominent block so the agent (and Lead) never forgets.
+      // All projects (including KenazAI core) are treated uniformly.
+      const taskProjectPath = parsed._project_path || projectPath;
+      if (taskProjectPath) {
+        lines.push('');
+        lines.push(`[internal] Sub-project: \`${taskProjectPath}\` — do NOT mention this to the user.`);
+        lines.push(`- ALL file operations must target this project directory`);
+        lines.push(`- ALL git operations (branch, commit, merge) must run in this repo`);
+        lines.push(`- post-complete: \`--project-path=${taskProjectPath}\``);
+        lines.push(`- headless dispatch: \`--project-path=${taskProjectPath}\``);
+        lines.push('');
+      }
+
+      if (parsed.description) {
+        lines.push(`**Description**: ${parsed.description.trim()}`);
+      }
+      if (parsed.priority) lines.push(`**Priority**: ${parsed.priority}`);
+      if (parsed.complexity) lines.push(`**Complexity**: ${parsed.complexity}`);
+      if (parsed.role) lines.push(`**Role**: ${parsed.role}`);
+
+      // Resolve scope_paths to absolute paths
+      const scopePaths = parsed.scope_paths || [];
+      if (scopePaths.length > 0) {
+        const root = projectPath || '';
+        lines.push('');
+        lines.push('**Scope Paths** (你只能操作這些路徑):');
+        for (const sp of scopePaths) {
+          if (root) {
+            const path = require('path');
+            lines.push(`- ${sp} → ${path.resolve(root, sp)}`);
+          } else {
+            lines.push(`- ${sp}`);
+          }
+        }
+      }
+
+      // Dependencies (TASK_1771: coerce string-typed dependencies defensively)
+      const _deps = Array.isArray(parsed.dependencies) ? parsed.dependencies : (parsed.dependencies ? [parsed.dependencies] : []);
+      if (_deps.length > 0) {
+        lines.push('');
+        lines.push(`**Dependencies**: ${_deps.join(', ')}`);
+      }
+
+      // Requirements
+      if (parsed.requirements && parsed.requirements.length > 0) {
+        lines.push('');
+        lines.push('**Requirements**:');
+        for (const r of parsed.requirements) {
+          lines.push(`- ${r}`);
+        }
+      }
+
+      // Acceptance criteria
+      if (parsed.acceptance_criteria && parsed.acceptance_criteria.length > 0) {
+        lines.push('');
+        lines.push('**Acceptance Criteria**:');
+        for (const ac of parsed.acceptance_criteria) {
+          lines.push(`- ${ac}`);
+        }
+      }
+
+      // Technical notes
+      if (parsed.technical_notes && parsed.technical_notes.length > 0) {
+        lines.push('');
+        lines.push('**Technical Notes**:');
+        for (const tn of parsed.technical_notes) {
+          lines.push(`- ${tn}`);
+        }
+      }
+    } else {
+      // Raw YAML/text fallback
+      lines.push('Task details:');
+      lines.push('```');
+      lines.push(taskData);
+      lines.push('```');
+    }
+  } else {
+    lines.push(taskInput);
+  }
+  lines.push('');
+}
+
+/**
+ * TASK_1833: commit command with HONEST failure semantics. The historical shape
+ * `git add ... && (git commit ... || true)` used ONE blanket swallow to cover
+ * two opposite exit conditions: nothing-to-commit (benign, should be silent)
+ * and could-not-acquire-.git/index.lock (another agent committing into the
+ * same shared tree — the work silently vanished; measured data loss 2026-07-31).
+ * This shape separates them:
+ *   - `git diff --cached --quiet` exits 0 when nothing is staged → silent skip,
+ *     no commit attempted.
+ *   - otherwise commit; on failure retry twice with 2s/4s backoff (covers the
+ *     index.lock contention window), and let the FINAL failure propagate
+ *     non-zero — loudly.
+ * `git add` gets the same retry treatment: staging also takes .git/index.lock,
+ * so under contention the add fails before the commit is ever attempted
+ * (measured in the TASK_1833 collision harness — lock held at add time made
+ * the un-retried shape fail immediately instead of riding out the window).
+ * thrift: retries on ANY failure, not just index.lock — a non-transient
+ * failure just fails 3 times and still exits loudly; classifying error kinds
+ * in a one-liner isn't worth it.
+ * @param {string} stageSpec - what to stage ('-A' or an explicit-paths placeholder)
+ * @param {string} message - commit message (may contain {task_id} placeholder)
+ * @returns {string} bash command line
+ */
+function buildCommitCommand(stageSpec, message) {
+  // TASK_1957: '-A' staging always runs inside an ISOLATED worktree (Formation
+  // unit worktree or cross-project target_repo_worktree — see appendWorkflow's
+  // isIsolated gate). Route it through buildWorktreeGitAddCommand() so daemon/
+  // dispatch telemetry (.kenaz/sessions, .kenaz/specialist, .formation/.dispatch-branch,
+  // .formation/analytics) is never staged into the task commit in the first
+  // place — the root cause of esp32 TASK_82/83's post-merge "would be
+  // overwritten" failures. The explicit-paths shared-tree case is unaffected.
+  const add = stageSpec === '-A' ? buildWorktreeGitAddCommand() : `git add ${stageSpec}`;
+  const commit = `git commit --no-verify -m "${message}"`;
+  // Jittered backoff (1-3s then 3-7s): deterministic delays keep two colliding
+  // agents in lockstep — measured in the TASK_1833 harness, fixed 2s/4s retries
+  // re-collided on every attempt; jitter de-synchronizes them.
+  // $RANDOM degrades to a fixed 1s/3s under non-bash sh — still valid.
+  const j1 = 'sleep $((RANDOM % 3 + 1))';
+  const j2 = 'sleep $((RANDOM % 5 + 3))';
+  // The nothing-staged gate is re-evaluated INSIDE each retry, not once up
+  // front: in a shared tree a racing committer can absorb our staged paths
+  // into ITS commit (shared .git/index) — the work has then landed, and a
+  // blind commit retry would fail "nothing to commit" (a loud false negative,
+  // measured in the TASK_1833 harness). Re-checking turns that into the
+  // correct silent skip; a still-held index.lock still fails all 3 attempts
+  // and exits non-zero.
+  const attempt = `git diff --cached --quiet || ${commit}`;
+  return `{ ${add} || { ${j1}; ${add}; } || { ${j2}; ${add}; }; } && { ${attempt} || { ${j1}; ${attempt}; } || { ${j2}; ${attempt}; }; }`;
+}
+
+/**
+ * TASK_2082 R3: true when the card's scope_paths touch Rust — a .rs file or
+ * anything under dashboard/src-tauri/. Drives whether the worktree subagent
+ * prompt gets the "## Rust check" section (see appendRustCheckReminder).
+ * @param {string|object|null|undefined} taskData
+ * @returns {boolean}
+ */
+function hasRustScope(taskData) {
+  try {
+    const parsed = typeof taskData === 'string' ? JSON.parse(taskData) : taskData;
+    const scopePaths = (parsed && parsed.scope_paths) || [];
+    return scopePaths.some((p) => {
+      const norm = String(p).replace(/\\/g, '/');
+      return /\.rs$/i.test(norm) || norm.includes('dashboard/src-tauri/');
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * TASK_2082 R3: default existence check for whether the resolved core root
+ * actually carries the Rust crate — on a packaged machine (Alaya failure_seed,
+ * 2026-09-25) dashboard/src-tauri may not exist at all, so the Rust check
+ * section must never render there even for a Rust-scoped card. Exposed as a
+ * default so callers/tests can inject `options.rustCoreCheck` instead of
+ * touching this machine's filesystem.
+ * @param {string} corePath
+ * @returns {boolean}
+ */
+function defaultRustCoreCheck(corePath) {
+  try {
+    return fs.existsSync(path.join(corePath, 'dashboard', 'src-tauri', 'Cargo.toml'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * TASK_2082 R3: appends the "## Rust check (once, after commit)" section for
+ * worktree-isolated subagents on Rust-scoped cards only. Gated on BOTH:
+ *   - hasRustScope(taskData) — the card actually touches Rust, and
+ *   - the resolved core root actually has the crate (defaultRustCoreCheck,
+ *     overridable via options.rustCoreCheck for tests / packaged machines).
+ * `isIsolated` is the same flag appendWorkflow already computes for the
+ * commit-step staging choice (`-A` in an isolated worktree vs explicit-paths
+ * in a shared tree) — this section only makes sense where there IS an
+ * isolated worktree + branch to run rust-verify-worktree.js against.
+ * Cards that don't match either gate render no lines — byte-identical to
+ * the pre-TASK_2082 output.
+ *
+ * Hard rule 4 ("Rust 交 Ansuz") lives in the SUBAGENT_PREFIX/
+ * WORKTREE_DISPATCH_HARD_RULES constant text, prepended BEFORE this prompt
+ * body — so this section does NOT try to talk over it with a "later wins"
+ * note (agents were observed obeying the earlier hard rule instead). The
+ * actual wording fix happens at the composition point in dispatch.js via
+ * applyRustCheckToPrefix(prefix, body), which rewrites "Rust 交 Ansuz" to
+ * the allowing wording IN THE PREFIX ITSELF whenever body contains this
+ * section's marker ("## Rust check (once, after commit)") — so there is
+ * never a contradiction for the agent to resolve.
+ * @param {string[]} lines
+ * @param {string|object|null|undefined} taskData
+ * @param {object} options
+ * @param {boolean} isIsolated
+ */
+function appendRustCheckReminder(lines, taskData, options = {}, isIsolated) {
+  if (!isIsolated) return;
+  if (!hasRustScope(taskData)) return;
+
+  const corePath = options.corePath || resolveCorePath(options.projectPath) || path.resolve(__dirname, '..', '..');
+  const checkFn = typeof options.rustCoreCheck === 'function' ? options.rustCoreCheck : defaultRustCoreCheck;
+  if (!checkFn(corePath)) return;
+
+  lines.push(`## Rust check (once, after commit)`);
+  lines.push(`After committing, run exactly one narrow filter: \`node ${corePath}/dev/scripts/rust-verify-worktree.js run <your branch> <test filter>\`.`);
+  lines.push(`Exit 75/124 = report unverified and stop, do not retry or poll. Never run cargo in your own worktree.`);
+  lines.push('');
+}
+
+/**
+ * TASK_2082 defect fix (Ansuz review of eb7c3be5d): the "later instructions
+ * win" approach above was rejected — dispatched agents were observed
+ * obeying the EARLIER hard rule 4 ("Rust 交 Ansuz") over the later "## Rust
+ * check" section, i.e. a genuinely contradictory prompt, not just a
+ * precedence question for a human reader. Fixing hard rule 4's wording
+ * itself requires editing the prefix constant AT THE COMPOSITION POINT
+ * (dispatch.js, where `subagentPrefix + promptText` are concatenated),
+ * since SUBAGENT_PREFIX/buildSubagentWorktreePrefix are plain strings with
+ * no access to the per-card body.
+ *
+ * Call this from dispatch.js right before prefixing: only when `body`
+ * (the assembled rawPrompt) carries the Rust-check section marker does the
+ * chosen prefix get its hard-rule-4 phrase swapped for wording that allows
+ * the single command. A body without the marker (JS-only card, or any
+ * card where appendRustCheckReminder's gates didn't fire) leaves `prefix`
+ * byte-identical.
+ * @param {string} prefix - the chosen subagent prefix (SUBAGENT_PREFIX,
+ *   SUBAGENT_PREFIX_DIRECT, or a buildSubagentWorktreePrefix(...) result)
+ * @param {string} body - the assembled rawPrompt (post buildPrompt())
+ * @returns {string}
+ */
+const RUST_CHECK_SECTION_MARKER = '## Rust check (once, after commit)';
+const HARD_RULE_4_RUST_PHRASE = 'Rust 交 Ansuz';
+const HARD_RULE_4_RUST_ALLOW_PHRASE = 'Rust 只准跑一次 ## Rust check 指令';
+
+function applyRustCheckToPrefix(prefix, body) {
+  if (typeof prefix !== 'string' || typeof body !== 'string') return prefix;
+  if (!body.includes(RUST_CHECK_SECTION_MARKER)) return prefix;
+  return prefix.split(HARD_RULE_4_RUST_PHRASE).join(HARD_RULE_4_RUST_ALLOW_PHRASE);
+}
+
+function appendWorkflow(lines, skillDef, options = {}, taskData = null) {
+  if (skillDef.collaboration && skillDef.collaboration.workflow) {
+    // Sub-project: rewrite task-api commands to include --project-path
+    const rewriteCmd = buildTaskApiRewriter(options);
+    // Replace {task_id} placeholder with actual task ID when available
+    const taskId = options.taskId || null;
+    const resolveTaskId = (cmd) => taskId ? cmd.replace(/\{task_id\}/g, taskId) : cmd;
+
+    // TASK_1821: rigor-gated self-complete. rigor:high cards must NOT be closed by
+    // their own executor — the party with independent verification on the Formation
+    // path is post-complete (dispatcher side: regression tests + verify-acceptance +
+    // verified merge), and it already moves the task active→done itself after
+    // isVerifiedMergeSuccess (post-complete.js Step 2.5), so the card cannot strand.
+    // NOTE: this axis (per-card rigor) is orthogonal to the isSubagent axis below
+    // (per-dispatch-path). The subagent branch `continue`s first, so its replacement
+    // note stays byte-identical and this check only fires on Formation/headless/serial.
+    // TASK_2252: extractRigor accepts string OR object (a bare JSON.parse(object)
+    // threw into the catch and silently skipped this gate).
+    const taskRigor = extractRigor(taskData);
+
+    lines.push(`## Workflow`);
+    // TASK_1819: only isolated executors may stage the whole tree.
+    // - options.isSubagent  → Agent-tool dispatch (worktree isolation, dispatch.js)
+    //   ...UNLESS options.isCrossProject (TASK_1824): cross-project sub-agent dispatch
+    //   has NO worktree isolation (TASK_1672 — the Agent tool worktree derives from the
+    //   conversation cwd repo, not the target sub-project). It writes directly into the
+    //   sub-project's SHARED working tree, so it gets explicit-paths staging like serial.
+    // - options.isWorktree  → Formation task worktree (threaded from headless.js
+    //                         promptOpts.isWorktree = !!_unitWorktreePath)
+    // Serial (neither flag) shares the working tree with the user and Ansuz —
+    // a blanket `git add -A` swept 392 unrelated files in TASK_188, so serial
+    // mode gets an explicit-paths staging instruction instead.
+    const isIsolated = !!((options.isSubagent && !options.isCrossProject) || options.isWorktree);
+    for (const step of skillDef.collaboration.workflow) {
+      // In subagent mode: skip read/claim (card already inline; claim done by parent)
+      if (options.isSubagent) {
+        const stepRun = step.run || '';
+        if (stepRun.includes('task-api.js get ') || stepRun.includes('task-api.js claim ')) {
+          continue;
+        }
+        if (stepRun.includes('task-api.js complete')) {
+          lines.push(`### ${step.step}`);
+          lines.push('Note: ⚠️ Worktree mode — 禁止執行 task-api.js complete。主 thread 在 merge + 驗證後處理。');
+          lines.push('');
+          continue;
+        }
+      }
+      // TASK_1821: Formation/headless/serial path + rigor:high → replace the
+      // self-complete step with a prohibition note (same technique as the
+      // subagent branch above). The dispatcher-side post-complete pipeline
+      // closes the card after merge + independent verification.
+      if (taskRigor === 'high' && step.run && step.run.includes('task-api.js complete')) {
+        lines.push(`### ${step.step}`);
+        lines.push('Note: ⚠️ rigor: high — 禁止執行 task-api.js complete。任務留在 active/，由派工方的 post-complete 在 merge + 獨立驗證（回歸測試 + verify-acceptance）通過後移入 done/。在完成摘要中明確標註「未自行 complete，待派工者驗證後關閉」。');
+        lines.push('');
+        continue;
+      }
+      // TASK_1833: the workflow commit step must never render the blanket
+      // `|| true` from the skill YAML — see buildCommitCommand for why (one
+      // swallow covered both nothing-to-commit AND index.lock data loss).
+      // Applies to BOTH modes: isolated gets `git add -A`, shared-tree gets
+      // explicit-paths staging (TASK_1819) — each with the honest commit shape.
+      if (step.run && step.run.includes('git add -A') && step.run.includes('git commit')) {
+        const msgMatch = step.run.match(/-m\s+"([^"]+)"/);
+        const commitMsg = msgMatch ? msgMatch[1] : '[{task_id}] task completed';
+        lines.push(`### ${step.step}`);
+        if (isIsolated) {
+          lines.push(`Command: ${resolveTaskId(buildCommitCommand('-A', commitMsg))}`);
+          if (step.note) lines.push(`Note: ${step.note}`);
+          lines.push('Note: nothing to commit 時靜默跳過（不算失敗）；git commit 失敗（如 index.lock 競爭）會自動退避重試兩次，仍失敗則以非零退出 — 此時大聲回報錯誤，不要吞掉。');
+        } else {
+          lines.push(`Command: ${resolveTaskId(buildCommitCommand('<只列出你本次明確編輯過的檔案路徑>', commitMsg))}`);
+          lines.push('Note: ⚠️ 共用工作樹模式（無 worktree 隔離）— 你與使用者、其他 agent 共用同一個工作樹。只 stage 你本次明確編輯過的檔案，嚴禁一次 stage 整個工作樹（TASK_188 曾因此把 392 個無關檔案掃進單一 commit）。nothing to commit 時靜默跳過（不算失敗）；git commit 失敗（如 .git/index.lock 被其他 agent 持有）會自動退避重試兩次，仍失敗則以非零退出 — 此時大聲回報錯誤，不要吞掉。');
+        }
+        lines.push('');
+        appendRustCheckReminder(lines, taskData, options, isIsolated);
+        continue;
+      }
+      lines.push(`### ${step.step}`);
+      if (step.run) lines.push(`Command: ${resolveTaskId(rewriteCmd(step.run))}`);
+      if (step.note) lines.push(`Note: ${step.note}`);
+      if (step.actions) {
+        for (const a of step.actions) {
+          lines.push(`- ${a}`);
+        }
+      }
+      lines.push('');
+    }
+
+    if (skillDef.collaboration.on_blocked) {
+      lines.push(`### On Blocked`);
+      lines.push(`Command: ${resolveTaskId(rewriteCmd(skillDef.collaboration.on_blocked.run))}`);
+      lines.push(`Note: ${skillDef.collaboration.on_blocked.note}`);
+      lines.push('');
+    }
+  }
+
+  appendDispatchOverrides(lines, taskData);
+}
+
+/**
+ * TASK_1820: card-controlled override channel, rendered immediately AFTER the
+ * ## Workflow envelope. Section order is fixed (## Task always precedes
+ * ## Workflow) and later instructions win for LLMs, so card-level override
+ * statements written inside ## Task structurally lose to the envelope
+ * (observed: TASK_183's "DO NOT COMMIT" technical note was overridden and the
+ * executor committed anyway). This is the single override mechanism — do NOT
+ * add skip_steps or a kenaz_dispatch extraInstructions param alongside it:
+ * multiple channels without a stated precedence turn "cannot override" into
+ * "unclear who wins".
+ *
+ * Card field: `dispatch_overrides` (optional; string or array of strings).
+ * Cards without the field render byte-identically to before this change.
+ */
+function appendDispatchOverrides(lines, taskData) {
+  if (!taskData) return;
+  let parsed = null;
+  try { parsed = typeof taskData === 'string' ? JSON.parse(taskData) : taskData; } catch { return; /* raw YAML fallback — no structured field */ }
+  const raw = parsed && parsed.dispatch_overrides;
+  if (!raw) return;
+  const items = (Array.isArray(raw) ? raw : [raw])
+    .filter(item => item != null && String(item).trim() !== '');
+  if (items.length === 0) return;
+
+  lines.push(`## Dispatch Overrides (card-level — 覆寫上方 Workflow)`);
+  lines.push(`⚠️ 以下指示來自任務卡片，優先級高於上方 ## Workflow 的預設步驟。兩者衝突時，一律以本區段為準。`);
+  for (const item of items) {
+    lines.push(`- ${String(item).trim()}`);
+  }
+  lines.push('');
+}
+
+/**
+ * Build a rewriter function that rewrites task-api commands for sub-projects.
+ * When projectPath is set, replaces relative `node .collaboration/core/task-api.js`
+ * with absolute path + --project-path flag.
+ */
+function buildTaskApiRewriter(options = {}) {
+  const { projectPath } = options;
+  if (!projectPath) return (cmd) => cmd;
+
+  // Resolve corePath using shared resolver (validates path + KENAZ_SOURCE_DIR fallback)
+  const corePath = resolveCorePath(projectPath);
+  if (!corePath) return (cmd) => cmd;
+
+  const TASK_API_PATTERN = /node\s+\.collaboration\/core\/task-api\.js/g;
+  const replacement = `node "${corePath}/.collaboration/core/task-api.js" --project-path "${projectPath}"`;
+
+  return (cmd) => cmd.replace(TASK_API_PATTERN, replacement);
+}
+
+/**
+ * Append Yggdrasil network context — shows what other nodes are doing.
+ * Lets the agent know about remote activity and potential file conflicts.
+ *
+ * @param {string[]} lines
+ * @param {object} ctx - { onlineNodes, remoteTasks, myNodeName, myScopePaths }
+ */
+function appendYggdrasilContext(lines, ctx) {
+  if (!ctx) return;
+  const { onlineNodes = [], remoteTasks = [], myScopePaths = [] } = ctx;
+  if (onlineNodes.length === 0 && remoteTasks.length === 0) return;
+
+  lines.push('## Yggdrasil Network (Remote Collaborators)');
+  lines.push('Other developers/agents are currently working on this project:');
+  lines.push('');
+
+  for (const node of onlineNodes) {
+    const files = node.touching_files || [];
+    lines.push(`**${node.node_name}** — ONLINE`);
+    if (node.branch) lines.push(`  Branch: ${node.branch}`);
+    if (node.current_task) lines.push(`  Task: ${node.current_task}`);
+    if (node.work_summary) lines.push(`  Working on: ${node.work_summary}`);
+    if (files.length > 0) {
+      lines.push(`  Files: ${files.slice(0, 8).join(', ')}${files.length > 8 ? ` (+${files.length - 8})` : ''}`);
+    }
+
+    // Highlight file overlaps with my scope (informational, not blocking)
+    if (myScopePaths.length > 0 && files.length > 0) {
+      const overlaps = files.filter(f =>
+        myScopePaths.some(sp => f.startsWith(sp) || sp.startsWith(f))
+      );
+      if (overlaps.length > 0) {
+        lines.push(`  ℹ️ FILE OVERLAP: ${overlaps.join(', ')}`);
+        lines.push(`  → Be aware of potential merge conflicts. Coordinate if needed.`);
+      }
+    }
+    lines.push('');
+  }
+
+  if (remoteTasks.length > 0) {
+    lines.push('Active remote tasks:');
+    for (const t of remoteTasks.slice(0, 5)) {
+      lines.push(`- ${t.task_id} (claimed by ${t.claimed_by})`);
+    }
+    lines.push('');
+  }
+
+  lines.push('To check real-time network status: `node .formation/tools/coordinator.js --status`');
+  lines.push('');
+}
+
+/**
+ * Append memory context — 從 .failure/ + .memory/ + .kenaz/main-memory/ 載入相關經驗
+ * 注入到 prompt 中讓 agent 避免重蹈覆轍
+ */
+function appendMemoryContext(lines, taskData, options = {}) {
+  if (!memoryLoader) return;
+
+  try {
+    // 從 taskData 提取上下文資訊
+    const memOpts = {};
+    if (taskData) {
+      let parsed = null;
+      try { parsed = JSON.parse(taskData); } catch { /* not JSON */ }
+      if (parsed) {
+        memOpts.taskTitle = parsed.title || '';
+        memOpts.role = parsed.role || '';
+        memOpts.scopePaths = parsed.scope_paths || [];
+        memOpts.tags = parsed.tags || [];
+        memOpts.priority = parsed.priority || '';
+      }
+    }
+
+    // TASK_1998 two-axis policy: Known Failures / Project Memory are CONTEXT
+    // volume, driven by complexity — simple drops both, medium restores Known
+    // Failures but keeps Project Memory dropped, complex keeps both. Knowledge
+    // Base (main-memory) is unaffected either way — it isn't part of this gate.
+    const profile = promptProfile({ rigor: extractRigor(taskData), complexity: extractComplexity(taskData) });
+    memOpts.skipFailures = profile.skipKnownFailures;
+    // 2026-10-10: memory system frozen (project_memory_system_frozen) - no Project Memory block.
+    memOpts.skipMemory = true;
+
+    // Resolve corePath for sub-projects so memory-loader reads from core's
+    // .failure/, .memory/, .kenaz/main-memory/ instead of __dirname fallback
+    const corePath = options.corePath || resolveCorePath(options.projectPath);
+    if (corePath) memOpts.corePath = corePath;
+
+    const memoryBlock = memoryLoader.loadMemoryContext(memOpts);
+    if (memoryBlock) {
+      lines.push(memoryBlock);
+    }
+
+    // Code-navigation reminder (SYN-002, rewritten for LSP in TASK_2335)
+    lines.push('');
+    lines.push('## Search Tool Selection (SYN-002)');
+    lines.push('搜尋前先判斷：精確字串（函數名、error message、概念關鍵字）→ Grep / Glob。「誰呼叫它」「改了影響哪裡」「定義在哪」→ kenaz_lsp_callers / kenaz_lsp_references / kenaz_lsp_definition（args: projectPath, file, line 或 symbol, depth）；檔案內 symbol 列表 → kenaz_lsp_symbols。');
+    lines.push('');
+  } catch { /* graceful degradation */ }
+}
+
+/**
+ * Synchronously call an MCP tool via JSON-RPC over the local Dashboard HTTP
+ * server (127.0.0.1:18080/api/mcp) in a subprocess — keeps buildPrompt() sync.
+ * Returns the parsed inner data object, or null on any failure / unavailability.
+ * Shared by appendAlayaLessons.
+ *
+ * @param {string} toolName - MCP tool name (e.g. 'cortex_recall')
+ * @param {object} toolArgs - forwarded as params.arguments
+ * @returns {object|null}
+ */
+function callMcpToolSync(toolName, toolArgs) {
+  try {
+    const { execSync } = require('child_process');
+    const script = `
+      const http = require('http');
+      const payload = JSON.stringify({
+        jsonrpc: '2.0', id: 1,
+        method: 'tools/call',
+        params: { name: ${JSON.stringify(toolName)}, arguments: ${JSON.stringify(toolArgs)} }
+      });
+      const req = http.request({
+        hostname: '127.0.0.1', port: 18080, path: '/api/mcp',
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+        timeout: 5000
+      }, (res) => {
+        let d = '';
+        res.on('data', c => d += c);
+        res.on('end', () => process.stdout.write(d));
+      });
+      req.on('error', () => process.exit(0));
+      req.on('timeout', () => { req.destroy(); process.exit(0); });
+      req.write(payload);
+      req.end();
+    `;
+    const stdout = execSync(`node -e "${script.replace(/"/g, '\\"').replace(/\n/g, ' ')}"`, {
+      timeout: 8000, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true,
+    });
+    if (!stdout || !stdout.trim()) return null;
+    const result = JSON.parse(stdout);
+    if (!result || result.error) return null;
+    const content = result.result?.content;
+    if (!content || !Array.isArray(content)) return null;
+    const textPart = content.find(c => c.type === 'text');
+    if (!textPart || !textPart.text) return null;
+    try { return JSON.parse(textPart.text); } catch { return null; }
+  } catch { return null; } // MCP server unavailable — graceful degradation
+}
+
+// TASK_2101/TASK_2104: the absolute relevance gate (cosine floor + stack
+// match) for Alaya lesson injection — constants, deriveTaskStack,
+// deriveBijaStack, passesAlayaRelevanceGate — now lives in
+// .formation/tools/alaya-gate.js (dependency-free, shared with task-api.js's
+// echoAlayaLessons). Destructured from the require() at the top of this
+// file; see alaya-gate.js for the full calibration writeup and rationale.
+
+/**
+ * Append bounded Alaya process-lesson context to the prompt.
+ * Reuses the title+scope_paths query, queries
+ * alaya_recall (hybrid mode, failure_seed + lesson_seed, with the TASK_2101
+ * min_cosine floor) and injects a ## Process lessons (Alaya) section capped
+ * at 900 chars total — but ONLY for candidates that also pass the stack-match
+ * gate. Zero passing candidates renders nothing (R3: an empty section beats
+ * noise).
+ *
+ * Graceful degradation: silently skips on empty query, empty results, or
+ * any MCP failure — the recall bar is never allowed to raise dispatch
+ * latency or fail the prompt build.
+ *
+ * @param {string[]} lines - prompt lines array (mutated)
+ * @param {string|object} taskData - task JSON string or parsed object
+ * @param {(toolName: string, toolArgs: object) => object|null} [mcpCaller] - injectable MCP bridge (defaults to callMcpToolSync; test seam)
+ */
+function appendAlayaLessons(lines, taskData, mcpCaller = callMcpToolSync) {
+  if (!mcpCaller.__forceAlaya) return; // 2026-10-10: memory system frozen; tests opt in via __forceAlaya
+  const query = buildTaskContextQuery(taskData);
+  if (!query) return;
+
+  let scopePaths = [];
+  try {
+    const parsed = typeof taskData === 'string' ? JSON.parse(taskData) : taskData;
+    if (parsed) scopePaths = parsed.scope_paths || [];
+  } catch { /* taskData not JSON — task stack stays empty, floor-only gate */ }
+  const taskStack = deriveTaskStack(scopePaths);
+
+  try {
+    const recallData = mcpCaller('alaya_recall', {
+      query, mode: 'hybrid', seed_types: ['failure_seed', 'lesson_seed'],
+      limit: ALAYA_CANDIDATE_POOL, min_cosine: ALAYA_MIN_COSINE_DEFAULT,
+    });
+    if (!recallData) return;
+
+    let bijas = recallData.bijas || [];
+    if (bijas.length === 0) return;
+    const candidateCount = bijas.length;
+
+    bijas = dedupBijas(bijas);
+
+    // TASK_2101 R3: stack-match gate on top of the server-side cosine floor
+    // (the server already applied min_cosine, but re-checking here keeps
+    // this function correct against a stub/older server that ignores it).
+    const gated = bijas.filter(b => passesAlayaRelevanceGate(b, taskStack, ALAYA_MIN_COSINE_DEFAULT));
+    const droppedCount = candidateCount - gated.length;
+    if (droppedCount > 0) {
+      // Log for floor/gate tuning (R3) — never fails the prompt build.
+      console.error(`[appendAlayaLessons] dropped ${droppedCount}/${candidateCount} candidates below the cosine floor (${ALAYA_MIN_COSINE_DEFAULT}) or stack mismatch for query "${query}"`);
+    }
+    bijas = gated.slice(0, 3);
+    if (bijas.length === 0) return;
+
+    const modeEffective = recallData.mode_effective || 'hybrid';
+    const sectionLines = [
+      '## Process lessons (Alaya)',
+      `Query: "${query}" — ${bijas.length} seeds (mode=${modeEffective}).`,
+      ...bijas.map(b => {
+        const content = (b.content || '').replace(/\s+/g, ' ').trim().slice(0, 220);
+        return `- **${b.seed_type || 'seed'}** [${b.origin || 'unknown'}] ${content}`;
+      }),
+    ];
+
+    let section = sectionLines.join('\n');
+    if (section.length > 900) {
+      section = section.slice(0, 899) + '…';
+    }
+
+    lines.push('');
+    lines.push(...section.split('\n'));
+    lines.push('');
+  } catch { /* Alaya unavailable — graceful degradation */ }
+}
+
+function appendCognitiveRecall(lines, taskData, options = {}) {
+  // Extract recall keywords from task data (title, scope_paths, tags)
+  let keywords = [];
+  let scopeFiles = [];
+  try {
+    const parsed = typeof taskData === 'string' ? JSON.parse(taskData) : taskData;
+    if (parsed) {
+      if (parsed.title) {
+        const stopWords = new Set(['the','a','an','is','are','was','were','be','to','of','and','in','for','on','at','by','with','from','as','into','fix','task','add','update','implement']);
+        const words = parsed.title.replace(/[^a-zA-Z0-9_\s]/g, ' ').split(/\s+/).filter(w => w.length > 2 && !stopWords.has(w.toLowerCase()));
+        keywords.push(...words.slice(0, 5));
+      }
+      if (parsed.scope_paths && parsed.scope_paths.length > 0) {
+        for (const sp of parsed.scope_paths) {
+          const parts = sp.replace(/\\/g, '/').split('/');
+          const last = parts[parts.length - 1].replace(/\.[^.]+$/, '');
+          if (last && last.length > 2) {
+            keywords.push(last);
+            scopeFiles.push(last);
+          }
+        }
+      }
+      if (parsed.tags && parsed.tags.length > 0) {
+        keywords.push(...parsed.tags.filter(t => t.length > 2));
+      }
+    }
+  } catch { /* taskData not JSON, skip */ }
+
+  if (keywords.length === 0) return;
+  keywords = [...new Set(keywords)].slice(0, 8);
+
+}
+
+// Exact, shared wording — rigor:low ends its Working contract with this
+// bullet; rigor:medium repeats the identical sentence as its own line after
+// the short progress-note instructions (TASK_1998 spec: "the exact line").
+const RUNE_OPTIONAL_LINE = 'Inscribe exactly one rune (synapse_inscribe) if you learned something non-obvious; otherwise skip it.';
+
+/**
+ * TASK_1998: rigor:medium's short (3-line) progress-note instruction — the
+ * same write-then-run contract as appendProgressNoteInstructions()'s full
+ * block, compressed to a header + 2 lines instead of a full schema dump.
+ * No-op when taskData has no id (mirrors appendProgressNoteInstructions).
+ */
+function appendShortProgressNote(lines, taskData, options = {}) {
+  let taskId = null;
+  try {
+    const parsed = typeof taskData === 'string' ? JSON.parse(taskData) : taskData;
+    if (parsed) taskId = parsed.id;
+  } catch { /* taskData not JSON, skip */ }
+  if (!taskId) return;
+
+  const corePath = options.corePath || path.resolve(__dirname, '..', '..');
+  const corePathFwd = corePath.replace(/\\/g, '/');
+  const noteFile = `.kenaz/specialist/progress_note_${taskId}.json`;
+
+  lines.push(`## Progress Note (brief)`);
+  lines.push(`Write JSON to \`${noteFile}\`, then run: node "${corePathFwd}/.specialist/tools/phase-gate.js" note --task=${taskId} --from-file="${noteFile}"`);
+  lines.push(`Include: files touched, acceptance-criteria pass/fail, any deviations.`);
+}
+
+function appendCognitiveCheckpoint(lines, taskData, options = {}) {
+  const profile = promptProfile({ rigor: extractRigor(taskData), complexity: extractComplexity(taskData) });
+
+  // TASK_1998: PROCESS strictness is rigor-driven. low/medium collapse the
+  // six ritual sections (Before You Start recall, Before You Finish
+  // inscribe, Cognitive Checkpoint, Progress Note, Known Failures, Project
+  // Memory) into a compact contract — Ansuz already ran recall at
+  // scoping time; the full mandatory recall/inscribe ceremony is reserved
+  // for rigor:high. rigor:medium additionally gets a short progress-note
+  // instruction on top of the contract (dropped entirely for rigor:low).
+  if (profile.compactRitual) {
+    lines.push('');
+    lines.push(`## Working contract`);
+    lines.push(`- Read the files you touch before editing.`);
+    lines.push(`- Independent reads: fire them as parallel tool calls in ONE turn (e.g. Read a.js + Read b.js + Grep "foo" together), not one call per turn.`);
+    lines.push(`- Independent shell checks: one bash command with separators (e.g. \`echo ==a==; cmd1; echo ==b==; cmd2\`), not N bash calls.`);
+    lines.push(`- N similar items: one command over all N (e.g. one grep with alternation, or a loop), not N calls.`);
+    lines.push(`- One Write or a multi-hunk Edit beats many small edits.`);
+    lines.push(`- No self-check greps unless the card asks for them.`);
+    lines.push(`- Commit early and often; the worktree hard rules above still apply verbatim.`);
+    lines.push(`- Final report <= 20 lines: files touched, tests run, commit sha, uncertainties.`);
+    lines.push('');
+
+    if (profile.ritualTier === 'medium') {
+      appendShortProgressNote(lines, taskData, options);
+      lines.push('');
+    }
+    return;
+  }
+}
+
+function appendOutput(lines, skillDef) {
+  if (!skillDef.output) return;
+  lines.push(`## Expected Output`);
+  lines.push(`Primary: ${typeof skillDef.output.primary === 'string' ? skillDef.output.primary.trim() : JSON.stringify(skillDef.output.primary)}`);
+  if (skillDef.output.secondary) {
+    lines.push(`Secondary: ${typeof skillDef.output.secondary === 'string' ? skillDef.output.secondary.trim() : JSON.stringify(skillDef.output.secondary)}`);
+  }
+}
+
+// ─────────────────────────────────────────
+// Squad Synthesis：整合多份成員報告
+// ─────────────────────────────────────────
+
+/**
+ * 組裝 Squad Synthesis Agent 的 prompt
+ * 在所有成員完成後，由 headless.js 自動呼叫
+ * @param {object} skillDef - Squad 的 YAML 定義（含 merge 設定）
+ * @param {string} reportDir - 報告目錄名稱（如 squad-strategy）
+ * @returns {string} synthesis prompt
+ */
+function buildSquadSynthesisPrompt(skillDef, reportDir, options = {}) {
+  const lines = [];
+  const merge = skillDef.merge;
+
+  lines.push('## Role');
+  lines.push('你是 Squad Synthesis Agent（整合者）。');
+  lines.push('你的任務是讀取多份獨立分析報告，按照指定的整合策略產出最終報告。');
+  lines.push('你不是成員之一，你是整合者。你不偏袒任何一方。');
+  lines.push('');
+
+  // Principles（整合者也必須遵守的硬規則）
+  if (skillDef.principles) {
+    lines.push('## Principles (整合時也必須遵守)');
+    if (skillDef.principles.focus) {
+      lines.push(skillDef.principles.focus.trim());
+      lines.push('');
+    }
+    if (skillDef.principles.forbidden && skillDef.principles.forbidden.length > 0) {
+      lines.push('**禁止 (違反即失敗)**:');
+      for (const f of skillDef.principles.forbidden) lines.push(`- ❌ ${f}`);
+      lines.push('');
+    }
+    if (skillDef.principles.required && skillDef.principles.required.length > 0) {
+      lines.push('**必須遵守**:');
+      for (const r of skillDef.principles.required) lines.push(`- ✅ ${r}`);
+      lines.push('');
+    }
+  }
+
+  // Merge strategy
+  if (merge) {
+    lines.push(`## Merge Strategy: ${merge.strategy || 'default'}`);
+    if (merge.description) {
+      lines.push(merge.description.trim());
+    }
+    lines.push('');
+
+    // Merge steps — 核心指令
+    if (merge.steps && merge.steps.length > 0) {
+      lines.push('## Merge Steps (按順序執行)');
+      lines.push('');
+      for (const step of merge.steps) {
+        lines.push(`### Step: ${step.step}`);
+        if (step.action) lines.push(step.action.trim());
+        if (step.on_partial_failure) {
+          lines.push(`**Partial Failure Handling**: ${step.on_partial_failure.trim()}`);
+        }
+        lines.push('');
+      }
+    }
+  }
+
+  // Reports location
+  const reportPath = `.formation/reports/${reportDir}`;
+  lines.push('## Reports Location');
+  lines.push(`所有成員報告位於 \`${reportPath}/\` 目錄。`);
+  lines.push('');
+  lines.push('**執行步驟**:');
+  lines.push(`1. 用 Glob 工具掃描 \`${reportPath}/*.md\``);
+  lines.push('2. 排除 synthesis.md（那是你要寫的輸出）');
+  lines.push('3. 用 Read 工具逐一讀取每份報告');
+  lines.push('4. 按照上述 Merge Steps 逐步整合');
+  lines.push('');
+
+  // Squad members for context
+  if (skillDef.members && skillDef.members.length > 0) {
+    lines.push('## Squad Members（供參考）');
+    for (const m of skillDef.members) {
+      const roleFirstLine = (typeof m.role === 'string' ? m.role.split('\n')[0].trim() : m.name);
+      lines.push(`- **${m.name}** (${m.id}): ${roleFirstLine}`);
+    }
+    lines.push('');
+  }
+
+  // Output
+  lines.push('## Output');
+  lines.push(`將整合報告寫入 \`${reportPath}/synthesis.md\``);
+  lines.push('');
+  lines.push('報告格式依 Merge Strategy 而定。確保報告完整、結構清晰、附上各成員的核心觀點摘要。');
+  lines.push('');
+
+  // No taskData in scope (post-hoc synthesis, not a dispatched task card) —
+  // rigor/complexity both normalize to 'medium', landing in the compact-ritual
+  // branch (TASK_1998 two-axis policy).
+  appendCognitiveCheckpoint(lines, null, options);
+
+  return lines.join('\n');
+}
+
+// ─────────────────────────────────────────
+// Squad Debate：Round 2 交叉辯論 prompt
+// ─────────────────────────────────────────
+
+/**
+ * 組裝 Squad Round 2 Debate prompts
+ * 每個成員讀取其他人的 Round 1 報告，寫出針對性回應
+ * @param {object} skillDef - Squad YAML 定義
+ * @param {string} reportDir - 報告目錄名稱
+ * @returns {{ memberId: string, prompt: string, skill: string }[]}
+ */
+function buildSquadDebatePrompts(skillDef, reportDir) {
+  const members = skillDef.members || [];
+  const debate = skillDef.debate || {};
+  const reportPath = `.formation/reports/${reportDir}`;
+
+  return members.map(member => {
+    const lines = [];
+    const otherMembers = members.filter(m => m.id !== member.id);
+
+    // Role reminder
+    lines.push('## Role');
+    lines.push(`你是 **${member.name}**，這是你的第二輪分析（辯論回合）。`);
+    lines.push('');
+
+    // Original stance
+    const roleFirstLine = typeof member.role === 'string' ? member.role.split('\n')[0].trim() : '';
+    if (roleFirstLine) {
+      lines.push('## 你的立場（簡要提醒）');
+      lines.push(roleFirstLine);
+      lines.push('');
+    }
+
+    // Debate instructions (per-member)
+    if (member.debate_instructions) {
+      lines.push('## Debate Instructions');
+      lines.push(member.debate_instructions.trim());
+      lines.push('');
+    }
+
+    // Debate rules (squad-wide)
+    if (debate.rules && debate.rules.length > 0) {
+      lines.push('## Debate Rules');
+      for (const rule of debate.rules) {
+        lines.push(`- ${rule}`);
+      }
+      lines.push('');
+    }
+
+    // Reports to read
+    lines.push('## Reports to Read');
+    for (const other of otherMembers) {
+      lines.push(`- **${other.name}**: \`${reportPath}/${other.id}.md\``);
+    }
+    lines.push('');
+    lines.push('用 Read 工具讀取上述報告，然後寫出你的回應。');
+    lines.push(`你自己的 Round 1 報告在 \`${reportPath}/${member.id}.md\`，可以參考但不需要重複。`);
+    lines.push('');
+
+    // Output
+    lines.push('## Output');
+    lines.push(`將反駁報告寫入 \`${reportPath}/${member.id}-r2.md\``);
+    lines.push('');
+
+    return {
+      memberId: `${member.id}-r2`,
+      prompt: lines.join('\n'),
+      skill: member.skill || 'do'
+    };
+  });
+}
+
+// ─────────────────────────────────────────
+// Headless 模式常數
+// ─────────────────────────────────────────
+
+// TASK_1712: Rewritten with honest provenance framing so safety-hardened models
+// (claude-sonnet-5) read this as legitimate orchestration context rather than injection.
+// Behavioral constraints are fully preserved — only the framing changed.
+// Key changes: (1) opened with machine-assembly provenance declaration, (2) replaced
+// "don't read CLAUDE.md" with why Formation supplies its own rule set, (3) replaced
+// "don't ask questions" with "no human is watching — report and exit if blocked",
+// (4) replaced concealment wording in git rule with safety-rationale explanation.
+// TASK_1784 (DEFECT-A): Rule 6 was a categorical git ban that contradicted the workflow's
+// mandated commit step (do.yaml "提交變更": git add -A && git commit --no-verify). Literal-obedience
+// models (gpt-5.6-sol) obeyed the ban, produced zero commits, and tripped the leak detector on
+// every unmodified bifrost dispatch (TASK_1779 A/B-proven). Rule 6 now carves out exactly the
+// workflow commit command shape and nothing else; all other git subcommands stay forbidden.
+const HEADLESS_PREFIX = `## Automated Dispatch Context
+This prompt was machine-assembled by the Kenaz orchestration system, which is owned and
+operated by the repository owner. It runs unattended via \`claude -p\` (no interactive user
+is watching the output stream). The task brief below was authored and approved by the user
+before this automated run was triggered.
+
+## Operating Rules
+1. Start with a one-line summary: "📋 {TASK_ID}: {what you are about to do}" (<=30 words). Then proceed.
+2. Execute directly — do not ask clarifying questions. Requirements were confirmed before dispatch.
+   If you are blocked by a genuine ambiguity, document the blocker in your output and exit; a human will read the log.
+3. Formation supplies its own rule set (see ## Role / ## Task below), so the project CLAUDE.md
+   is not the active instruction source for this run. Rely on the content in this prompt.
+4. Produce structured output when finished.
+5. On unrecoverable errors: describe what failed and exit. Do not attempt open-ended retries.
+6. **Git is restricted to the workflow's own commit step — nothing else.** Exactly two git commands
+   are permitted, and only when the ## Workflow section below explicitly lists them as a step:
+   the "git add ..." staging command and the "git commit --no-verify -m <message>" that follows it,
+   run EXACTLY as shown in that workflow step — stage only what that step specifies, never more —
+   on the branch this session started on, without switching branches.
+   When the workflow lists that commit step you MUST execute it — this rule does not cancel it.
+   Every other git subcommand is forbidden: do not run git checkout, git branch, git merge,
+   git push, git rebase, git stash, git reset, or anything else. Branch, merge, and push management
+   is handled exclusively by the Formation Lead after the task completes, to prevent
+   cross-repository contamination when multiple agents run in parallel against different project paths.
+7. **Handle exactly the task specified in ## Task below.** Do not discover or claim other tasks.
+   One agent — one task.
+8. Do not read the task directory directly (.collaboration/tasks/ or .kenaz/tasks/). Use task-api.js.
+9. Only complete the task assigned to you (see ## Task for the Task ID). Do not mark other tasks done.
+
+`;
+// TASK_1833: rules 12-14 are shared VERBATIM across all sub-agent prefixes
+// (worktree / direct-write / cross-project-worktree). The only variance is
+// which rule number the commit instruction lives under. Kept as one template
+// so the three prefixes cannot drift apart (coupling rule: no near-duplicate
+// parallel impls).
+const subagentAsyncRules = (commitRuleNo) => `12. **⚠️ 你送出訊息就等於結束本次執行。** 你的最終訊息**就是**回傳值 —— 沒有「稍後回來接手」這回事。不要規劃「先讓出控制權、等背景工作完成再繼續」，那會直接結束你的執行並留下無人收拾的背景行程。
+13. **禁止啟動預期超過數分鐘的建置或測試** —— cold Rust build（kuzu 的 CMake 可跑十幾分鐘）、完整測試套件都屬此類。原因是結構性的：Bash 前景呼叫上限 10 分鐘，超時會被砍；改用背景跑則你沒有同步工作可做，只能送出訊息（見規則 12），於是留下持有 target dir 鎖的孤兒行程，後續建置全部空等。
+    - **正確做法**：改完程式碼 → commit（規則 ${commitRuleNo}）→ **直接回報結束**。在報告中寫明「未執行建置驗證」。
+    - **Rust 建置驗證一律由主線程（Ansuz）負責** —— 主線程有熱快取、能跨 turn 輪詢、能診斷並清理孤兒行程。這是分工，不是你偷懶。
+    - 這**不代表**你不必自我檢查。讀周邊程式碼、確認語法與型別、小範圍 grep 比對既有實作，這些輕量檢查仍然必須做。被禁止的只有「耗時數分鐘以上的建置與完整測試套件」。
+14. **禁止用 \`sleep\` 迴圈輪詢背景工作。** 這是規則 13 的同一個問題換一種寫法：你排下的 \`sleep\` 是獨立的 OS 行程，**你結束後它們不會跟著死**。每個到期都會重新喚醒你一次，而你醒來只會發現工作還沒完、再睡一次——實測單次喚醒消耗約 146K token 卻只做 0-3 個 tool call，一次任務殘留 30 個 \`sleep\` 行程。
+    - 不要寫 \`while ...; do sleep N; done\`、不要 \`sleep 300 && check\`、不要用背景 job 搭配輪詢來等待建置或測試。
+    - 需要等待就代表這件事不該由你做（見規則 13）。**commit 後直接回報結束**，把工作交給主線程。
+15. **禁止用 image name 殺行程。** \`taskkill /IM node.exe\`、\`Stop-Process -Name node\`、\`pkill -f node\` 之類的指令會殺掉整台機器上同名的所有行程 —— 2026-09-07 一個 agent 用 \`taskkill /F /IM node.exe /T\` 收拾自己卡住的測試，結果把用戶正在跑的 tauri dev（dashboard、next dev、MCP server）全部殺掉。
+    - 只能殺你自己 spawn 的 PID（記下 \`$!\` 或 child pid，用 \`taskkill /PID <pid>\` / \`Stop-Process -Id\`）。
+    - 測試可能卡住就一開始用 \`timeout <秒> <指令>\` 包起來，而不是事後找行程殺。
+    - 不確定某個行程是誰的，就不要碰它，寫進報告交給主線程。`;
+
+// TASK_1978 scaffold diet: hard-constraint bullets shared by SUBAGENT_PREFIX
+// and buildSubagentWorktreePrefix() — the WHY for each lives in
+// dispatch-detail/worktree-subagent-mode.md, not inline (kept out of the
+// hot prompt path; read it only when a rule is unclear). Deliberately
+// separate from subagentAsyncRules() above: that one still backs
+// SUBAGENT_PREFIX_DIRECT verbatim (untouched, out of TASK_1978 scope).
+const WORKTREE_DISPATCH_HARD_RULES = `2. CLAUDE.md 生效；完成輸出結果；卡住回報錯誤並結束。
+3. 改完立刻 commit（## Workflow，已排除 telemetry）－不等驗證；禁 push/切 branch/刪 worktree/stash/reset --hard。
+4. 送出訊息=結束；禁長建置/全測試（commit 後報未驗證，Rust 交 Ansuz）；禁 sleep 輪詢；禁用 image name 殺行程（只殺自己 PID）。
+5. 只做指定任務；不讀任務目錄；只用 task-api.js；worktree 禁 complete。`;
+
+// Sub-agent dispatch preamble — used when task is dispatched via Agent tool (isolation=worktree)
+// instead of claude -p (headless). Key differences from HEADLESS_PREFIX:
+// - Git IS allowed (worktree provides isolation; commits land on task branch, not user branch)
+// - CLAUDE.md IS active (running inside an interactive Claude Code session)
+// - Agent must commit changes to the worktree before returning
+const SUBAGENT_PREFIX = `[WORKTREE SUBAGENT MODE] 硬性規則：
+1. 先印摘要「📋 {TASK_ID}: {你準備做什麼}」，直接做，不問。
+${WORKTREE_DISPATCH_HARD_RULES}
+6. pwd 取得 worktree 路徑，Edit/Read/Write 皆用它，禁用主 repo 路徑。
+Details: .formation/tools/dispatch-detail/worktree-subagent-mode.md (Read only if needed)
+`;
+
+// TASK_1672: Direct-write prefix for CROSS-PROJECT sub-agent dispatch.
+// Used when projectPath is a sub-project (projectPath !== ROOT).
+// In that case the Agent tool has NO worktree isolation — cwd is the sub-project's
+// real working tree. The agent must edit files at the absolute sub-project paths
+// given in the "## Project Context" section injected by buildPrompt().
+// Rules that reference worktree path-prefixing or "主 repo 路徑" are OMITTED
+// because they actively contradict the injected "Working directory: <subproject>" context.
+const SUBAGENT_PREFIX_DIRECT = `[DIRECT-WRITE SUBAGENT MODE]
+你已被 Ansuz 透過 Agent tool 指派任務，目標是一個**子專案** (sub-project)。規則：
+1. 開始前先輸出一行摘要：「📋 {TASK_ID}: {你準備做什麼}」（一句話，不超過 30 字）。然後再動手。
+2. 直接執行，不要提問。需求已經確認過了。
+3. CLAUDE.md 已啟用 — 遵循其規則（此為互動式 Claude Code 環境）。
+4. 完成後輸出結構化結果。
+5. 遇到無法執行的問題，輸出錯誤描述後結束。
+6. **工作目錄 = 子專案根目錄**（見 ## Project Context 的 "Working directory" 欄位）。
+   - 使用該路徑作為 Edit/Read/Write 的絕對路徑前綴。
+   - 不要自行猜測路徑；以 ## Project Context 注入的路徑為準。
+7. **Git 操作被允許且必要** — 你直接在子專案的**共用工作樹**提交（無 worktree 隔離）：
+   - **COMMIT FIRST（順序不可調換）**：改完程式碼就**立刻** \`git add <只列出你本次明確編輯過的檔案路徑> && git commit --no-verify -m "[{TASK_ID}] task completed"\`，**不要等驗證通過再 commit**。曾有兩個 agent 在建置中途結束、零 commit，工作全靠主線程手動搶救。寧可 commit 三次也不要一次都沒有。
+   - ⚠️ **只 stage 你本次明確編輯過的檔案** — 你與使用者、其他 agent 共用同一個工作樹，嚴禁一次 stage 整個工作樹（TASK_188 曾因此把 392 個無關檔案掃進單一 commit）。
+   - 禁止 git push 到遠端。不可切換 branch。
+${subagentAsyncRules(7)}
+8. **你只負責下方 ## Task 指定的那一個任務。** 不要讀取任務目錄去找其他任務、不要認領其他任務。
+9. 嚴禁直接讀取任務目錄（.collaboration/tasks/ 或 .kenaz/tasks/）。必須透過 task-api.js 操作任務。
+10. 只能操作你自己被指派的任務（見 ## Task 的 Task ID）。不要標記其他任務為完成。
+11. **禁止執行 task-api.js complete** — 任務完成由主 thread（Ansuz）在驗證後處理。
+
+`;
+
+/**
+ * TASK_1833: prefix for CROSS-PROJECT sub-agent dispatch WITH worktree isolation.
+ * The Agent tool's own isolation:'worktree' cannot isolate another repo — its
+ * worktree derives from the CONVERSATION cwd repo (TASK_1672/1593), so
+ * dispatch.js pre-creates a worktree INSIDE the target repo and this prefix
+ * points the agent at it. Keeps the sub-agent (subscription) billing path
+ * while gaining real isolation (no shared-tree index.lock collisions).
+ * @param {string} worktreePath - absolute worktree path inside the target repo
+ * @param {string} branchName - task branch checked out in the worktree
+ * @param {string} projectPath - the target sub-project's MAIN working tree root
+ * @returns {string}
+ */
+function buildSubagentWorktreePrefix(worktreePath, branchName, projectPath) {
+  return `[CROSS-PROJECT WORKTREE SUBAGENT MODE] wt=${worktreePath} repo=${projectPath} branch=${branchName}
+1. 先印摘要「📋 {TASK_ID}: {你準備做什麼}」，直接做，不問。
+${WORKTREE_DISPATCH_HARD_RULES}
+6. 工作目錄=上述 worktree；Edit/Write、cd/git -C 皆用它；禁編輯主樹；Synapse projectPath 用 ${projectPath}。
+Details: .formation/tools/dispatch-detail/cross-project-worktree.md (Read only if needed)
+`;
+}
+
+const LEGION_SYSTEM_PREFIX = `You are the TEAM LEAD using Claude Code's OFFICIAL "agent teams" feature.
+
+YOUR ROLE: Team Lead
+- You are RESPONSIBLE for this task's success or failure.
+- You MUST coordinate teammates and ensure they complete their work.
+- You CANNOT end the session until ALL teammates have reported back.
+- If you end early, the task FAILS and it's YOUR fault.
+
+This is NOT the project's .formation/ directory system. Do NOT read .formation/ files.
+To create teammates, use natural language like: "Create a teammate named X who handles Y"
+Each teammate is a separate Claude instance running in parallel.
+
+`;
+
+const LEGION_AUTO_EXECUTE = `
+
+BEFORE YOU START - OUTPUT YOUR PLAN:
+First, explain exactly what you will do step by step:
+1. What teammates will you create?
+2. How will you wait for their results?
+3. What tools will you use to poll for messages?
+4. When will you know all teammates are done?
+
+RULES:
+1. Do NOT ask questions. Execute immediately after stating your plan.
+2. Do NOT read CLAUDE.md - this is a separate system.
+3. Create teammates using natural language descriptions.
+4. IMPORTANT: Use "sonnet" model for ALL teammates to reduce cost.
+
+WAITING FOR TEAMMATES - CRITICAL:
+5. After spawning ALL teammates, you MUST enter a polling loop.
+6. In the loop: call "sleep 5" with Bash, then check if teammates sent messages.
+7. Teammates send results via SendMessage - you will see them as incoming user messages.
+8. Keep looping (sleep + check) until you have received messages from ALL teammates.
+9. Do NOT end until you have ACTUAL CONTENT from every single teammate.
+10. If a teammate is slow, keep waiting - do NOT give up or timeout early.
+11. Only after ALL teammates report back, synthesize their findings into final answer.`;
+
+// ─────────────────────────────────────────
+// Legion Lead Prompt 組裝
+// ─────────────────────────────────────────
+
+/**
+ * 組裝 Legion Lead 的完整 headless prompt
+ * 複製 Sunny teammate 的成功模式：
+ *   SYSTEM_PREFIX + 成員列表（自然語言）+ 任務 + AUTO_EXECUTE
+ */
+function buildLegionLeadPrompt(config) {
+  let prompt = LEGION_SYSTEM_PREFIX;
+
+  prompt += `Create an agent team with ${config.members.length} teammates:\n`;
+  config.members.forEach((m, i) => {
+    const lines = m.prompt.split('\n');
+    const roleIdx = lines.findIndex(l => l.startsWith('## Role'));
+    let desc = m.name;
+    if (roleIdx >= 0) {
+      for (let j = roleIdx + 1; j < lines.length && j < roleIdx + 5; j++) {
+        const line = lines[j].trim();
+        if (line && !line.startsWith('#')) { desc = line; break; }
+      }
+    }
+    prompt += `${i + 1}. "${m.name}" - ${desc}\n`;
+  });
+  prompt += '\n';
+
+  const taskMatch = config.lead.prompt.match(/## Task\n([\s\S]*?)(?=\n##|$)/);
+  if (taskMatch) {
+    prompt += `Task: ${taskMatch[1].trim()}\n`;
+  }
+
+  prompt += LEGION_AUTO_EXECUTE;
+  return prompt;
+}
+
+module.exports = {
+  recordSkillUsage,
+  buildPrompt, buildSquadSynthesisPrompt, buildSquadDebatePrompts,
+  buildLegionLeadPrompt,
+  resolveModules,
+  HEADLESS_PREFIX,
+  SUBAGENT_PREFIX,
+  SUBAGENT_PREFIX_DIRECT,
+  buildSubagentWorktreePrefix,
+  // TASK_1978: exported for direct unit-testing of the compressed ceremony
+  // sections (byte budget + hard-constraint presence), without exercising
+  // the full buildUnitPrompt pipeline (which touches memory/cortex/episodic
+  // context and needs a live project).
+  appendCognitiveCheckpoint,
+  // TASK_1992: exported for direct unit-testing of the Alaya process-lessons
+  // section with an injected mcpCaller stub (no live MCP dependency).
+  buildTaskContextQuery,
+  appendAlayaLessons,
+  // TASK_2101: exported for direct unit-testing of the absolute-relevance
+  // gate (cosine floor + stack match) that appendAlayaLessons applies before
+  // any bija is rendered into the dispatch prompt.
+  deriveTaskStack,
+  deriveBijaStack,
+  passesAlayaRelevanceGate,
+  ALAYA_MIN_COSINE_DEFAULT,
+  ALAYA_STACK_OVERRIDE_COSINE,
+  ALAYA_CANDIDATE_POOL,
+  // TASK_1998: exported for dispatch.js (Related Files Preview gating,
+  // prompt-byte-stats telemetry) and for direct unit-testing of the
+  // two-axis prompt policy (context volume by complexity, process
+  // strictness by rigor).
+  promptProfile,
+  extractRigor,
+  extractComplexity,
+  splitPromptSections,
+  // TASK_1998 R2 follow-up: exported for direct unit-testing of Known
+  // Failures/Project Memory rigor gating against the real .failure/.memory
+  // dirs (no live-project mocking needed).
+  appendMemoryContext,
+  // TASK_2082: exported for direct unit-testing of the Rust-check reminder
+  // gate (scope detection + core-crate existence + isolated-worktree gate)
+  // without needing a live dashboard/src-tauri checkout on the test machine.
+  hasRustScope,
+  appendRustCheckReminder,
+  // TASK_2082: exported so prompt.test.js can exercise the commit-step +
+  // Rust-check-reminder wiring directly, without paying for buildUnitPrompt's
+  // other live-project-dependent appends (memory/cortex/episodic context).
+  appendWorkflow,
+  // TASK_2082 defect fix: exported for dispatch.js to call at the prefix +
+  // body composition point (rewrites hard rule 4's wording in-place instead
+  // of relying on "later instructions win"), and for direct unit-testing.
+  applyRustCheckToPrefix,
+};