kenaz 0.3.2 → 0.3.5

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

@@ -1,38 +1,39 @@
-## 專案路徑解析（Project Path Resolution · 最先執行）
-
-在執行任何步驟前，先從 `/Ansuz` 的 ARGUMENTS 解析 PROJECT_PATH：
-- 格式 `[專案: X]` → PROJECT_PATH = X
-- 格式 `--project-path X` → PROJECT_PATH = X
-- 無此格式（cwd = core，一般情況）→ PROJECT_PATH 為空，全程不附加任何 flag，行為完全不變
-
-PROJECT_PATH 有值時，必須下傳至：下方快速 Boot 的 ansuz-boot-fast.js 呼叫（附加 `--project-path "<PROJECT_PATH>"`）。
-
----
+## 專案路徑
+ARGUMENTS 含 `[專案: X]` 或 `--project-path X` → PROJECT_PATH = X，下方 boot 腳本與 task-api / dispatch 呼叫都附加 `--project-path "<PROJECT_PATH>"`。沒有就留空，什麼都不加。
 
 # Ansuz boot
 
-你是 **Ansuz**，Kenaz 的 PM：理解需求、設計任務、選擇派工方式、派工、驗證、回報。先查現況、先確認 scope，再動手。
-
-日常規則在 CLAUDE.md 與記憶索引裡。**以下時機讀 `.specialist/Ansuz/RULES.md`**：用戶授權自主時、派工前、合併／landing 前、寫 handoff 時、boot banner 出現 `[pin:...]` 時。（2026-10-07 盲測：常駐的 17.5 KB elixir 開機 prompt 不改變這些行為，已退役，見 dev/research/ansuz-boot-ablation/RESULTS.md。）
-
----
-
-## 快速 Boot（唯一路徑 · 無 gate；舊 `--full` 流程已封存於 dev/archive/ansuz/BOOT_FULL.md）
-
-main thread 直接做輕量 Phase 0：**不 spawn sub-agent、不跑 phase-gate、不寫 mirror、不 emit ritual markers**。只印 banner、歸檔上一世 handoff。
-
-> 若解析出 PROJECT_PATH，下方腳本呼叫附加 `--project-path "<PROJECT_PATH>"`。
-
-0. **（TASK_2222 · 必做）取得真實 session_id**：本輪 Turn Context 若含 `[session] session_id=<id>`，記住 `<id>`（本 session 專屬；單槽檔 `last_prompt_session.json` 會被並行 session 覆寫，不可用）。之後：
-   - 第 2 步附加 `--conversation-id=<id>`；
-   - 每次呼叫 `ansuz_handoff_snapshot`（或其他接受 `session_id` 的工具）一律帶 `session_id=<id>`。
-   - 找不到這行時省略兩者，腳本有 fallback。
-
-
-2. **跑 boot 腳本**（一個 Bash 呼叫）：
-   `node .specialist/tools/ansuz-boot-fast.js`（子專案附加 `--project-path "<PROJECT_PATH>"`；有 `<id>` 時附加 `--conversation-id="<id>"`）
-   印出 banner（peer / 任務 / Wishes / ANOMALY / handoff）並歸檔上一世 handoff。
-
-3. **Relay banner**：把腳本 stdout 轉述給用戶（Bash 輸出在 UI 是摺疊的）。顯示 pin 行時，後續所有 synapse_*/hippocampus_*/cortex_* MCP 呼叫與 specialist CLI 呼叫皆需帶 `projectPath`/`--project-path <pin>`。
-
-4. **Phase 0 完成** → 直接進 Phase 1+。banner 的 `📋 Open cards` 已含每張卡的 id / 優先度 / 標題 / STATUS，**第一個回應就依此提議程**，不要再跑 task-api list；只在要動某張卡時才 `task-api get`。
+你是 **Ansuz**，Kenaz 的 orchestrator：理解需求，依情境決定自己動手或拆任務派給 subagent，合併前在真實路徑上驗證，然後回報。先查現況、確認 scope，再動手。
+
+## Boot（一次 Bash，無其他儀式）
+1. Turn Context 若有 `[session] session_id=<id>`，記住 `<id>`。
+2. 執行 `node .specialist/tools/ansuz-boot-fast.js`（有 `<id>` 加 `--conversation-id="<id>"`；有 PROJECT_PATH 加 `--project-path`）。
+3. 把 banner 轉述給用戶（Bash 輸出在 UI 會摺疊），並依 `📋 Open cards` 直接提出議程。
+
+## 每件工作的做法
+- **自己做**：小而明確的修正（約 30 行內、單一檔案或少數檔案）→ 直接改，跑最近的測試，提交。
+- **開卡派工**：中型、可平行、或高風險路徑的工作：
+  1. 用 `kenaz_task_create` 開卡（`projectPath` = 目前專案；寫清楚 requirements、acceptance criteria、scope paths）。查卡、改狀態用 `kenaz_task_list` / `kenaz_task_get` / `kenaz_task_update`。
+  2. 產生派工內容：`node .formation/tools/dispatch.js --skill=do --task=TASK_XXX --dispatch-mode=subagent`（加 `--project-path`；Codex 加 `--harness=codex`）。把輸出 JSON 的 `promptText` 交給 subagent，`agentParams` 照用（模型不要自己換）。
+  3. subagent 在 worktree 裡改完並 commit；你驗證後合併。
+- 開卡前先確認 scope 與驗收條件對準真正的問題，不要照著錯的假設派工。
+
+## 驗證（合併前一定做，強度跟風險相稱）
+- 走**真實路徑**：實際執行會被使用者用到的那條路（真的安裝、真的啟動、真的收發訊息），不只看單元測試。
+- 有**對照組**：證明測試在舊程式上會失敗，或修改前後結果不同。
+- subagent 回報「未驗證」的項目，由你補驗或明講仍未驗證。
+- 合併：`git merge` 後跑相關測試（或 `node .specialist/Ansuz/tools/verify-and-land.js`），用這個專案自己的測試指令。
+- 只在 Kenaz 核心 repo 本身：Rust 測試走 `npm run test:rust` / `dev/scripts/rust-verify-worktree.js`。
+
+## 回報
+用用戶的語言。說清楚：做了什麼、怎麼驗證的、還有什麼沒驗證或需要用戶決定。不說「應該可以」。
+
+## Kenaz 本身出問題時：先回報再繞過（wish / field report）
+Kenaz 的工具、hook、安裝、peer 訊息、派工擋住或拖慢工作時（指令失敗、回傳錯的資料、少了能力、行為不如預期），**繞過之前**先呼叫 `kenaz_wish_create`。scope=kenaz 的 wish 會自動送到 Kenaz 團隊成為 field report。
+- `projectPath`：目前專案路徑；`scope`：`kenaz`（Kenaz 本身的問題）或 `project`（只跟這個專案有關）
+- `wish_type`：`bug`（壞了）／`feature`（缺能力，內容寫：需求、現在哪裡不夠、建議做法、還有誰受益）／`question`
+- `content`：一行重現步驟 + 預期 vs 實際 + 版本（`npx kenaz doctor` 那幾行）；附上 session id。不要貼金鑰或 token。
+- 一個問題只報一次；報完照常用替代做法把工作完成，並在回報裡告訴用戶已送出 wish。
+- 用戶直接說「回報這個問題」時也用同一個工具（`source`=`user`）。
+
+需要更多規則時（用戶授權自主、派工前、合併前）讀 `.specialist/Ansuz/RULES.md`。

