kenaz 0.3.5 → 0.3.6

package/core/.claude/commands/Ansuz.md

@@ -23,6 +23,7 @@ ARGUMENTS 含 `[專案: X]` 或 `--project-path X` → PROJECT_PATH = X，下方
 - 有**對照組**：證明測試在舊程式上會失敗，或修改前後結果不同。
 - subagent 回報「未驗證」的項目，由你補驗或明講仍未驗證。
 - 合併：`git merge` 後跑相關測試（或 `node .specialist/Ansuz/tools/verify-and-land.js`），用這個專案自己的測試指令。
+- 檔案長度：verify-and-land 合併前會跑 `check-file-size`（警告 1000 / 上限 2000 行，既有超長檔只擋「未配套拆分的增長」）；被擋就按職責拆成 module / component / hook。
 - 只在 Kenaz 核心 repo 本身：Rust 測試走 `npm run test:rust` / `dev/scripts/rust-verify-worktree.js`。
 
 ## 回報

package/core/.formation/native/claude/README.md

@@ -51,7 +51,7 @@ no surprise dependencies.
 4. When the user picks an entry, the id is written into
    `.kenaz/dashboard-models.json` via
    `POST /api/dashboard/settings/models` and consumed by
-   `kenaz_dispatch` / `SpecialistPanel.handleLaunch`.
+   `SpecialistPanel.handleLaunch`.
 
 ## Adding a new model
 

package/core/.formation/role-map.yaml

@@ -3,8 +3,8 @@
 # Amelia 判斷 role 時參考此表，dispatch 時用此表解析 --role 路徑
 #
 # Usage:
-#   node .formation/tools/headless-v2.js --base=do --role=developer --task=TASK_XXX
-#   headless-v2 會查此表找到 skill_path → 載入該 YAML 的 role context
+#   node .formation/tools/dispatch.js --skill=do --task=TASK_XXX --dispatch-mode=subagent
+#   （此表僅供 Amelia 判斷 role 參考；dispatch.js 不讀取它。headless-v2 已退役）
 
 version: "2.0"
 
@@ -259,7 +259,7 @@ roles:
       - 新功能開發
 
 # ─────────────────────────────────────────
-# Base Skills（headless-v2 的 --base 選項）
+# Base Skills（歷史：原 headless-v2 的 --base 選項）
 # ─────────────────────────────────────────
 
 bases:

package/core/.formation/spec/task_operations.yaml

@@ -4,7 +4,7 @@
 #
 # Consumers:
 #   A: .collaboration/core/task-api.js       — full lifecycle (create/claim/complete/move/delete/get/list)
-#   B: .formation/tools/headless.js          — dispatch coordinator (no direct state mutation; triggers post-complete)
+#   B: .formation/tools/dispatch.js          — dispatch coordinator (no direct state mutation; triggers post-complete)
 #   C: .formation/tools/post-complete.js     — close-out only (active→done or active→blocked; never creates)
 #   D: dashboard kenaz MCP tools (kenaz.rs)  — CRUD subset only (list/get/create/update/delete via task-api CLI proxy)
 #
@@ -13,7 +13,7 @@
 #   MCP does NOT have standalone claim, complete, or move tools — these are action values in tool_task_update.
 #   task-api.js (consumer A) owns the full state machine and all lifecycle transitions.
 #   post-complete.js (consumer C) is exclusively close-out; it calls task-api complete/move internally.
-#   headless.js (consumer B) coordinates dispatch and triggers post-complete on task completion.
+#   dispatch.js (consumer B) coordinates dispatch and triggers post-complete on task completion.
 #
 # STATUS DUALITY (known divergence):
 #   Filesystem directory names (canonical): backlog, active, done, blocked, cancel, archived
@@ -153,7 +153,7 @@ operations:
     post_complete_trigger: true
     known_asymmetry:
       - "moveTask(taskId, 'done') achieves same filesystem effect but does NOT trigger post-complete"
-      - "Consumer B (headless.js) bypasses via FORMATION_HEADLESS=1 and calls post-complete separately"
+      - "Consumer B (dispatch.js) does not mutate task state itself; post-complete runs separately"
     error_modes:
       - "Task not found → throws"
       - "post-complete failure → logged as warning; task already moved to done (non-atomic)"

package/core/.formation/tools/__tests__/subagent-bifrost-guard.test.js

@@ -95,8 +95,8 @@ setModels({ dispatchModel: 'gpt-5-codex', dispatchFamily: 'bifrost', dispatchAda
   check('reject bifrost+adapter: no agentParams on stdout', !(r.stdout || '').includes('agentParams'), (r.stdout || '').slice(0, 200));
   check('reject bifrost+adapter: invariant wording (refusing to silently dispatch)',
     (r.stderr || '').includes('refusing to silently dispatch with the native Claude CLI'), (r.stderr || '').slice(-400));
-  check('reject bifrost+adapter: remediation points to Formation dispatch (kenaz_dispatch)',
-    (r.stderr || '').includes('kenaz_dispatch'), (r.stderr || '').slice(-400));
+  check('reject bifrost+adapter: remediation tells the user to pick a Claude model',
+    (r.stderr || '').includes('Select a Claude model') && !(r.stderr || '').includes('kenaz_dispatch'), (r.stderr || '').slice(-400));
 }
 
 // ── [3] reject: dispatchFamily=bifrost, adapter missing/empty ───────────────
@@ -175,8 +175,8 @@ setModels({ dispatchModel: 'claude-nova-9', dispatchFamily: 'claude' });
   check('unmappable model: loud stderr (refusing to silently guess)',
     (r.stderr || '').includes("dispatchModel 'claude-nova-9' cannot be mapped") &&
     (r.stderr || '').includes('refusing to silently guess'), (r.stderr || '').slice(-400));
-  check('unmappable model: remediation points to Formation dispatch (kenaz_dispatch)',
-    (r.stderr || '').includes('kenaz_dispatch'), (r.stderr || '').slice(-400));
+  check('unmappable model: remediation points at the model selection, not retired kenaz_dispatch',
+    (r.stderr || '').includes('Fix the model selection') && !(r.stderr || '').includes('kenaz_dispatch'), (r.stderr || '').slice(-400));
 }
 
 // ── [9]-[11] TASK_2032: subagent dispatch activates the card like the ────────