package/core/.claude/hooks/__tests__/task-2395-project-registration.test.js

@@ -0,0 +1,84 @@
+'use strict';
+// TASK_2395: kenaz init and the first turn-context call per session ask the server to register the
+// project (POST /api/projects/register). The stub server stands in for the Rust route: it writes a
+// temp-HOME projects.json idempotently, so the real ~/.kenaz is never touched.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const http = require('node:http');
+const { spawn } = require('node:child_process');
+
+const REPO = path.resolve(__dirname, '..', '..', '..');
+const KENAZ_MODE = path.join(REPO, 'plugins', 'kenaz', 'scripts', 'kenaz-mode.js');
+const TURN_CONTEXT = path.join(REPO, '.claude', 'hooks', 'turn-context.js');
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'k2395-'));
+const home = path.join(tmp, 'home');
+const proj = path.join(tmp, 'Ashfall-game');
+fs.mkdirSync(path.join(home, '.kenaz'), { recursive: true });
+fs.mkdirSync(proj, { recursive: true });
+const registryFile = path.join(home, '.kenaz', 'projects.json');
+let posts = 0;
+let server;
+let port;
+
+test.before(async () => {
+  server = http.createServer((req, res) => {
+    let body = '';
+    req.on('data', (c) => { body += c; });
+    req.on('end', () => {
+      if (req.method === 'POST' && req.url === '/api/projects/register') {
+        posts += 1;
+        const p = JSON.parse(body).projectPath;
+        let doc = { projects: [] };
+        try { doc = JSON.parse(fs.readFileSync(registryFile, 'utf8')); } catch { /* new */ }
+        const hit = doc.projects.find((x) => x.path === p);
+        if (!hit) doc.projects.push({ id: 'proj_' + doc.projects.length, name: path.basename(p), path: p });
+        fs.writeFileSync(registryFile, JSON.stringify(doc));
+        res.setHeader('Content-Type', 'application/json');
+        return res.end(JSON.stringify({ success: true, created: !hit }));
+      }
+      res.statusCode = 404;
+      res.end('{}');
+    });
+  });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  port = server.address().port;
+});
+test.after(() => { server.close(); fs.rmSync(tmp, { recursive: true, force: true }); });
+
+function run(script, args, input) {
+  return new Promise((resolve) => {
+    const env = { ...process.env, HOME: home, USERPROFILE: home, CLAUDE_PROJECT_DIR: proj, KENAZ_HTTP_PORT: String(port) };
+    const child = spawn(process.execPath, [script, ...args], { cwd: proj, env });
+    let out = '';
+    child.stdout.on('data', (c) => { out += c; });
+    child.stderr.on('data', (c) => { out += c; });
+    child.on('close', () => resolve(out));
+    child.stdin.end(input || '');
+  });
+}
+const registered = () => JSON.parse(fs.readFileSync(registryFile, 'utf8')).projects.filter((p) => p.path === proj);
+
+test('kenaz init registers the project, and a second init does not duplicate it', async () => {
+  await run(KENAZ_MODE, ['init']);
+  assert.equal(registered().length, 1);
+  assert.ok(fs.existsSync(path.join(proj, '.kenaz', 'project.yaml')));
+  await run(KENAZ_MODE, ['init']);
+  assert.equal(registered().length, 1);
+  assert.ok(posts >= 2, 'init asks the server every time (the server is the idempotent part)');
+});
+
+test('turn-context registers once per session, again for a new session', async () => {
+  const before = posts;
+  const payload = (sid) => JSON.stringify({ session_id: sid });
+  await run(TURN_CONTEXT, [], payload('sess-1'));
+  assert.equal(posts, before + 1);
+  await run(TURN_CONTEXT, [], payload('sess-1'));
+  assert.equal(posts, before + 1, 'same session: no second call');
+  await run(TURN_CONTEXT, [], payload('sess-2'));
+  assert.equal(posts, before + 2, 'new session asks again');
+  assert.equal(registered().length, 1);
+});

package/core/.claude/hooks/_ansuz-conversation.js

@@ -22,6 +22,7 @@ const path = require('path');
 
 const MARKERS = [
   '<command-name>/Ansuz</command-name>', // user typed /Ansuz
+  '<command-name>/kenaz:Ansuz</command-name>', // typed through the kenaz plugin (npm install)
   '# Ansuz boot', // .claude/commands/Ansuz.md body since the elixir boot prompt was retired (2026-10-07)
   'session.js prompt Ansuz --mode=assembled', // older Ansuz.md body (transcripts before 2026-10-07)
   '# Ansuz -- Specialist Prompt', // assembled prompt handed over as a user message (headless)

package/core/.claude/hooks/_ansuz-conversation.test.js

@@ -88,3 +88,9 @@ test('the current Ansuz.md body (no boot prompt, 2026-10-07) is still recognised
   const mention = JSON.stringify({ type: 'user', message: { role: 'user', content: 'what is in .specialist/Ansuz/RULES.md?' } });
   assert.equal(lineIsAnsuzEntry(mention), false);
 });
+
+test('plugin-namespaced /kenaz:Ansuz is recognised as an Ansuz session', () => {
+  const { lineIsAnsuzEntry } = require('./_ansuz-conversation');
+  const line = JSON.stringify({ type: 'user', message: { role: 'user', content: '<command-name>/kenaz:Ansuz</command-name>' } });
+  assert.strictEqual(lineIsAnsuzEntry(line), true);
+});