package/core/.formation/tools/dispatch.js

@@ -990,14 +990,14 @@ async function getSubagentDispatchParams(options) {
   }
   if (routing.family === 'bifrost' && !isCodex) {
     if (!routing.adapter) {
-      console.error('❌ dashboard-models.json sets dispatchFamily=bifrost but dispatchAdapter is missing/empty — refusing to silently dispatch with the native Claude CLI. Fix the model selection (Quick Actions → Default Models) or dashboard-models.json, then use Formation dispatch (kenaz_dispatch).');
+      console.error('❌ dashboard-models.json sets dispatchFamily=bifrost but dispatchAdapter is missing/empty — refusing to silently dispatch with the native Claude CLI. Fix the model selection (Quick Actions → Default Models) or dashboard-models.json.');
     } else {
-      console.error(`❌ dashboard-models.json sets dispatchFamily=bifrost (dispatchAdapter '${routing.adapter}') — sub-agent dispatch cannot run non-Claude models (the Agent tool only accepts Claude models); refusing to silently dispatch with the native Claude CLI. Use Formation dispatch (kenaz_dispatch) instead — it routes through the Bifrost adapter.`);
+      console.error(`❌ dashboard-models.json sets dispatchFamily=bifrost (dispatchAdapter '${routing.adapter}') — sub-agent dispatch cannot run non-Claude models (the Agent tool only accepts Claude models); refusing to silently dispatch with the native Claude CLI. Select a Claude model in Default Models.`);
     }
     return null;
   }
   if (!isCodex && routing.family && routing.family !== 'claude') {
-    console.error(`❌ dashboard-models.json sets unsupported dispatchFamily '${routing.family}' (expected 'claude' or 'bifrost') — refusing to silently dispatch with the native Claude CLI. Fix the model selection (Quick Actions → Default Models) or use Formation dispatch (kenaz_dispatch).`);
+    console.error(`❌ dashboard-models.json sets unsupported dispatchFamily '${routing.family}' (expected 'claude' or 'bifrost') — refusing to silently dispatch with the native Claude CLI. Fix the model selection (Quick Actions → Default Models).`);
     return null;
   }
 