package/core/.claude/hooks/_run-user-prompt.js

@@ -33,14 +33,10 @@ const path = require('path');
 const { Readable } = require('stream');
 
 const DEFAULT_HOOKS = [
-  'handoff-staleness.js',
-  'fatigue-check.js',
   'daemon-outbox-hook.js',
   // TASK_2218: ansuz-session-pin.js is called from turn-context.js (every install layout runs that hook).
   'turn-context.js',
   'task-bridge.js',
-  'lease-touch.js',
-  'stream-delta.js',
 ];
 
 const HARD_CAP_MS = 10000;

package/core/.claude/hooks/_run-user-prompt.test.js

@@ -69,12 +69,11 @@ test('runner replays stdin, traps exits, concatenates stdout, exits 0', () => {
   assert.ok(elapsed < 5000, 'runner drained promptly, took ' + elapsed + ' ms');
 });
 
-test('default list is the seven UserPromptSubmit hooks in settings order', () => {
+test('default list is the three UserPromptSubmit hooks in settings order', () => {
   // TASK_2218: the pin writer is invoked from turn-context.js, not listed here.
   const { DEFAULT_HOOKS } = require(RUNNER);
   assert.deepStrictEqual(DEFAULT_HOOKS, [
-    'handoff-staleness.js', 'fatigue-check.js', 'daemon-outbox-hook.js', 'turn-context.js',
-    'task-bridge.js', 'lease-touch.js', 'stream-delta.js',
+    'daemon-outbox-hook.js', 'turn-context.js', 'task-bridge.js',
   ]);
   for (const f of DEFAULT_HOOKS) assert.ok(fs.existsSync(path.join(__dirname, f)), f + ' exists');
 });

package/core/.claude/hooks/handoff-staleness.js

@@ -20,7 +20,7 @@
  * (HANDOFF_STALE_AFTER_MS) — see TASK_1837/TASK_1838.
  *
  * Dispatch detection (TASK_1830 measurement — two routes, two trace families):
- *   1. kenaz_dispatch / Formation route → .formation/.active-dispatches.json
+ *   1. Formation dispatch route → .formation/.active-dispatches.json
  *      (written by Rust, kenaz.rs). Kept for that route.
  *   2. sub-agent route (Agent tool — the DEFAULT since 2026-06-09) never touches
  *      that file. Its in-project trace is the dispatch brief
@@ -104,7 +104,7 @@ try {
   const { toolUseMentionsAny, taskIdNeedles } = require('./_ansuz-conversation');
   const candidateNeedles = [];
   try {
-    // Route 1: kenaz_dispatch / Formation registry (Rust writer; entries carry taskId).
+    // Route 1: Formation registry (entries carry taskId).
     if (fs.existsSync(dispatchFile)) {
       const dispatches = JSON.parse(fs.readFileSync(dispatchFile, 'utf8'));
       if (Array.isArray(dispatches)) {

package/core/.claude/hooks/turn-context.js

@@ -93,15 +93,61 @@ try {
   state = { last_ts: 0, last_event_count: 0 };
 }
 
+// ── TASK_2395: register this project in ~/.kenaz/projects.json (first call per session) ──
+// Peer routing by to_project only knows registered projects; under kenaz-server nothing else
+// registers them. The registry write itself is the server's (POST /api/projects/register, one
+// Rust writer, idempotent); this only asks, once per session, and remembers success.
+// Per machine, not per project: a file under <project>/.kenaz would show up in repos that do not
+// ignore .kenaz/specialist (e.g. a fresh `kenaz init` project).
+const REGISTERED_PATH = path.join(require('os').homedir(), '.kenaz', 'registered_sessions.json');
+const REGISTERED_KEY = (sid) => projectDir.split(path.sep).join('/').toLowerCase() + '|' + sid;
+function registerProjectOnce() {
+  return new Promise((resolve) => {
+    try {
+      const sid = peerHookPayload.session_id ? String(peerHookPayload.session_id) : '';
+      if (!sid) return resolve();
+      let seen = [];
+      try { seen = JSON.parse(fs.readFileSync(REGISTERED_PATH, 'utf8')).sessions || []; } catch { /* first run */ }
+      if (seen.includes(REGISTERED_KEY(sid))) return resolve();
+      const body = JSON.stringify({ projectPath: projectDir });
+      const req = http.request({
+        host: '127.0.0.1',
+        port: Number(process.env.KENAZ_HTTP_PORT || process.env.KENAZ_BACKEND_PORT || 18080),
+        path: '/api/projects/register',
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+        timeout: 800,
+      }, (res) => {
+        let raw = '';
+        res.on('data', (c) => { raw += c; });
+        res.on('end', () => {
+          try {
+            if (JSON.parse(raw).success === true) {
+              fs.mkdirSync(path.dirname(REGISTERED_PATH), { recursive: true });
+              fs.writeFileSync(REGISTERED_PATH, JSON.stringify({ sessions: seen.concat(REGISTERED_KEY(sid)).slice(-200) }));
+            }
+          } catch { /* retried next turn */ }
+          resolve();
+        });
+      });
+      req.on('timeout', () => req.destroy());
+      req.on('error', () => resolve());
+      req.end(body);
+    } catch { resolve(); }
+  });
+}
+const registeredP = registerProjectOnce();
+
 // ── Cooldown check ───────────────────────────────────────────────────────────
 const now = Date.now();
-if (now - state.last_ts < TURN_CONTEXT_COOLDOWN_MS) {
+const inCooldown = now - state.last_ts < TURN_CONTEXT_COOLDOWN_MS;
+if (inCooldown) {
   // The cooldown throttles the peer pull only; the session line must still reach
   // the model on every turn (a second session in the same cwd lands here).
   if (peerHookPayload.session_id) {
     process.stdout.write('\n' + fenceSignal('context', '[Turn Context]\n[session] session_id=' + String(peerHookPayload.session_id)) + '\n');
   }
-  process.exit(0);
+  registeredP.then(() => process.exit(0));
 }
 
 // ── Helper: HTTP GET returning a promise ─────────────────────────────────────
@@ -142,6 +188,8 @@ const sessionLine = peerHookPayload.session_id
 
 // ── Main async flow ──────────────────────────────────────────────────────────
 (async () => {
+  if (inCooldown) return; // the cooldown branch above exits after the registration settles
+  await registeredP;
   // 1. Synapse turn-context: retired with Kuzu (0.2.266) -- the endpoint only returns
   // empty text. Not fetched any more: a slow or unreachable backend used to exit
   // here and skip the peer pull below.

package/core/.claude/settings.json

@@ -33,16 +33,6 @@
         ]
       }
     ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node -e \"const d=process.env.CLAUDE_PROJECT_DIR||process.cwd();process.chdir(d);require(d+'/.claude/hooks/lease-release.js')\""
-          }
-        ]
-      }
-    ],
     "UserPromptSubmit": [
       {
         "hooks": [
@@ -82,33 +72,6 @@
           }
         ],
         "matcher": "TaskCreate|TaskUpdate"
-      },
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node -e \"const d=process.env.CLAUDE_PROJECT_DIR;process.chdir(d);require(d+'/.claude/hooks/handoff-snapshot-on-commit.js')\""
-          }
-        ],
-        "matcher": "Bash"
-      },
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node -e \"const d=process.env.CLAUDE_PROJECT_DIR;process.chdir(d);require(d+'/.claude/hooks/handoff-snapshot-on-question.js')\""
-          }
-        ],
-        "matcher": "AskUserQuestion"
-      },
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node -e \"const d=process.env.CLAUDE_PROJECT_DIR;process.chdir(d);require(d+'/.claude/hooks/handoff-snapshot-on-decision.js')\""
-          }
-        ],
-        "matcher": "mcp__kenaz-dashboard__synapse_inscribe"
       }
     ]
   },

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

@@ -1589,17 +1589,12 @@ class TaskAPI {
       console.warn('WARNING: overriding acceptance_criteria required for code-touching task via --force');
     }
 
-    // 品質閘門：檢查任務內容是否足夠豐富
+    // 品質提示（2026-10-10 起只警告、不阻擋；ANSUZ_SLIM_PLAN）：數量門檻擋卡的成本高於價值。
+    // 仍強制的只有上方「改到程式碼的卡至少一條 acceptance_criteria」。
     if (!options.force) {
       const quality = this.validateTaskQuality(taskData);
       if (!quality.valid) {
-        const msg = [
-          '❌ 任務品質不足，無法建立：',
-          ...quality.warnings.map(w => `  - ${w}`),
-          '',
-          '提示：補齊欄位後重試，或使用 --force 強制建立'
-        ].join('\n');
-        throw new Error(msg);
+        console.warn(['⚠️ 任務內容偏少（仍會建立）：', ...quality.warnings.map(w => `  - ${w}`)].join('\n'));
       }
     }
 
@@ -2116,8 +2111,7 @@ class TaskAPI {
     // TASK_2264: decide up front whether post-complete (below) will measure 'after' in-process.
     // TASK_2288 single-winner rule: whenever a post-complete run is expected for this completion,
     // post-complete's own measurement is the ONE 'after' capture (it runs after merge and feeds the
-    // verdict), so moveTask must not also spawn one. Expected = in-process (below) OR the caller
-    // (headless.js / scheduler, signalled by FORMATION_HEADLESS / FORMATION_SCHEDULER) runs it itself.
+    // verdict), so moveTask must not also spawn one. Expected = in-process (below).
     // moveTask's detached capture stays the sole one only when nobody measures: --skip-post-complete.
     const postCompleteRuns = !options.skipPostComplete;
     const result = await this.moveTask(taskId, 'done', updatedTask, { skipHealthAfter: postCompleteRuns });
@@ -2140,8 +2134,6 @@ class TaskAPI {
     }
 
     // 自動執行 post-complete（除非明確跳過）
-    // - FORMATION_SCHEDULER: 由 scheduler 統一管理，避免重複執行
-    // - FORMATION_HEADLESS: 由 headless.js onDone 統一執行，避免並行 agent git 衝突
     if (postCompleteRuns) {
       try {
         const { postComplete } = require('../../.formation/tools/post-complete.js');

package/core/.formation/README.md

@@ -1,16 +1,10 @@
 # Formation System
 
-Agent 部署陣型系統。根據任務規模選擇適當的陣型。
+Subagent 調度。唯一的 live 路徑：`dispatch.js --dispatch-mode=subagent` 印出 JSON（`promptText` + `agentParams`），由 Ansuz 交給 Agent tool（或 `--harness=codex` 的 Codex `spawn_agent`）執行。
 
-## 陣型一覽
+Headless（`claude -p`、`kenaz_dispatch`）、Squad、Legion、Legacy scheduler 已退役；`squad/`、`legion/` 的 YAML 只是歷史定義，`dispatch.js` 遇到會直接報錯結束。
 
-```
-Unit  →  Solo  →  Squad  →  Legion
- 1×1      1×N      N×1      Native Team
-最輕量    最靈活    真並行    最重火力
-```
-
----
+## 陣型
 
 ### Unit
 
@@ -18,138 +12,37 @@ Unit  →  Solo  →  Squad  →  Legion
 
 派出一個 subagent 執行單一任務，完成後回報結果。不切換角色、不協作，純粹的「去做這件事」。
 
-- 機制：`Task` 工具，單次調用
-- 成本：最低
 - 適用：明確的單一任務、Bug 修復、檔案修改、腳本執行
-
----
+- 可用 skill：`do`、`think`、`plan`
 
 ### Solo
 
 **1 agent, N perspectives** — 單人多視角自主切換。
 
-派出一個 subagent，同時裝備多個專業視角。Agent 根據分析過程中的需要，自主決定何時切換到哪個視角。不是輪流發言，是一個人用不同鏡頭看同一件事。
+一個 subagent，同時裝備多個專業視角，由 agent 自主決定何時切換。
 
-- 機制：`dispatch.js --formation=solo`，prompt 中載入所有 `perspectives`
-- 成本：低（單次 subagent 調用）
+- 機制：`dispatch.js --formation=solo`
 - 適用：策略分析、程式碼審查、方案評估、設計決策
 - 可用 skill：`strategy`（策略分析）、`diagnosis`（問題診斷）
 
-```
-範例：Solo + Strategy
-→ [技術專家] 分析架構影響
-→ 發現成本問題 → [產品策略師] 評估 ROI
-→ 發現安全疑慮 → [風險分析師] 識別風險
-→ 綜合判斷，產出結論
-（視角切換由 agent 自主決定，非固定順序）
-```
-
----
-
-### Squad
-
-**N agents, 1 task** — 多 agent 並行協作。
-
-同時派出多個 subagent，各自負責任務的不同部分，並行執行後整合成果。成員之間不能互相通訊（那是 Legion 的事），各自獨立完成後由 lead 整合。
-
-- 機制：`dispatch.js --formation=squad`，並行啟動多個 Claude 進程
-- 成本：中等（隨 agent 數量線性增長）
-- 適用：並行子任務開發、跨模組批量修改、多區域同步掃蕩
-- 可用 skill：`blitz`（通用並行拆分）、`sweep`（同規則多範圍掃蕩）
-
-**核心約束**：
-- 成員之間 **不通訊**，只靠 `shared_context`（啟動前定義的共享約定）協調
-- 每個成員的 `scope_paths` 不得重疊（避免檔案衝突）
-- 如果子任務之間有依賴關係，不適合用 Squad
-
-```
-範例 1：Squad + blitz（並行拆分）
-├── [part_1] → 實作模組 A 的功能
-├── [part_2] → 實作模組 B 的功能
-└── [part_3] → 實作模組 C 的功能
-→ lead 整合驗證，統一提交
-
-範例 2：Squad + sweep（同規則掃蕩）
-├── [zone_1] → 重構 cmd_modules/ 下的模組
-├── [zone_2] → 重構 components/ 下的元件
-└── [zone_3] → 重構 lib/ 下的工具函數
-→ lead 驗證一致性，統一提交
-```
-
----
-
-### Legion
-
-**Native Team** — 即時溝通的完整團隊。
-
-使用 Claude Code 原生的 TeamCreate 機制，建立持久化團隊。成員之間可互相通訊、即時協調。Legion 的核心價值不是「更多人」，而是「即時溝通」— 只在成員的工作互相影響、需要即時協調時使用。
-
-- 機制：`TeamCreate` + `SendMessage`
-- 成本：最高（持久化 context + 通訊開銷）
-- 適用：有順序依賴、回饋循環、或高度耦合的複雜任務
-- 可用 skill：`forge`（順序流水線）、`hive`（網狀即時協調）
-
-**核心價值**（Squad 做不到的事）：
-- 即時通知「我改了 X，你要更新」
-- 回饋循環（review → fix → re-review）
-- 順序依賴（A 做完 B 才開始）
-- 動態調整（做到一半改方向）
-
-```
-範例 1：Legion + forge（鍛造）
-Designer ──→ Implementer(s) ──→ Reviewer
-    ↑ 回饋修正 ←──────────────────↓
-→ 設計 → 打造 → 淬煉，有序且有品質把關
-
-範例 2：Legion + hive（蜂巢）
-Worker A ←→ Worker B
-   ↕           ↕
-Worker C ←→ Worker D
-→ 所有人即時互聯，任何變更即時同步
-```
-
----
-
-## 選擇指南
-
-| 問自己 | 答案 | 陣型 |
-|--------|------|------|
-| 任務簡單、目標明確？ | Yes | **Unit** |
-| 需要多角度分析？ | Yes | **Solo** |
-| 需要同時做多件事？ | Yes | **Squad** |
-| 有順序依賴或回饋循環？ | Yes | **Legion** (forge) |
-| 工作高度耦合、需即時協調？ | Yes | **Legion** (hive) |
-
 ---
 
 ## 啟動方式
 
-### Headless Mode（推薦）
-
-由 Formation Lead 配好任務後直接呼叫，subagent 不問問題：
-
 ```bash
-# Unit: 單一任務
-node .formation/tools/headless.js --skill=do --task="修正按鈕顏色"
+# Unit
+node .formation/tools/dispatch.js --skill=do --task=TASK_172 --dispatch-mode=subagent
 
-# Solo: 多視角分析
-node .formation/tools/headless.js --formation=solo --skill=strategy --task="評估快取方案"
+# Solo
+node .formation/tools/dispatch.js --formation=solo --skill=strategy --task=TASK_172 --dispatch-mode=subagent
 
-# Squad: 並行執行
-node .formation/tools/headless.js --formation=squad --skill=blitz --task=TASK_201
-
-# Legion: Agent Teams 即時協作
-node .formation/tools/headless.js --formation=legion --skill=forge --task=TASK_202
-
-# Dry run（只看 prompt，不啟動）
-node .formation/tools/headless.js --formation=legion --skill=forge --task=TASK_202 --dry-run
+# Codex harness / 子專案 / 只看 payload 不產生副作用
+node .formation/tools/dispatch.js --skill=do --task=TASK_172 --dispatch-mode=subagent --harness=codex
+node .formation/tools/dispatch.js --skill=do --task=TASK_172 --dispatch-mode=subagent --project-path <path>
+node .formation/tools/dispatch.js --skill=do --task=TASK_172 --dispatch-mode=subagent --dry-run
 ```
 
-### Dispatch Mode（互動式）
-
-```bash
-node .formation/tools/dispatch.js --skill=do --task=TASK_172
-```
+缺 `--dispatch-mode=subagent`、或指定 squad/legion skill，都會以非零 exit code 結束並印出原因。
 
 ---
 
@@ -158,31 +51,13 @@ node .formation/tools/dispatch.js --skill=do --task=TASK_172
 ```
 .formation/
 ├── README.md              # 本文件
-├── lead.yaml              # Formation Lead（陣型選擇器）
+├── lead.yaml              # Formation Lead
 ├── tools/
-│   ├── headless.js       # ⭐ 無頭啟動器（所有陣型）
-│   ├── dispatch.js        # CLI 入口（互動式）
+│   ├── dispatch.js        # CLI 入口（--dispatch-mode=subagent）
 │   ├── loader.js          # YAML/Task 載入
-│   ├── prompt.js          # Prompt 組裝（unit/solo/squad/legion）
-│   ├── runner.js          # Claude 進程管理（single + parallel）
-│   ├── logger.js          # Log 格式化
+│   ├── prompt.js          # Subagent prompt 組裝 + 傳輸前綴
+│   ├── post-complete.js   # 完成後 merge / 驗證
 │   └── utils.js           # 工具函數
-├── logs/                  # ⭐ 執行日誌（按陣型分目錄）
-│   ├── unit/
-│   ├── solo/
-│   ├── squad/
-│   └── legion/
-├── unit/                  # Unit 陣型定義
-│   ├── do.yaml            # 執行者
-│   ├── think.yaml         # 分析者
-│   └── plan.yaml          # 規劃者
-├── solo/                  # Solo 陣型定義（含視角集）
-│   ├── strategy.yaml      # 策略分析（6 視角）
-│   └── diagnosis.yaml     # 問題診斷（4 視角）
-├── squad/                 # Squad 陣型定義（含協作模板）
-│   ├── blitz.yaml         # 通用並行拆分
-│   └── sweep.yaml         # 同規則多範圍掃蕩
-└── legion/                # Legion 陣型定義（含溝通模式）
-    ├── forge.yaml         # 順序流水線（設計→打造→淬煉）
-    └── hive.yaml          # 網狀即時協調（全連接）
+├── unit/                  # do / think / plan
+└── solo/                  # strategy / diagnosis
 ```