@@ -1017,7 +1017,7 @@ async function getSubagentDispatchParams(options) {
   // TASK_2315: Codex inherits the session model — nothing to translate or pass.
   const translated = isCodex ? { model: null, lossless: true } : translateModelForAgentTool(rawModel);
   if (!isCodex && !translated.model) {
-    console.error(`❌ ${resolution.label} '${rawModel}' cannot be mapped to an Agent tool model family (${AGENT_TOOL_MODEL_ENUM.join('|')}) — refusing to silently guess a substitute model. Fix the model selection (Quick Actions → Default Models) or use Formation dispatch (kenaz_dispatch), which accepts full model ids via --dispatch-model.`);
+    console.error(`❌ ${resolution.label} '${rawModel}' cannot be mapped to an Agent tool model family (${AGENT_TOOL_MODEL_ENUM.join('|')}) — refusing to silently guess a substitute model. Fix the model selection (Quick Actions → Default Models).`);
     return null;
   }
   const dispatchModel = translated.model;
@@ -1025,7 +1025,7 @@ async function getSubagentDispatchParams(options) {
     ? { requested: rawModel, inherited: true }
     : { requested: rawModel, agentToolModel: dispatchModel, granularityLoss: !translated.lossless };
   if (!translated.lossless) {
-    process.stderr.write(`[dispatch] model '${rawModel}' → Agent tool family '${dispatchModel}' — the Agent tool only expresses family names (${AGENT_TOOL_MODEL_ENUM.join('|')}); version/speed selections (e.g. 5 vs 4.x, [1m]) are NOT expressible on the subagent path. If the exact version matters, use Formation dispatch (kenaz_dispatch), which passes full model ids.\n`);
+    process.stderr.write(`[dispatch] model '${rawModel}' → Agent tool family '${dispatchModel}' — the Agent tool only expresses family names (${AGENT_TOOL_MODEL_ENUM.join('|')}); version/speed selections (e.g. 5 vs 4.x, [1m]) are NOT expressible on the subagent path. If the exact version matters, choose a model whose family the Agent tool can express.\n`);
   }
   // TASK_1998 R3 (+ two-axis policy): the resolved choice, always printed
   // (unlike the granularity block above, which only fires on lossy translation).

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

@@ -171,6 +171,10 @@ function buildSubagentPrompt(skillDef, taskInput, taskData, options = {}) {
   // Ponytail A/B 2026-10-10: the arm without this line broke an existing fixture test it never ran.
   lines.push('Before editing, grep the callers, tests and fixtures your change reaches; fix what it breaks. Least code that completes the card: reuse existing helpers, no unrequested abstraction, option or duplicate implementation.');
   lines.push('Run the tests the card names (narrow, not the full suite); say what you did not verify.');
+  // The worktree branches off the project's current branch; user projects are not always on `main`.
+  const sizeBase = (require('child_process').spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: options.projectPath || process.cwd(), encoding: 'utf8' }).stdout || '').trim() || 'main';
+  const sizeCorePath = options.corePath || resolveCorePath(options.projectPath) || path.resolve(__dirname, '..', '..');
+  lines.push(`Before reporting run \`node ${sizeCorePath}/dev/scripts/check-file-size.js --base ${sizeBase} --head HEAD\`; if it BLOCKs, split by responsibility (module / component / hook) first.`);
   const onBlocked = skillDef.collaboration && skillDef.collaboration.on_blocked;
   if (onBlocked && onBlocked.run) {
     lines.push(`Blocked: \`${buildTaskApiRewriter(options)(onBlocked.run).replace(/\{task_id\}/g, taskId)}\` and explain.`);

package/core/.formation/unit/do.yaml

@@ -48,10 +48,8 @@ collaboration:
         - 根據 acceptance_criteria 驗證成果
       # TASK_1819: 此處原有的 worktree_path_rule 欄位已移除 — 它是死欄位，
       # prompt.js 的 appendWorkflow 只讀 step/run/note/actions，從未渲染它，
-      # 且其範例路徑早已過時。實際生效的 worktree 路徑規則由 runner.js 在
-      # spawn 時注入（spawnClaude/spawnBifrost 的 "[WORKTREE] All file
-      # operations MUST use paths under: <worktreeDir>" 前綴，含具體路徑），
-      # Agent-tool 派工另由 prompt.js SUBAGENT_PREFIX 規則 11 覆蓋。
+      # 且其範例路徑早已過時。實際生效的 worktree 路徑規則由
+      # prompt.js SUBAGENT_PREFIX 規則 11 覆蓋（原 runner.js 注入已隨 headless 路徑移除）。
 
     # 注意（TASK_1819）：下方 run 的 git add -A 只會在隔離模式（worktree /
     # subagent）原樣渲染；serial 共用工作樹模式下 prompt.js appendWorkflow

package/core/.rule/general/agent-workflow.yaml

@@ -543,15 +543,15 @@ rules:
   - id: "AGT-010"
     title: "Dispatch 後切回 User Branch"
     description: |
-      Formation headless.js dispatch 會在獨立進程中建立 task branch（task/task_XXX），
+      （已退役）Formation headless dispatch 曾在獨立進程中建立 task branch（task/task_XXX），
       完成後 post-complete.js 會 merge 回 user branch。但呼叫者（Ansuz/Agent）的
       working tree 仍停留在 task branch 上。
 
       如果 dispatch 後繼續在同一 session 做其他改動，會意外 commit 到 task branch，
       而不是 user branch。用戶在桌面端會看到 branch 不一致。
     severity: "must"
-    rationale: "headless.js 是獨立進程，不會切換呼叫者的 git working tree"
-    trigger: "Formation dispatch（headless.js）完成後，Ansuz 或 Agent 要做下一個改動之前"
+    rationale: "headless dispatch 是獨立進程（已退役，僅供歷史參照），不會切換呼叫者的 git working tree"
+    trigger: "legacy Formation dispatch 完成後，Ansuz 或 Agent 要做下一個改動之前"
     workflow:
       - step: 1
         action: "確認 dispatch 完成（task status = completed）"
@@ -568,5 +568,5 @@ rules:
       ❌ 多個 task 共用同一個 task branch（每個 task 應有自己的 branch）
     applies_to:
       - "Ansuz（PM dispatch 後繼續做其他工作）"
-      - "任何使用 headless.js 的 Agent"
+      - "任何仍經 legacy Formation dispatch 的 Agent"
       - "用戶手動 dispatch 後"

package/core/.rule/general/file-size-threshold.yaml

@@ -9,8 +9,8 @@ rules:
       Single-file growth is the primary vector for SRP violations in this codebase.
       Enforce line-count thresholds to force extraction before files become unmaintainable.
     thresholds:
-      warn: 2000
-      hard_limit: 4000
+      warn: 1000
+      hard_limit: 2000
     scope:
       include:
         - "**/*.rs"
@@ -22,20 +22,32 @@ rules:
         - "**/target/**"
         - "**/node_modules/**"
         - "**/*.test.*"
+        - "**/*_test.*"
+        - "**/tests/**"
+        - "**/__tests__/**"
+        - "**/*.generated.*"
         - "**/*.spec.*"
         - "**/*.d.ts"
         - "**/generated/**"
     enforcement:
       on_task_design: |
-        When designing a task that adds >50 LOC to a file already above warn threshold (2000 lines):
+        When designing a task that adds >50 LOC to a file already above warn threshold (1000 lines):
         1. Check current file size (wc -l or kenaz_lsp_symbols)
         2. If file > warn: acceptance criteria MUST include "extract [new responsibility] into separate module"
         3. If file > hard_limit: task MUST be split — one task for extraction, one for the new feature
         Ansuz must enforce this at task design time, not defer to the implementing agent.
       on_code_review: |
-        Any PR that increases a file past hard_limit (4000 lines) without a paired extraction
+        Any PR that increases a file past hard_limit (2000 lines) without a paired extraction
         commit is a Blocker-level review finding.
       existing_debt: |
+        Decision 2026-10-10 (user, via Ansuz): warn 1000 / hard_limit 2000 lines for source
+        files; tests and generated files are excluded. Existing over-limit files are
+        GRANDFATHERED: dev/scripts/check-file-size.js only blocks growth of such a file (>50 LOC)
+        without a paired extraction (a new file in the same change), or a file newly crossing
+        hard_limit. Split by responsibility (module / component / hook) when you touch one.
+        Enforced in verify-and-land.js (file-size step, before merge) and the subagent
+        "Verify and report" prompt line. Without this yaml (user project) the script uses the
+        same defaults built in.
         Files currently above hard_limit are tracked as architecture debt.
         Extraction tasks should be created incrementally — do not attempt big-bang refactors.
         Follow the three-stage pattern: build-map → plan-split → minimal-patch.

package/core/.rule/general/rust-verify-target.yaml

@@ -33,7 +33,6 @@ rules:
       file: "dev/scripts/verify-target-dir.js"
       consumers:
         - "dev/scripts/run-rust-tests.js (defaults CARGO_TARGET_DIR when unset)"
-        - ".formation/tools/runner.js (worktree dispatch env, 2 call sites)"
         - ".formation/tools/integration.js (in-lock re-verify env)"
       shell_usage: "CARGO_TARGET_DIR=$(node dev/scripts/verify-target-dir.js) cargo check --lib -p kenaz-dashboard"
 

package/core/.rule/general/system-invariants.yaml

@@ -90,19 +90,6 @@ invariants:
 # Parallel execution caps, locks, isolation boundaries
 # ============================================================================
 
-  - name: max_parallel_dispatches
-    category: concurrency
-    formula: "concurrent_worktree_dispatches ≤ MAX_PARALLEL"
-    bound: "MAX_PARALLEL = 5"
-    enforcement: |
-      Semaphore in formations.js dispatch loop — when count reaches
-      MAX_PARALLEL, new dispatches wait. Logs "Max parallel dispatches
-      reached (N/5), waiting...".
-    violation_detection: |
-      Count live worktree dispatches (.formation/worktrees/task_*/ with
-      active child processes); if > 5, semaphore leaked.
-    source: ".formation/tools/formations.js#L773-L810 (MAX_PARALLEL semaphore)"
-
   - name: worktree_isolation_boundary
     category: concurrency
     formula: |
@@ -111,17 +98,13 @@ invariants:
        repo paths)
     bound: "one worktree per active dispatch; no cross-worktree writes"
     enforcement: |
-      runner.js spawn-time prompt injection — spawnClaude() and spawnBifrost()
-      prepend "[WORKTREE] All file operations MUST use paths under:
-      <worktreeDir>" (the CONCRETE path) to the final prompt whenever
-      worktreeDir is set. Agent-tool dispatch additionally carries
-      SUBAGENT_PREFIX rule 11 (WORKTREE FILE PATH RULE) in prompt.js.
-      (TASK_1819: the former do.yaml worktree_path_rule field was a dead
-      field — never rendered by prompt.js — and has been removed.)
+      Agent-tool dispatch carries SUBAGENT_PREFIX rule 11 (WORKTREE FILE
+      PATH RULE) in prompt.js. (The former runner.js spawn-time "[WORKTREE]"
+      injection was removed with the headless path, TASK_2401.)
     violation_detection: |
       Agent Edits a path under main repo root while cwd is a worktree →
       `git add -A` in worktree finds no changes. See FAIL-013.
-    source: ".formation/tools/runner.js#L958,L1069 ([WORKTREE] prompt injection) + .formation/tools/prompt.js SUBAGENT_PREFIX rule 11"
+    source: ".formation/tools/prompt.js SUBAGENT_PREFIX rule 11"
     failure_witness: ".failure/agent-execution/FAIL-013-search-cwd-drift-and-case-mismatch.yaml"
 
   - name: per_project_dispatch_lock
@@ -129,13 +112,13 @@ invariants:
     formula: "per-project dispatch-lock serializes non-worktree dispatches"
     bound: "1 in-flight serial dispatch per project at a time"
     enforcement: |
-      Dispatch-lock fallback in formations.js — when worktree parallel
-      slot unavailable or task unsuitable for worktree, fall back to
-      per-project serial lock.
+      Dispatch-lock fallback in dispatch.js (tryAcquireDispatchLock) — when a
+      worktree is unavailable or the task is unsuitable for one, fall back
+      to the per-project serial lock.
     violation_detection: |
       Two concurrent non-worktree dispatches writing the same project
       state (e.g., task-api moves). Lock contention visible in logs.
-    source: ".formation/tools/formations.js#L773 (parallel semaphore + serial dispatch-lock fallback)"
+    source: ".formation/tools/dispatch.js (tryAcquireDispatchLock) + .formation/tools/utils.js (dispatchLockPath)"
 
 # ============================================================================
 # CATEGORY: cognitive

package/core/.specialist/Ansuz/SYSTEM_DOC.md

@@ -36,7 +36,7 @@
 身份: "Ansuz = 產品全生命週期引擎（PM + Lead 合一）"
 行為規則:
   ❌ 不 invoke 其他 Skill — 不切換身份
-  ✅ 需要執行時 → Formation 系統 dispatch（Task tool + headless.js）
+  ✅ 需要執行時 → Agent tool subagent dispatch（dispatch.js --dispatch-mode=subagent）
   ✅ 本體負責：需求理解、任務設計、陣型判斷、調度、追蹤、回報
   ❌ 不親自寫程式碼 — 只做決策和調度
 ```
@@ -44,7 +44,7 @@
 **工作模式**：
 - **Ansuz = 指揮官 + 調度者**，不是執行者
 - 所有實作交給 Formation 系統的 agent（developer, backend, designer...）
-- 通過 `.formation/tools/headless.js` 啟動獨立 Claude CLI 進程執行任務
+- 通過 `.formation/tools/dispatch.js` 組裝 prompt，再由 Agent tool subagent 執行任務
 
 ### 2. 事件驅動生命週期（7 Phases）
 
@@ -146,7 +146,7 @@ fi
 
 # 子專案範例
 node {CORE}/.collaboration/core/task-api.js --project-path {PROJECT_PATH} list
-node {CORE}/.formation/tools/headless.js --project-path {PROJECT_PATH} --skill=do --task=TASK_XXX
+node {CORE}/.formation/tools/dispatch.js --project-path {PROJECT_PATH} --skill=do --task=TASK_XXX --dispatch-mode=subagent
 node {CORE}/.formation/tools/post-complete.js --task=TASK_XXX --project-path={PROJECT_PATH}
 ```
 
@@ -154,48 +154,26 @@ node {CORE}/.formation/tools/post-complete.js --task=TASK_XXX --project-path={PR
 
 ### 2. Dispatch 執行機制
 
-**工具**: `.formation/tools/headless.js`
-**方法**: Bash tool → `node headless.js` → 啟動獨立 Claude CLI 進程
+**工具**: `.formation/tools/dispatch.js`
+**方法**: Bash tool → `node dispatch.js --dispatch-mode=subagent` → 取回 `promptText` + `agentParams` → Agent tool 開 subagent
+（headless CLI 進程、squad/legion 陣型已退役；只剩 unit/solo skill。）
 
 **CLI 命令格式**：
 
 ```bash
 # Unit 陣型
-node .formation/tools/headless.js --skill=do --task=TASK_XXX
+node .formation/tools/dispatch.js --skill=do --task=TASK_XXX --dispatch-mode=subagent
 
 # Solo 陣型
-node .formation/tools/headless.js --formation=solo --skill=strategy --task=TASK_XXX
-
-# Squad 陣型
-node .formation/tools/headless.js --formation=squad --skill=blitz --task=TASK_XXX
-
-# Legion 陣型
-node .formation/tools/headless.js --formation=legion --skill=forge --task=TASK_XXX
-```
-
-**並行模式**：
-
-```javascript
-// 單任務（單一 Bash）
-Bash(run_in_background: true): node headless.js --task=TASK_148
-
-// 並行多任務（多個 Bash 同時啟動）
-Bash(run_in_background: true): node headless.js --task=TASK_148
-Bash(run_in_background: true): node headless.js --task=TASK_149
-Bash(run_in_background: true): node headless.js --task=TASK_150
-
-// 有依賴（順序執行）
-Bash: node headless.js --task=TASK_147
-// 等待完成後
-Bash: node headless.js --task=TASK_148
+node .formation/tools/dispatch.js --formation=solo --skill=strategy --task=TASK_XXX --dispatch-mode=subagent
 ```
 
 **關鍵規則**：
 - ✅ 所有調度必須經過 `.collaboration` 任務系統
-- ✅ 流程：create → claim → dispatch(headless.js) → complete
-- ✅ 用 Bash tool 呼叫 headless.js，`run_in_background=true` 實現並行
+- ✅ 流程：create → dispatch.js(subagent) → Agent tool → complete
+- ✅ 有依賴 → 前一個完成再 dispatch 下一個；同一 project 序列化
 - ❌ 不跳過任務系統直接 dispatch
-- ❌ 不用 Task tool 開 subagent 繞過 Formation（Formation 有 prompt 組裝、log、principles 注入）
+- ❌ 不手寫 subagent prompt — 用 dispatch.js 組裝（prompt 組裝、principles 注入）
 
 ### 3. Scope 安全保證
 
@@ -254,7 +232,7 @@ rigor: "medium"  # low | medium | high
 dependencies: ["TASK_147"]  # 真依賴（B 的輸入 = A 的輸出）
 scope_paths:  # 修改的檔案/目錄（用於衝突檢測）
   - "CLAUDE.md"
-  - ".formation/tools/runner.js"
+  - ".formation/tools/dispatch.js"
 requirements:
   - "新增 Lead Agent 開發流程章節"
   - "引用 .rule/pipeline/task-execution.yaml"
@@ -402,9 +380,8 @@ Step 2: 展示 Banner
 └── Ansuz.md             # 斜線指令觸發點
 
 .formation/tools/
-├── headless.js          # Formation 調度核心
+├── dispatch.js          # Formation 調度核心（subagent）
 ├── prompt.js            # Prompt 組裝 + principles 注入
-├── runner.js            # 執行引擎
 ├── post-complete.js     # 任務完成後自動化
 └── logger.js            # 日誌系統
 
@@ -439,11 +416,9 @@ Phase 3: 建立任務
   - node task-api.js create ... （x3 任務）
 
 Phase 4: 陣型判斷 + Dispatch
-  - 判斷：3 個獨立任務 → squad/blitz
+  - 判斷：3 個任務 → 各自 unit/do，序列化 dispatch
   - Dispatch:
-    Bash(bg): node headless.js --formation=squad --skill=blitz --task=TASK_151
-    Bash(bg): node headless.js --formation=squad --skill=blitz --task=TASK_152
-    Bash(bg): node headless.js --formation=squad --skill=blitz --task=TASK_153
+    node dispatch.js --skill=do --task=TASK_151 --dispatch-mode=subagent（完成後再下一個）
 
 Phase 5: 結果處理
   - 驗證：檔案變更 + Git commit + 驗收標準
@@ -531,7 +506,7 @@ Phase 7: 回報
 ```yaml
 無衝突（可並行）:
   TASK_A: scope_paths: ["CLAUDE.md"]
-  TASK_B: scope_paths: [".formation/tools/runner.js"]
+  TASK_B: scope_paths: [".formation/tools/dispatch.js"]
 
 有衝突（必須順序執行）:
   TASK_A: scope_paths: [".rule/pipeline/"]
@@ -601,7 +576,7 @@ Phase 7: 回報
 | 能力定義 | `.specialist/Ansuz/capability.yaml` | 需求分析、任務設計、陣型判斷等能力 |
 | 執行模式 | `.specialist/Ansuz/workflow.yaml` | 事件驅動 7 phases 工作流程 |
 | 共享詞彙 | `.specialist/Ansuz/knowledge.yaml` | Formation、任務系統、Agent 類型 |
-| Formation 系統 | `.formation/tools/` | headless.js, prompt.js, runner.js... |
+| Formation 系統 | `.formation/tools/` | dispatch.js, prompt.js, post-complete.js... |
 | 任務系統 | `.collaboration/core/task-api.js` | 任務 API |
 | CLAUDE.md | `CLAUDE.md` | 專案級指令與工作流程 |
 

package/core/.specialist/Ansuz/capability.yaml

@@ -91,24 +91,17 @@ capabilities:
   # ─── 調度執行 ───
   # §dispatch
   dispatch:
-    description: "使用 Formation 系統調度 agent 執行任務"
-    tool: ".formation/tools/headless.js"
-    method: "Bash tool → node headless.js → 啟動獨立 claude CLI 進程"
+    description: "使用 Formation prompt 組裝 + Agent tool subagent 執行任務（headless CLI 進程已退役）"
+    tool: ".formation/tools/dispatch.js"
+    method: "Bash tool → node dispatch.js --dispatch-mode=subagent → 取回 assembled prompt → Agent tool 開 subagent"
     rules:
       - "✅ 所有調度必須經過 .collaboration 任務系統"
-      - "✅ create → claim → dispatch(headless.js) → complete"
-      - "✅ 用 Bash tool 呼叫 headless.js，run_in_background=true 實現並行"
-      - "⚠️ 同一 project 的 dispatch 必須序列化 — 一個 task 完成後再 dispatch 下一個"
-      - "⚠️ 原因：多個 agent 共用同一 git working directory，並行會 git 衝突 + agent stall"
-      - "⚠️ 有依賴鏈時：按依賴順序逐一 dispatch，等 TaskOutput/poll 確認前一個完成"
+      - "✅ create → dispatch.js(subagent) → Agent tool → complete"
+      - "⚠️ 同一 project 的 dispatch 必須序列化 — 多個 agent 共用同一 git working directory，並行會衝突"
+      - "⚠️ 有依賴鏈時：按依賴順序逐一 dispatch，確認前一個完成"
       - "❌ 不跳過任務系統直接 dispatch"
-      - "❌ 不用 Task tool 開 subagent 繞過 Formation — Formation 有 prompt 組裝、log、principles 注入"
-      - "❌ 禁止同時 dispatch 多個 task 到同一 project（即使它們沒有依賴關係）"
     commands:
-      unit: "node .formation/tools/headless.js --skill=do --task=TASK_XXX"
-      solo: "node .formation/tools/headless.js --formation=solo --skill=strategy --task=TASK_XXX"
-      squad: "node .formation/tools/headless.js --formation=squad --skill=blitz --task=TASK_XXX"
-      legion: "node .formation/tools/headless.js --formation=legion --skill=forge --task=TASK_XXX"
+      unit: "node .formation/tools/dispatch.js --skill=do --task=TASK_XXX --dispatch-mode=subagent"
 
   # ─── 結果追蹤 ───
   # §result_tracking

package/core/.specialist/Ansuz/concepts/formation_quick_ref.yaml

@@ -9,20 +9,13 @@ size_kb: 0.98
 evolution_status: reference
 ---
 formation_quick_ref:
-  principle: "Lightest viable formation: unit > solo > squad > legion"
+  principle: "Only unit/solo skills are dispatchable (squad/legion retired); dispatch = Agent-tool subagent"
   unit:
     when: "Clear goal, single scope, direct execution"
-    command: "node .formation/tools/headless.js --skill=do --task=TASK_XXX"
+    command: "node .formation/tools/dispatch.js --skill=do --task=TASK_XXX --dispatch-mode=subagent"
   solo:
     when: "Multi-perspective analysis needed"
-    command: "node .formation/tools/headless.js --formation=solo --skill=strategy --task=TASK_XXX"
-  squad:
-    when: "Independent parallel subtasks possible"
-    command: "node .formation/tools/headless.js --formation=squad --skill=blitz --task=TASK_XXX"
-  legion:
-    when: "Sequential dependencies or real-time coordination required"
-    command: "node .formation/tools/headless.js --formation=legion --skill=forge --task=TASK_XXX"
+    command: "node .formation/tools/dispatch.js --formation=solo --skill=strategy --task=TASK_XXX --dispatch-mode=subagent"
   dispatch_rules:
-    - "✅ Always background=true for parallel dispatch (Bash run_in_background=true)"
     - "⚠️ Same project: serialize dispatches — wait for each to complete (git conflicts)"
-    - "✅ create → claim → dispatch(headless.js) → complete lifecycle"
+    - "✅ create → dispatch.js(subagent) → Agent tool → complete lifecycle"

package/core/.specialist/Ansuz/elixir.yaml

@@ -54,13 +54,12 @@ mandates:
   - "Project pinning: when boot banner shows a `[pin:...]` line or session was started with --project-path, EVERY MCP call to synapse_*/hippocampus_*/cortex_* that accepts a projectPath param MUST pass projectPath=<pin>; every specialist tool CLI call (task-api, phase-gate, dispatch) MUST pass --project-path <pin>. Missing projectPath leaks memory into the wrong project graph."
   - "Verification policy (PARTIAL/UNVERIFIED/FIX-keeps-original/verified_uncommitted vs committed_unmerged vs merged): .specialist/Ansuz/VERIFY.md, loaded on demand at Phase 9."
   - "Landing mechanics for a verified card (branch check -> Rust/node suites -> optional negative control -> merge -> task-api complete -> mark-landed -> optional backend-restart wait): run .specialist/Ansuz/tools/verify-and-land.js instead of doing the same 10-20 tool calls by hand; it only executes, judgement (what to verify, scope) stays with you."
-  - "WISHING WELL (every incarnation, TASK_1997/TASK_2040): file a wish with kenaz_wish_create — BEFORE working around the problem — whenever the Kenaz app itself blocks or degrades the work: a Kenaz tool/route fails or returns wrong data, a capability you needed is missing, a UX confusion cost you a turn, or a task ends failed/blocked because of the app. wish_type=bug|feature|question, one-line repro + what you expected, task_id when there is one. SCOPE (required on every wish): scope 'kenaz' — the Kenaz app/tools/dispatch itself blocked or degraded the work; scope 'project' — an idea or problem specific to the project being worked on (still sent; the mother may adopt it globally when it benefits Kenaz overall). FEATURE PROPOSALS: when the work reveals a capability Kenaz itself lacks that would help beyond this one task (not only blockers), you may file kenaz_wish_create with wish_type=feature, scope=kenaz. Content, in this order, within ~3000 chars: need (what you were trying to do), why current Kenaz falls short (evidence), proposed shape, who else benefits. Propose only - do not build Kenaz-core changes from a branch instance; the mother decides whether and how. MOTHER-SIDE TRIAGE: on the mother machine, field-report cards tagged needs-triage (blockers, project-scope wishes, and feature proposals alike) are judged at boot — adopt (rewrite as a global card stating the Kenaz-wide benefit, cancel the original with a pointer) or decline (cancel with a one-line reason); a feature proposal may be reshaped rather than built as proposed; never implement a project-specific ask verbatim in core. EXAMPLES — blocker: scope=kenaz, wish_type=bug, 'kenaz_dispatch timed out on a cross-project worktree with no partial log, TASK_2011'. feature proposal: scope=kenaz, wish_type=feature, 'need: retry one failed sub-task without rerunning the whole formation; current Kenaz only retries the full formation; shape: kenaz_dispatch --retry-task <id>; benefits every multi-task formation'. project-specific: scope=project, wish_type=feature, 'this project needs a CSV importer for onboarding — project-specific, flagging in case it generalizes'. At session close, anything unfinished BECAUSE of the app also becomes a wish. This is the channel that feeds the mother from every branch (TASK_1994); a session that hit an app problem and filed no wish has skipped a mandate, not saved time. Boot banner shows the open-wish count (and needs-triage count when >0) so you can see the channel is live."
+  - "WISHING WELL (every incarnation, TASK_1997/TASK_2040): file a wish with kenaz_wish_create — BEFORE working around the problem — whenever the Kenaz app itself blocks or degrades the work: a Kenaz tool/route fails or returns wrong data, a capability you needed is missing, a UX confusion cost you a turn, or a task ends failed/blocked because of the app. wish_type=bug|feature|question, one-line repro + what you expected, task_id when there is one. SCOPE (required on every wish): scope 'kenaz' — the Kenaz app/tools/dispatch itself blocked or degraded the work; scope 'project' — an idea or problem specific to the project being worked on (still sent; the mother may adopt it globally when it benefits Kenaz overall). FEATURE PROPOSALS: when the work reveals a capability Kenaz itself lacks that would help beyond this one task (not only blockers), you may file kenaz_wish_create with wish_type=feature, scope=kenaz. Content, in this order, within ~3000 chars: need (what you were trying to do), why current Kenaz falls short (evidence), proposed shape, who else benefits. Propose only - do not build Kenaz-core changes from a branch instance; the mother decides whether and how. MOTHER-SIDE TRIAGE: on the mother machine, field-report cards tagged needs-triage (blockers, project-scope wishes, and feature proposals alike) are judged at boot — adopt (rewrite as a global card stating the Kenaz-wide benefit, cancel the original with a pointer) or decline (cancel with a one-line reason); a feature proposal may be reshaped rather than built as proposed; never implement a project-specific ask verbatim in core. EXAMPLES — blocker: scope=kenaz, wish_type=bug, 'dispatch.js timed out on a cross-project worktree with no partial log, TASK_2011'. feature proposal: scope=kenaz, wish_type=feature, 'need: retry one failed sub-task without rerunning the whole formation; current Kenaz only retries the full formation; shape: dispatch.js --retry-task <id>; benefits every multi-task formation'. project-specific: scope=project, wish_type=feature, 'this project needs a CSV importer for onboarding — project-specific, flagging in case it generalizes'. At session close, anything unfinished BECAUSE of the app also becomes a wish. This is the channel that feeds the mother from every branch (TASK_1994); a session that hit an app problem and filed no wish has skipped a mandate, not saved time. Boot banner shows the open-wish count (and needs-triage count when >0) so you can see the channel is live."
 dispatch_routing:
   paths:
     subagent: "Agent tool within interactive session — stays on subscription billing, results return directly, no log polling. Use: short/medium tasks (rigor:low/medium, same-project or trivial scope)."
-    formation: "kenaz_dispatch / claude -p — independent process, own log, subscription billing (the June 15 credit-pool split was rescinded, user 2026-10-02). Use: long tasks (rigor:high, multi-hour), cross-project (different cwd needed), or when no interactive session."
-  how: "Run `node .formation/tools/dispatch.js --skill=do --task=TASK_XXX --dispatch-mode=subagent` (include the project pin when present). Read the assembled prompt from top-level promptText and pass it as the Agent tool prompt alongside agentParams. Top-level isolation is orchestration metadata, NOT an Agent tool argument: cross-project worktreePath specifies the target cwd; serialLock specifies required serialization and release. agentParams.isolation is present only for the native same-project worktree route. agentParams.model is ALREADY translated to the Agent tool enum (sonnet|opus|haiku|fable, TASK_1815) — pass it verbatim to a compatible Agent tool, do NOT re-translate or improvise. LIMIT: the Agent tool expresses family names ONLY, so dashboard version/speed picks (claude-opus-5[1m] vs claude-opus-4-8[1m], [1m] modifiers) all degrade to the family name; the payload's modelTranslation {requested, agentToolModel, granularityLoss} shows exactly what was lost — if the exact version matters, use the formation path (kenaz_dispatch → headless.js --dispatch-model accepts full model ids). Unmappable dispatchModel values make dispatch.js exit 1 loudly; never substitute a model silently. For formation path, use kenaz_dispatch MCP as before."
-  mandate: "ALWAYS evaluate both paths before dispatching. Check .kenaz/dashboard-models.json dispatchMode for the user override (set from the Dashboard Model Selection panel > Dispatch Routing, persisted by dashboard_settings.rs since TASK_1814): 'formation' or 'subagent' = hard override, route ALL dispatches through that path; 'auto' = no forced route, apply the heuristic (subagent when within interactive session unless task requires cross-project cwd or is rigor:high, else formation); key missing = dispatch.js falls back to 'formation' (TASK_1813 contract) — treat missing the same as no override and apply the heuristic at the Ansuz level."
+  how: "Run `node .formation/tools/dispatch.js --skill=do --task=TASK_XXX --dispatch-mode=subagent` (include the project pin when present). Read the assembled prompt from top-level promptText and pass it as the Agent tool prompt alongside agentParams. Top-level isolation is orchestration metadata, NOT an Agent tool argument: cross-project worktreePath specifies the target cwd; serialLock specifies required serialization and release. agentParams.isolation is present only for the native same-project worktree route. agentParams.model is ALREADY translated to the Agent tool enum (sonnet|opus|haiku|fable, TASK_1815) — pass it verbatim to a compatible Agent tool, do NOT re-translate or improvise. LIMIT: the Agent tool expresses family names ONLY, so dashboard version/speed picks (claude-opus-5[1m] vs claude-opus-4-8[1m], [1m] modifiers) all degrade to the family name; the payload's modelTranslation {requested, agentToolModel, granularityLoss} shows exactly what was lost. Unmappable dispatchModel values make dispatch.js exit 1 loudly; never substitute a model silently."
+  mandate: "Subagent is the only dispatch path (Formation headless/kenaz_dispatch retired, TASK_2359/2401/2402). dispatchMode in .kenaz/dashboard-models.json no longer selects a route."
 exo_cortex:
   opening_move: synapse_recall + kenaz_lsp_callers
   anti_pattern: "Bash grep/rg/find for source archaeology — prefer Grep/Glob (and kenaz_lsp_symbols for symbols); the hook nudge is downstream of you knowing the tool exists"

package/core/.specialist/Ansuz/identity_contract.yaml

@@ -339,7 +339,7 @@ cross_model:
     - "ME-001 governance (immutable rules cannot be deleted) must hold"
     - "AskUserQuestion tool must be available and used for all user-response questions"
     - "Phase sequence 0-11 must be respected; phase-gate.js must be callable"
-    - "Formation dispatch must work (headless.js must be callable)"
+    - "Subagent dispatch must work (.formation/tools/dispatch.js --dispatch-mode=subagent must be callable)"
     - "Task-api.js must be callable for task lifecycle management"
 
   acceptable_substrate_drift:

package/core/.specialist/Ansuz/knowledge.yaml

@@ -34,9 +34,8 @@ formation:
     - "Squad ≠ 開會。Squad = 多個獨立 subagent 並行，零溝通"
     - "Legion ≠ 大號 Squad。Legion = 持久化團隊，成員間即時通訊"
   key_files:
-    headless: ".formation/tools/headless.js"
+    dispatch: ".formation/tools/dispatch.js"
     prompt: ".formation/tools/prompt.js"
-    runner: ".formation/tools/runner.js"
     logs: ".formation/logs/{formation}/"
     post_complete: ".formation/tools/post-complete.js"
   research_notes:
@@ -49,12 +48,10 @@ formation:
         - "Better mapping: represent agent-role reliability and coordination cost as factorised hidden states, then evaluate a whole formation against task context."
         - "Keep a collective dispatch objective separate from per-agent or per-symbol EFE because ensemble-level EFE is not guaranteed to be aggregate-optimal."
   dispatch_mechanism:
-    how: "Bash tool → node headless.js → runner.js → spawn claude CLI 獨立進程"
-    why: "headless.js 統一處理 prompt 組裝（prompt.js）、principles 注入、log 管理"
-    anti_pattern: "❌ 禁止用 Task tool 直接開 subagent — 繞過 Formation 會失去 prompt 組裝和 log"
-    parallel: "多個 Bash(run_in_background=true) 同時啟動 → 真正的進程級並行"
-    max_parallel: 5  # 同時最多 5 個 headless 進程，超過排隊等空位
-    monitoring: "讀 .formation/logs/{formation}/ 下的 log 確認結果"
+    how: "Bash tool → node dispatch.js --dispatch-mode=subagent → Agent tool subagent"
+    why: "dispatch.js 統一處理 prompt 組裝（prompt.js）、principles 注入"
+    anti_pattern: "❌ 不手寫 subagent prompt — 用 dispatch.js 組裝"
+    monitoring: "Agent tool 結果直接返回"
 
 # ═══════════════════════════════════════
 #  任務系統
@@ -89,10 +86,10 @@ task_system:
     project_yaml: ".kenaz/project.yaml"
     rule: |
       子專案的任務存在 .kenaz/tasks/，不是 .collaboration/tasks/。
-      所有 task-api.js、headless.js、post-complete.js 呼叫都必須加 --project-path。
+      所有 task-api.js、dispatch.js、post-complete.js 呼叫都必須加 --project-path。
     cli_pattern:
       task_api: "node {CORE}/.collaboration/core/task-api.js --project-path {PROJECT_PATH} <command>"
-      headless: "node {CORE}/.formation/tools/headless.js --project-path {PROJECT_PATH} --skill=do --task=TASK_XXX"
+      dispatch: "node {CORE}/.formation/tools/dispatch.js --project-path {PROJECT_PATH} --skill=do --task=TASK_XXX --dispatch-mode=subagent"
       post_complete: "node {CORE}/.formation/tools/post-complete.js --task=TASK_XXX --project-path={PROJECT_PATH}"
 
 # ═══════════════════════════════════════

package/core/.specialist/Ansuz/rule.yaml

@@ -35,7 +35,7 @@ allow:
   - "讀取專案內所有原始碼"
   - "讀寫 specialist/Ansuz/ 下所有檔案"
   - "使用 .collaboration/core/task-api.js 管理任務"
-  - "使用 .formation/tools/headless.js 調度執行"
+  - "使用 .formation/tools/dispatch.js --dispatch-mode=subagent 調度執行"
   - "使用 .formation/tools/post-complete.js 完成後自動化"
   - "執行 git 操作（建立分支、commit、merge 到用戶分支）"
 
@@ -51,7 +51,7 @@ identity:
   symbol: "ᚨ — 神諭符文：理解意圖，傳遞給執行層"
   rules:
     - "❌ 不 invoke 其他 Skill — 不切換身份"
-    - "✅ 需要執行時 → 用 Formation 系統 dispatch（Task tool + headless.js）"
+    - "✅ 需要執行時 → 用 Agent tool subagent dispatch（dispatch.js --dispatch-mode=subagent）"
     - "✅ Ansuz 本體負責：需求理解、任務設計、陣型判斷、調度、追蹤、回報"
     - "❌ 不親自寫程式碼 — 只做決策和調度"
     - "✅ Task-First — 預設先建立任務卡再 dispatch，除非是極簡單的單檔修改（< 20 行）"