kenaz 0.3.13 → 0.3.15

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

@@ -1,52 +1,43 @@
 ## 專案路徑
-ARGUMENTS 含 `[專案: X]` 或 `--project-path X` → PROJECT_PATH = X，下方 boot 腳本與 task-api / dispatch 呼叫都附加 `--project-path "<PROJECT_PATH>"`。沒有就留空，什麼都不加。
+ARGUMENTS 含 `[專案: X]` 或 `--project-path X` → PROJECT_PATH = X，下方 boot、task-api、dispatch 都附加 `--project-path "<PROJECT_PATH>"`。沒有就不加。
 
 # Ansuz boot
 
-你是 **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 有 `📎 Project handoff` 時，**先用 Read 讀 → 標記的那份全文**（不用問用戶），以它為準接續上一個 session。
-4. 把 banner 轉述給用戶（Bash 輸出在 UI 會摺疊），依 handoff 的 R 段與 `📋 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 加 `--project-path`）。把輸出 JSON 的 `promptText` 交給 subagent，`agentParams` 照用（模型不要自己換）。
-  3. subagent 在 worktree 裡改完並 commit；你驗證後合併。
-     若輸出是 `executor` 區塊（模型為 `codex:<id>` / `deepseek:<model>`，無 agentParams）：用 Bash run_in_background 執行 `executor.command`，等完成通知，讀 `executor.resultFile`（ok、commits；`no commits` = 失敗），再照常驗證並合併 `executor.branchName`。
-- 開卡前先確認 scope 與驗收條件對準真正的問題，不要照著錯的假設派工。
-
-## 驗證（合併前一定做，強度跟風險相稱）
-- 走**真實路徑**：實際執行會被使用者用到的那條路（真的安裝、真的啟動、真的收發訊息），不只看單元測試。
-- 有**對照組**：證明測試在舊程式上會失敗，或修改前後結果不同。
-- subagent 回報「未驗證」的項目，由你補驗或明講仍未驗證。
-- 合併：`git merge` 後跑相關測試（或 `node .specialist/Ansuz/tools/verify-and-land.js`），用這個專案自己的測試指令。
-
-## 交接（handoff，ISBAR）
-用戶說交接／暫停／換 session、context 快滿、或結束時仍有未完成的工作 → 寫交接：
-1. `node .specialist/tools/handoff-doc.js new --topic "<主題>" --session <id>`（有 PROJECT_PATH 加 `--project-path`），建立 `<專案>/.kenaz/handoffs/<日期時間>-<主題>.md`，I 段已自動填好。
-2. 用 Edit 填 S（現況）、B（背景：用戶決定原話、相關卡與 commit）、A（已驗證／未驗證／風險）、R（下一個 session 第一步、待用戶決定的事）。寫給「沒看過這段對話的人」，不寫空泛句。
-3. 一份交接一個檔，不覆寫舊的；下一個 session 的 boot 會自動列出並讀最新那份。
+你是 **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 有 `📎 Project handoff`：先 Read → 標記的那份全文，以它接續。
+4. 轉述 banner，依 handoff 的 R 段與 `📋 Open cards` 提出議程。`[lessons]`、`[learn]`、`[glossary]` 行照 RULES.md 的 Lessons / Project glossary 處理。
+
+## 工作方式
+- **自己做**：約 30 行內的小修正 → 直接改，跑最近的測試，提交。
+- **開卡派工**（中型、可平行、高風險）：`kenaz_task_create` 開卡（requirements、acceptance criteria、scope paths）→ `node .formation/tools/dispatch.js --skill=do --task=TASK_XXX --dispatch-mode=subagent` → `promptText` 給 subagent、`agentParams` 照用（不換模型）；輸出是 `executor` 區塊時照 RULES.md 的 Dispatch 執行。subagent 在 worktree commit，你驗證後合併。
+- 開卡前確認 scope 與驗收條件對準真正的問題。
+
+## 驗證（合併前，強度跟風險相稱）
+- **真實路徑**：實際跑使用者會走的路，不只看單元測試。
+- **對照組**：證明測試在舊程式上會失敗。
+- subagent 的「未驗證」由你補驗或明講。合併後跑相關測試（含被改檔案的既有測試）。
+
+## 交接
+用戶說交接／暫停、context 快滿、或結束時有未完成工作：`node .specialist/tools/handoff-doc.js new --topic "<主題>" --session <id>`，再填 S/B/A/R（見 RULES.md 的 Handoff）。
 
 ## 回報與提問
-- 一律用用戶的語言（中文訊息 → 中文回覆，含提問選項）。
-- 需要用戶決定時用 `AskUserQuestion`（2-4 個選項、建議的放第一個），不要在文字裡列選項等回覆；有證據能自己判斷的事不問。
-- 回報說清楚：做了什麼、怎麼驗證的、還有什麼沒驗證或需要用戶決定。不說「應該可以」。
+- 用用戶的語言（中文訊息 → 中文，含提問選項）。
+- 需要用戶決定時用 `AskUserQuestion`（2-4 選項、建議的放第一），有證據能自己判斷的不問。
+- 說清楚做了什麼、怎麼驗證、什麼沒驗證或要用戶決定。不說「應該可以」。
 
-## Kenaz 本身出問題時：先回報再繞過
-Kenaz 的工具、hook、安裝、peer、派工擋住或拖慢工作時，**繞過之前**先 `kenaz_wish_create`（`projectPath`；`scope` kenaz|project；`wish_type` bug|feature|question；`content` = 一行重現 + 預期 vs 實際 + `npx kenaz doctor` 版本 + session id，不貼金鑰）。一個問題報一次，報完照常完成工作並告訴用戶；用戶說「回報這個問題」也用它（`source`=`user`）。
+## Kenaz 本身出問題：先回報再繞過
+繞過之前先 `kenaz_wish_create`（`scope` kenaz|project；`wish_type` bug|feature|question；一行重現 + 預期 vs 實際 + `npx kenaz doctor` 版本 + session id，不貼金鑰），報完照常完成工作。
 
 ## 自主模式
-用戶明確授權自主時：立刻 `node .specialist/tools/autonomy.js grant --session <id> --scope "<範圍>"`，讀 RULES.md 的 Autonomy。之後結束回合會被 Stop hook 擋回：自己決定、一路做完，不在結尾問「要我…嗎？」；只有必要停點才 `pause`，做完才 `done`。
+用戶明確授權自主時：`node .specialist/tools/autonomy.js grant --session <id> --scope "<範圍>"`，讀 RULES.md 的 Autonomy；只在必要停點 `pause`，做完 `done`。
 
-## 參考產品（REA）與學習教訓
-- banner `[rea]` 行：用戶提到參考產品時，有 REA 就提議分析，沒有就提示一次 `npx rea-agents setup`（範圍見 RULES.md 的 REA）。
-- 用戶糾正/重複指示、推翻決定、或驗證抓到失敗時，自動寫教訓並在回報點名一行：`node .specialist/tools/lessons.js add --scope user|project --type pref|fact|pitfall|check --text "..."`（規則見 RULES.md 的 Lessons）。
-- banner 出現 `[lessons] N to graduate`：跑 `kenaz learn review`，提議把排第一的教訓改成代碼（測試、hook 檢查或專案 CLAUDE.md/AGENTS.md 規則，這是首選結果）；糾正若與既有教訓相符屬於重複（recurrence），不是新教訓（`add` 會自動累加）。
-- banner 出現 `[learn] N history items to review`：跑 `kenaz learn review`，每個歷史項目（返工、executor 失敗、blocked 卡、handoff 風險行）有現成的 `kenaz learn add ... --source harvest:<id>`，值得記的補上 why 後執行，其餘忽略；指標建議（各 rigor 一次過率、返工最多的檔案）只建議給用戶，不自行套用。詳見 RULES.md。
+## 教訓、詞彙、參考產品
+- 用戶糾正、推翻決定、或驗證抓到失敗：`node .specialist/tools/lessons.js add --scope user|project --type pref|fact|pitfall|check --text "..."`，回報點名一行。
+- 用戶定義或拍板專案術語：`kenaz glossary add "<term>" --means "..."`；問術語前先讀 `.kenaz/GLOSSARY.md`。
+- `[rea]` 行、教訓生命週期與歷程收割：見 RULES.md（REA、Lessons）。
 
-需要更多規則時（授權自主、派工前、合併前、參考產品、寫教訓）讀 `.specialist/Ansuz/RULES.md`。
+需要更多規則時（自主、派工、合併、交接、教訓、REA）讀 `.specialist/Ansuz/RULES.md`。

package/core/.formation/bifrost/exec.js

@@ -15,9 +15,12 @@ const os = require('os');
 const path = require('path');
 const { spawn, spawnSync } = require('child_process');
 
-const DEEPSEEK_MODELS = ['deepseek-chat', 'deepseek-reasoner'];
+// First = default. From GET https://api.deepseek.com/models on 2026-10-11 (V4 ids, 1M context); the V3 ids still
+// answer but are no longer listed. `kenaz launch` re-reads the context window from that endpoint at start.
+const DEEPSEEK_MODELS = ['deepseek-v4-pro', 'deepseek-flash', 'deepseek-chat', 'deepseek-reasoner'];
 const DEEPSEEK_BASE_URL = 'https://api.deepseek.com/anthropic';
-const DEEPSEEK_CONTEXT_TOKENS = 128000;
+const DEEPSEEK_CONTEXT_TOKENS = { 'deepseek-v4-pro': 1048576, 'deepseek-flash': 1048576, 'deepseek-chat': 128000, 'deepseek-reasoner': 128000 };
+const DEEPSEEK_FAST = 'deepseek-flash'; // Claude Code's small/fast slot (titles, summaries): the cheap model
 const CLAUDE_TOOLS = ['Bash', 'Edit', 'Write', 'Read', 'Glob', 'Grep'];
 
 const codexSpec = (id) => require('./openai/relay.js').resolveCodexModelSpec(id);
@@ -66,14 +69,26 @@ function buildChild({ adapter, id, worktree, lastFile, key, gitDir }) {
 /** Claude Code env for DeepSeek's Anthropic-compatible endpoint (shared by exec.js and `kenaz launch --provider deepseek`).
  *  Every model slot points at DeepSeek: background requests (small/fast = haiku) and Agent-tool subagents
  *  (sonnet/opus aliases) would otherwise ask DeepSeek for Claude model names it does not serve. */
-function deepseekEnv(id, key) {
+function deepseekEnv(id, key, contextTokens) {
   return {
-    ANTHROPIC_BASE_URL: DEEPSEEK_BASE_URL, ANTHROPIC_AUTH_TOKEN: key, ANTHROPIC_MODEL: id, ANTHROPIC_SMALL_FAST_MODEL: id,
-    ANTHROPIC_DEFAULT_HAIKU_MODEL: id, ANTHROPIC_DEFAULT_SONNET_MODEL: id, ANTHROPIC_DEFAULT_OPUS_MODEL: id, CLAUDE_CODE_SUBAGENT_MODEL: id,
-    // Claude Code does not know DeepSeek ids and assumes a 200k window; DeepSeek serves 128k, so auto-compact must start earlier.
-    CLAUDE_CODE_MAX_CONTEXT_TOKENS: String(DEEPSEEK_CONTEXT_TOKENS),
+    ANTHROPIC_BASE_URL: DEEPSEEK_BASE_URL, ANTHROPIC_AUTH_TOKEN: key, ANTHROPIC_MODEL: id, ANTHROPIC_SMALL_FAST_MODEL: DEEPSEEK_FAST,
+    ANTHROPIC_DEFAULT_HAIKU_MODEL: DEEPSEEK_FAST, ANTHROPIC_DEFAULT_SONNET_MODEL: id, ANTHROPIC_DEFAULT_OPUS_MODEL: id, CLAUDE_CODE_SUBAGENT_MODEL: id,
+    // Claude Code does not know DeepSeek ids and assumes a 200k window: tell it the real one (V4 = 1M; a 128k
+    // value here made a V4 session compact right after the Ansuz boot).
+    CLAUDE_CODE_MAX_CONTEXT_TOKENS: String(contextTokens || DEEPSEEK_CONTEXT_TOKENS[id] || 128000),
   };
 }
+
+/** {id: context_window} from GET /models (the live list); null on any failure (callers fall back to the table). */
+async function deepseekModels(key, fetchFn = globalThis.fetch, timeoutMs = 3000) {
+  try {
+    const r = await fetchFn('https://api.deepseek.com/models', { headers: { Authorization: 'Bearer ' + key }, signal: AbortSignal.timeout(timeoutMs) });
+    const j = await r.json();
+    const out = {};
+    for (const m of (j && j.data) || []) if (m && m.id) out[m.id] = Number(m.context_window) || null;
+    return Object.keys(out).length ? out : null;
+  } catch { return null; }
+}
 const DEEPSEEK_UNSET = ['ANTHROPIC_API_KEY']; // never send a real Anthropic key to another vendor
 
 const git = (cwd, args) => spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true });
@@ -144,4 +159,4 @@ async function main(argv) {
 }
 
 if (require.main === module) main(process.argv.slice(2)).then((c) => { process.exitCode = c; });
-module.exports = { parseExecutorModel, deepseekKey, deepseekEnv, DEEPSEEK_UNSET, winQuote, buildChild, run, main, DEEPSEEK_MODELS };
+module.exports = { parseExecutorModel, deepseekKey, deepseekEnv, deepseekModels, DEEPSEEK_UNSET, winQuote, buildChild, run, main, DEEPSEEK_MODELS };

package/core/.formation/bifrost/provider-launch.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 /**
- * `kenaz launch --provider deepseek [--model deepseek-chat|deepseek-reasoner] [claude args...]`
+ * `kenaz launch --provider deepseek [--model deepseek-v4-pro|deepseek-flash|...] [claude args...]`
  * Starts Claude Code with every model request sent to another vendor's Anthropic-compatible endpoint, so
  * Ansuz (/kenaz:Ansuz), its subagents and background requests run on that vendor and use no Claude quota.
  * The key is read from the env or ~/.kenaz/credentials.yaml and set only in the claude child's env: never in
@@ -9,18 +9,17 @@
  */
 const os = require('os');
 const { spawn } = require('child_process');
-const { deepseekKey, deepseekEnv, DEEPSEEK_UNSET, DEEPSEEK_MODELS, winQuote } = require('./exec');
+const { deepseekKey, deepseekEnv, deepseekModels, DEEPSEEK_UNSET, DEEPSEEK_MODELS, winQuote } = require('./exec');
 
 const PROVIDERS = {
   deepseek: {
-    models: DEEPSEEK_MODELS, key: deepseekKey, env: deepseekEnv, unset: DEEPSEEK_UNSET,
+    models: DEEPSEEK_MODELS, key: deepseekKey, env: deepseekEnv, live: deepseekModels, unset: DEEPSEEK_UNSET,
     keyHelp: 'set DEEPSEEK_API_KEY, or add `deepseek_api_key: <key>` to ~/.kenaz/credentials.yaml',
   },
 };
 const USAGE = 'usage: kenaz launch --provider <' + Object.keys(PROVIDERS).join('|') + '> [--model <id>] [claude args...]';
 
-/** Child process plan: { bin, args, env }. Throws with a user-facing message. */
-function plan(argv, env = process.env, home = os.homedir()) {
+function parse(argv) {
   const rest = []; let provider = null; let model = null;
   for (let i = 0; i < argv.length; i++) {
     const m = /^--(provider|model)(?:=(.*))?$/.exec(argv[i]);
@@ -28,22 +27,35 @@ function plan(argv, env = process.env, home = os.homedir()) {
     const v = m[2] !== undefined ? m[2] : argv[++i];
     if (m[1] === 'provider') provider = v; else model = v;
   }
+  return { rest, provider, model };
+}
+
+/** Child process plan: { bin, args, env }. live = {id: context_window} from the vendor's model list (or null):
+ *  a listed id is valid even if it is newer than the built-in list, and its window drives auto-compact.
+ *  Throws with a user-facing message. */
+function plan(argv, env = process.env, home = os.homedir(), live = null) {
+  const { rest, provider, model } = parse(argv);
   const p = PROVIDERS[provider];
   if (!p) throw new Error((provider ? `unknown provider '${provider}'. ` : '') + USAGE);
   const id = model || p.models[0];
-  if (!p.models.includes(id)) throw new Error(`unknown ${provider} model '${id}'; valid: ${p.models.join(', ')}`);
+  const valid = [...new Set([...p.models, ...Object.keys(live || {})])];
+  if (!valid.includes(id)) throw new Error(`unknown ${provider} model '${id}'; valid: ${valid.join(', ')}`);
   const key = p.key(env, home);
   if (!key) throw new Error(`${provider}: no API key (${p.keyHelp})`);
-  const childEnv = { ...env, ...p.env(id, key), CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1' };
+  const childEnv = { ...env, ...p.env(id, key, live && live[id]), CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1' };
   for (const k of p.unset) delete childEnv[k];
-  return { bin: 'claude', args: rest, env: childEnv, provider, model: id };
+  return { bin: 'claude', args: rest, env: childEnv, provider, model: id, context: childEnv.CLAUDE_CODE_MAX_CONTEXT_TOKENS };
 }
 
 /** Resolves to the child's exit code. deps: { spawn, env, home, platform } for tests. */
-function main(argv, out = console.log, deps = {}) {
+async function main(argv, out = console.log, deps = {}) {
+  const env = deps.env || process.env, home = deps.home || os.homedir();
+  const p = PROVIDERS[parse(argv).provider];
+  const key = p && p.key(env, home);
+  const live = key ? await (deps.live || p.live)(key) : null;
   let pl;
-  try { pl = plan(argv, deps.env || process.env, deps.home || os.homedir()); } catch (e) { out(e.message); return Promise.resolve(2); }
-  out(`kenaz launch: Claude Code on ${pl.provider} (${pl.model}); no Claude quota is used in this session`);
+  try { pl = plan(argv, env, home, live); } catch (e) { out(e.message); return 2; }
+  out(`kenaz launch: Claude Code on ${pl.provider} (${pl.model}, context ${pl.context} tokens); no Claude quota is used in this session`);
   const win = (deps.platform || process.platform) === 'win32'; // claude is a .cmd shim on npm installs
   const child = (deps.spawn || spawn)(win ? [pl.bin, ...pl.args].map(winQuote).join(' ') : pl.bin, win ? [] : pl.args,
     { stdio: 'inherit', env: pl.env, shell: win });

package/core/.formation/bifrost/provider-launch.test.js

@@ -16,7 +16,7 @@ function fakeSpawn(calls, code = 0) {
 test('deepseek: every model slot points at DeepSeek, key only in the child env, Anthropic key removed', async () => {
   const calls = [], lines = [];
   const rc = await main(['--provider', 'deepseek', '--resume', 'abc'], (l) => lines.push(l),
-    { spawn: fakeSpawn(calls), env: { DEEPSEEK_API_KEY: KEY, ANTHROPIC_API_KEY: 'real-anthropic', PATH: 'p' }, home: home(), platform: 'linux' });
+    { spawn: fakeSpawn(calls), live: async () => null, env: { DEEPSEEK_API_KEY: KEY, ANTHROPIC_API_KEY: 'real-anthropic', PATH: 'p' }, home: home(), platform: 'linux' });
   assert.strictEqual(rc, 0);
   const c = calls[0];
   assert.strictEqual(c.cmd, 'claude');
@@ -24,9 +24,11 @@ test('deepseek: every model slot points at DeepSeek, key only in the child env,
   const e = c.opts.env;
   assert.strictEqual(e.ANTHROPIC_BASE_URL, 'https://api.deepseek.com/anthropic');
   assert.strictEqual(e.ANTHROPIC_AUTH_TOKEN, KEY);
-  for (const k of ['ANTHROPIC_MODEL', 'ANTHROPIC_SMALL_FAST_MODEL', 'ANTHROPIC_DEFAULT_HAIKU_MODEL', 'ANTHROPIC_DEFAULT_SONNET_MODEL', 'ANTHROPIC_DEFAULT_OPUS_MODEL', 'CLAUDE_CODE_SUBAGENT_MODEL']) {
-    assert.strictEqual(e[k], 'deepseek-chat', k);
+  for (const k of ['ANTHROPIC_MODEL', 'ANTHROPIC_DEFAULT_SONNET_MODEL', 'ANTHROPIC_DEFAULT_OPUS_MODEL', 'CLAUDE_CODE_SUBAGENT_MODEL']) {
+    assert.strictEqual(e[k], 'deepseek-v4-pro', k);
   }
+  assert.strictEqual(e.ANTHROPIC_SMALL_FAST_MODEL, 'deepseek-flash'); assert.strictEqual(e.ANTHROPIC_DEFAULT_HAIKU_MODEL, 'deepseek-flash');
+  assert.strictEqual(e.CLAUDE_CODE_MAX_CONTEXT_TOKENS, '1048576', 'V4 window from the built-in table when the live list is unavailable');
   assert.strictEqual(e.ANTHROPIC_API_KEY, undefined);
   assert.strictEqual(e.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, '1');
   assert.strictEqual(e.PATH, 'p', 'the rest of the env is kept');
@@ -37,11 +39,12 @@ test('--model, key from ~/.kenaz/credentials.yaml, Windows goes through the shel
   const h = home(); fs.mkdirSync(path.join(h, '.kenaz'));
   fs.writeFileSync(path.join(h, '.kenaz', 'credentials.yaml'), `relay: x\ndeepseek_api_key: "${KEY}"\n`);
   const calls = [];
-  const rc = await main(['--provider=deepseek', '--model', 'deepseek-reasoner'], () => {}, { spawn: fakeSpawn(calls), env: {}, home: h, platform: 'win32' });
+  const rc = await main(['--provider=deepseek', '--model', 'deepseek-reasoner'], () => {}, { spawn: fakeSpawn(calls), live: async () => null, env: {}, home: h, platform: 'win32' });
   assert.strictEqual(rc, 0);
   assert.strictEqual(calls[0].cmd, 'claude');
   assert.strictEqual(calls[0].opts.shell, true);
   assert.strictEqual(calls[0].opts.env.ANTHROPIC_MODEL, 'deepseek-reasoner');
+  assert.strictEqual(calls[0].opts.env.CLAUDE_CODE_MAX_CONTEXT_TOKENS, '128000', 'legacy V3 id keeps its 128k window');
   assert.ok(!calls[0].cmd.includes(KEY));
 });
 
@@ -50,13 +53,23 @@ test('control: no key, unknown provider or model -> exit 2 and claude is never s
     [['--provider', 'deepseek'], {}, /no API key/],
     [['--provider', 'nope'], { DEEPSEEK_API_KEY: KEY }, /unknown provider 'nope'/],
     [[], { DEEPSEEK_API_KEY: KEY }, /usage: kenaz launch --provider <deepseek>/],
-    [['--provider', 'deepseek', '--model', 'gpt-x'], { DEEPSEEK_API_KEY: KEY }, /valid: deepseek-chat, deepseek-reasoner/],
+    [['--provider', 'deepseek', '--model', 'gpt-x'], { DEEPSEEK_API_KEY: KEY }, /valid: deepseek-v4-pro, deepseek-flash, deepseek-chat, deepseek-reasoner/],
   ]) {
     const calls = [], lines = [];
-    const rc = await main(argv, (l) => lines.push(l), { spawn: fakeSpawn(calls), env, home: home(), platform: 'linux' });
+    const rc = await main(argv, (l) => lines.push(l), { spawn: fakeSpawn(calls), live: async () => null, env, home: home(), platform: 'linux' });
     assert.strictEqual(rc, 2, argv.join(' '));
     assert.strictEqual(calls.length, 0, 'claude not started: ' + argv.join(' '));
     assert.match(lines.join('\n'), re);
   }
   assert.throws(() => plan(['--provider', 'deepseek'], {}, home()), /no API key/);
 });
+
+test('live model list: a newer listed id is accepted and its context window drives auto-compact', async () => {
+  const calls = [], lines = [];
+  const live = async (k) => { assert.strictEqual(k, KEY); return { 'deepseek-v5-preview': 2097152, 'deepseek-v4-pro': 1048576 }; };
+  const rc = await main(['--provider', 'deepseek', '--model', 'deepseek-v5-preview'], (l) => lines.push(l), { spawn: fakeSpawn(calls), live, env: { DEEPSEEK_API_KEY: KEY }, home: home(), platform: 'linux' });
+  assert.strictEqual(rc, 0);
+  assert.strictEqual(calls[0].opts.env.ANTHROPIC_MODEL, 'deepseek-v5-preview');
+  assert.strictEqual(calls[0].opts.env.CLAUDE_CODE_MAX_CONTEXT_TOKENS, '2097152');
+  assert.match(lines[0], /context 2097152 tokens/);
+});

package/core/.formation/tools/__tests__/diagnose-bug.test.js

@@ -0,0 +1,73 @@
+// TASK_2429: bug-diagnosis A/B arm in dispatch (temp dirs only).
+// Usage: node .formation/tools/__tests__/diagnose-bug.test.js
+'use strict';
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const D = require('../dispatch');
+
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+const SB = fs.mkdtempSync(path.join(os.tmpdir(), 't2429_'));
+let pass = 0; let fail = 0;
+const check = (name, cond, detail) => { console.log((cond ? 'PASS' : 'FAIL') + ' | ' + name + (cond ? '' : ' | ' + detail)); cond ? pass++ : fail++; };
+
+// detection
+const card = (o) => JSON.stringify(o);
+check('tag bug', D.isBugCard(card({ title: 'x', tags: ['bug'] })), '');
+check('tag Fix (case)', D.isBugCard(card({ title: 'x', tags: ['Fix'] })), '');
+check('tag regression', D.isBugCard(card({ title: 'x', tags: ['ui', 'regression'] })), '');
+check('type: bug', D.isBugCard(card({ title: 'x', type: 'bug' })), '');
+check('title fix:', D.isBugCard(card({ title: 'Fix login crash' })), '');
+check('title bug', D.isBugCard(card({ title: 'bug in stats' })), '');
+check('title CJK 修正', D.isBugCard(card({ title: '修正登入錯誤' })), '');
+check('title CJK 修', D.isBugCard(card({ title: '修 dashboard 閃退' })), '');
+check('negative: feature', !D.isBugCard(card({ title: 'Add export', tags: ['feature'] })), '');
+check('negative: fixture word', !D.isBugCard(card({ title: 'Fixture loader for tests' })), '');
+check('negative: fix mid-title', !D.isBugCard(card({ title: 'Add quick fix menu' })), '');
+check('negative: debug tag', !D.isBugCard(card({ title: 'x', tags: ['debugging'] })), '');
+check('negative: null / garbage', !D.isBugCard(null) && !D.isBugCard('not json') && !D.isBugCard('{}'), '');
+
+// arm assignment
+check('arm stable for same id', D.diagnoseArmFor('TASK_2429') === D.diagnoseArmFor('TASK_2429'), '');
+let withN = 0;
+for (let i = 1000; i < 1200; i++) if (D.diagnoseArmFor('TASK_' + i) === 'with') withN++;
+check('arm balanced over 200 ids (40-60%)', withN >= 80 && withN <= 120, 'with=' + withN);
+check('override on/off', D.diagnoseArmFor('TASK_1', 'on') === 'with' && D.diagnoseArmFor('TASK_1', 'off') === 'without', '');
+
+// stats record carries the arm
+D.appendDispatchPromptStats({ taskId: 'TASK_7', promptText: 'p', formation: 'unit', model: 'm', projectPath: SB, diagnoseArm: 'with' });
+D.appendDispatchPromptStats({ taskId: 'TASK_8', promptText: 'p', formation: 'unit', model: 'm', projectPath: SB });
+const recs = fs.readFileSync(path.join(SB, '.kenaz', 'specialist', 'dispatch_prompt_stats.jsonl'), 'utf8').trim().split('\n').map((l) => JSON.parse(l));
+check('stats record: diagnose_arm = with / null for non-bug', recs[0].diagnose_arm === 'with' && recs[1].diagnose_arm === null, JSON.stringify(recs));
+
+// real dry-run dispatch path in a sandbox project
+for (const d of ['backlog', 'active', 'done', 'blocked', 'cancel']) fs.mkdirSync(path.join(SB, '.kenaz', 'tasks', d), { recursive: true });
+fs.mkdirSync(path.join(SB, '.kenaz', 'locks'), { recursive: true });
+const env = { ...process.env }; delete env.CLAUDE_PROJECT_DIR;
+const run = (script, args) => spawnSync(process.execPath, [script, ...args], { encoding: 'utf8', env, windowsHide: true, cwd: ROOT });
+const mk = (title, extra) => {
+  const r = run(path.join(ROOT, '.collaboration/core/task-api.js'), ['--project-path', SB, 'create', '--title', title, '--description', 'd', '--scope-paths', 'zzz/a.js',
+    '--requirements', 'r1', '--acceptance-criteria', 'a1', '--acceptance-criteria', 'a2', '--acceptance-criteria', 'a3', '--technical-notes', 't1', '--technical-notes', 't2', '--force', ...extra]);
+  return ((r.stdout || '').match(/TASK_\d+/) || [])[0];
+};
+const dry = (id, extra) => {
+  const r = run(path.join(ROOT, '.formation/tools/dispatch.js'), ['--skill=do', '--task=' + id, '--dispatch-mode=subagent', '--dry-run', '--project-path', SB, ...extra]);
+  try { return JSON.parse(r.stdout); } catch { return { err: (r.stdout + r.stderr).slice(-300) }; }
+};
+const bug = mk('Fix flaky stats crash', ['--tags', 'bug']);
+const feat = mk('Add export button', ['--tags', 'feature']);
+check('setup: cards created', !!bug && !!feat, bug + ' ' + feat);
+if (bug && feat) {
+  const on = dry(bug, ['--diagnose', 'on']); const off = dry(bug, ['--diagnose', 'off']);
+  check('with arm: section + diagnoseArm', !!on.promptText && on.promptText.includes('## Bug diagnosis') && on.promptText.includes('diagnose-bug.md') && on.diagnoseArm === 'with', JSON.stringify(on).slice(0, 300));
+  check('without arm: no section, diagnoseArm=without', !!off.promptText && !off.promptText.includes('## Bug diagnosis') && off.diagnoseArm === 'without', JSON.stringify(off).slice(0, 300));
+  check('default arm follows the id hash', dry(bug, []).diagnoseArm === D.diagnoseArmFor(bug), '');
+  const fOn = dry(feat, ['--diagnose', 'on']); const fOff = dry(feat, ['--diagnose', 'off']);
+  check('non-bug: no section, no arm, prompt identical whatever --diagnose says', !!fOn.promptText && !fOn.promptText.includes('## Bug diagnosis') && fOn.diagnoseArm === undefined && fOn.promptText === fOff.promptText, JSON.stringify(fOn).slice(0, 300));
+  check('with-arm prompt = without-arm prompt + section only', !!on.promptText && !!off.promptText && on.promptText === off.promptText + '\n\n' + D.BUG_DIAGNOSIS_SECTION + '\n', '');
+}
+
+try { fs.rmSync(SB, { recursive: true, force: true }); } catch { /* best effort */ }
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail ? 1 : 0);

package/core/.formation/tools/dispatch-detail/diagnose-bug.md

@@ -0,0 +1,23 @@
+# Diagnosing a bug
+
+Adapted from `diagnosing-bugs` in github.com/mattpocock/skills (MIT license). Applies to bug cards in the
+`with` arm of the TASK_2429 A/B (see dev/research/self-improvement/DESIGN.md).
+
+The loop comes first. Guessing at a fix without a loop that fails on this bug is the main cause of wrong fixes.
+
+1. **Red loop before any code change.** Build the cheapest thing that fails because of this bug: a test at the
+   nearest seam (the lowest function that still shows the wrong result), a CLI or HTTP repro script, a replayed
+   artifact (the log, payload or file that triggered it), or a bisect harness over commits. Run it and see it fail
+   for the reported reason, not for a missing fixture. Inline fixtures that differ from the real input are the usual
+   way a loop passes while the bug lives on: use the real path.
+2. **Tighten it.** Fast (seconds), specific (fails only on this bug), deterministic (no clock, network or order
+   dependence; run it 3 times). A flaky loop proves nothing.
+3. **Hypotheses, ranked.** Write 3 or fewer causes, most likely first. For each, name the observation that would
+   kill it (a value, a log line, a branch not taken). Instrument to get that observation; do not edit behavior to
+   test a guess. When a hypothesis dies, list the rest again instead of tweaking the same spot.
+4. **Fix** the cause the observation shows, at the place it originates, not where the symptom appears.
+5. **Prove it.** Loop green with the fix, and red again with the fix reverted (the control: green alone could
+   mean the loop never exercised the bug). Keep the test. Check one sibling: the same pattern elsewhere.
+6. **Redact secrets** (tokens, keys, cookies, personal data) in anything you print, log, commit or report.
+
+Report: the loop command, its red output (one line), the green output, and the revert check.

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

@@ -627,6 +627,38 @@ function buildCortexContext(scopePaths, projectPath) {
 // TASK_1998 R1: dispatch-prompt telemetry
 // ─────────────────────────────────────────
 
+// TASK_2429: bug-diagnosis discipline (adapted from mattpocock/skills diagnosing-bugs, MIT) with a
+// randomized A/B arm per bug card, so its benefit is measured (dev/research/self-improvement/DESIGN.md).
+function isBugCard(taskData) {
+  let t;
+  try { t = typeof taskData === 'string' ? JSON.parse(taskData) : taskData; } catch { return false; }
+  if (!t || typeof t !== 'object') return false;
+  const tags = Array.isArray(t.tags) ? t.tags : (typeof t.tags === 'string' ? t.tags.split(/[,\s]+/) : []);
+  if (tags.some((x) => /^(bug|fix|regression)$/i.test(String(x).trim()))) return true;
+  if (/^bug$/i.test(String(t.type || '').trim())) return true;
+  return /^\s*((fix(es|ed)?|bug)\b|修)/i.test(String(t.title || ''));
+}
+
+/** 'with' | 'without': stable 50/50 split by task id (FNV-1a), unless forced by --diagnose on|off. */
+function diagnoseArmFor(taskId, override) {
+  if (override === 'on') return 'with';
+  if (override === 'off') return 'without';
+  let h = 2166136261;
+  for (const ch of String(taskId || '')) { h ^= ch.charCodeAt(0); h = Math.imul(h, 16777619) >>> 0; }
+  return (h >>> 7) % 2 === 0 ? 'with' : 'without';
+}
+
+const BUG_DIAGNOSIS_SECTION = [
+  '## Bug diagnosis',
+  'Follow .formation/tools/dispatch-detail/diagnose-bug.md (Read it first):',
+  '1. Build a loop that goes red on this bug before touching code (test at the nearest seam, repro script, replayed artifact).',
+  '2. Tighten it: fast, specific, deterministic.',
+  '3. Rank hypotheses, each with the observation that would kill it.',
+  '4. Fix the cause the loop shows.',
+  '5. Prove it: loop green with the fix, red with the fix reverted; keep the test.',
+  '6. Redact secrets in anything you print or commit.',
+].join('\n');
+
 /**
  * Append one structured JSONL line to .kenaz/specialist/dispatch_prompt_stats.jsonl —
  * one per sub-agent dispatch (getSubagentDispatchParams). Mirrors
@@ -641,7 +673,7 @@ function buildCortexContext(scopePaths, projectPath) {
  * complexity (TASK_1998 two-axis policy): the normalized 'simple'|'medium'|'complex'
  * CONTEXT-volume key (extractComplexity() default). Optional for older readers.
  */
-function appendDispatchPromptStats({ taskId, rigor, complexity, formation, promptText, model, modelSource, projectPath }) {
+function appendDispatchPromptStats({ taskId, rigor, complexity, formation, promptText, model, modelSource, projectPath, diagnoseArm }) {
   const root = projectPath || ROOT;
   const dir = path.join(root, '.kenaz', 'specialist');
   try {
@@ -656,6 +688,7 @@ function appendDispatchPromptStats({ taskId, rigor, complexity, formation, promp
       sections: splitPromptSections(promptText || ''),
       model,
       model_source: modelSource || null,
+      diagnose_arm: diagnoseArm || null,
     });
     fs.appendFileSync(path.join(dir, 'dispatch_prompt_stats.jsonl'), line + '\n', 'utf8');
   } catch { /* best-effort — telemetry must never block dispatch */ }
@@ -743,6 +776,7 @@ Options:
   --formation <name>      Skill folder: unit (default) or solo
   --skill <name>          Skill to use (YAML filename without extension)
   --task <value>          Task ID (TASK_XXX) or free-text description
+  --diagnose on|off       Force the bug-diagnosis A/B arm for a bug card (default: stable hash of the task id)
   --dry-run               Build and print the payload with no side effects
   --dispatch-mode <mode>  Required: subagent (JSON params for the Agent tool)
   --harness <name>        claude (default) | codex (Codex spawn_agent payload)
@@ -868,7 +902,7 @@ Sub-agent dispatch (Ansuz billing-aware path):
     console.error('❌ --dispatch-mode=subagent is required (Formation headless/squad/legion dispatch is retired)');
     process.exit(1);
   }
-  getSubagentDispatchParams({ formation, skill, task, projectPath, force, useWorktree: useWorktreeCli, dispatchModelOverride: dispatchModelCli, dryRun, harness: harnessCli }).then(result => {
+  getSubagentDispatchParams({ formation, skill, task, projectPath, force, useWorktree: useWorktreeCli, dispatchModelOverride: dispatchModelCli, dryRun, harness: harnessCli, diagnose: getArg('--diagnose') }).then(result => {
     if (!result) { process.exitCode = 1; return; }
     process.stdout.write(JSON.stringify(result, null, 2) + '\n');
   }).catch(e => {
@@ -942,6 +976,7 @@ async function getSubagentDispatchParams(options) {
     dryRun = false,
     // TASK_2315: 'claude' (Agent tool) | 'codex' (Codex-native spawn_agent). Selects the payload shape.
     harness = 'claude',
+    diagnose = null, // TASK_2429: --diagnose on|off forces the bug-diagnosis arm
   } = options;
   if (harness !== 'claude' && harness !== 'codex') {
     console.error(`❌ --harness expects claude|codex (got '${harness}')`);
@@ -1190,7 +1225,10 @@ async function getSubagentDispatchParams(options) {
   if (projectPath) promptOptions.projectPath = projectPath;
   if (taskInput && taskInput.startsWith('TASK_')) promptOptions.taskId = taskInput;
 
-  const rawPrompt = buildPrompt(skillDef, taskInput, taskData, promptOptions);
+  let rawPrompt = buildPrompt(skillDef, taskInput, taskData, promptOptions);
+  // TASK_2429: only bug cards get an arm; any other prompt stays byte-for-byte unchanged.
+  const diagnoseArm = isBugCard(taskData) ? diagnoseArmFor(taskInput, diagnose) : null;
+  if (diagnoseArm === 'with' && typeof rawPrompt === 'string') rawPrompt = rawPrompt + '\n\n' + BUG_DIAGNOSIS_SECTION + '\n';
 
   // 4. Cortex context (same as Formation dispatch)
   const taskScopePaths = (() => {
@@ -1335,7 +1373,7 @@ async function getSubagentDispatchParams(options) {
   // by dashboard vs dashboard-by-rigor vs cli without re-deriving it.
   // Two-axis policy: complexity rides along too, so dispatch-stats.js can
   // group by (rigor, complexity) instead of rigor alone.
-  if (!dryRun) appendDispatchPromptStats({ taskId: taskInput, rigor: resolution.rigorKey, complexity, formation, promptText, model: dispatchModel || rawModel, modelSource: resolution.source, projectPath });
+  if (!dryRun) appendDispatchPromptStats({ taskId: taskInput, rigor: resolution.rigorKey, complexity, formation, promptText, model: dispatchModel || rawModel, modelSource: resolution.source, projectPath, diagnoseArm });
 
   // TASK_2032: mirror headless.js's formation-path auto-activation (~L272-290)
   // on the subagent path — every gate/guard above has passed and this function
@@ -1395,6 +1433,7 @@ async function getSubagentDispatchParams(options) {
     promptText, taskId: taskInput, formation, skill, dispatchMode, effectiveMode: 'subagent',
     ...(isCodex ? { harness: 'codex', cwd: crossWorktree ? crossWorktree.worktreePath : null, worktreePath: crossWorktree ? crossWorktree.worktreePath : null } : {}),
     modelTranslation, isolation, ...(agentParams ? { agentParams } : {}), ...(executor ? { executor } : {}), rigor: resolution.rigorKey, complexity, modelSource: resolution.source,
+    ...(diagnoseArm ? { diagnoseArm } : {}),
     ...(dryRun ? { dryRun: true } : {}),
   };
 }
@@ -1445,4 +1484,4 @@ function setupSubagentCrossProjectWorktree(projectPath, taskInput) {
   };
 }
 
-module.exports = { resolveDispatchModelForRigor, translateModelForAgentTool, DEFAULT_DISPATCH_MODEL, getSubagentDispatchParams, checkDispatchScopeGate, releaseDispatchLock, resolveDispatchIsolation, _getProvenSessionId, _getOwnConversationId, _isOwnClaimMarker, _buildCortexContext: buildCortexContext };
+module.exports = { isBugCard, diagnoseArmFor, BUG_DIAGNOSIS_SECTION, appendDispatchPromptStats, resolveDispatchModelForRigor, translateModelForAgentTool, DEFAULT_DISPATCH_MODEL, getSubagentDispatchParams, checkDispatchScopeGate, releaseDispatchLock, resolveDispatchIsolation, _getProvenSessionId, _getOwnConversationId, _isOwnClaimMarker, _buildCortexContext: buildCortexContext };

package/core/.formation/tools/kenaz-stats.js

@@ -209,6 +209,37 @@ function lessonStats({ home, cwd, now, days }) {
   } catch (e) { return { source: src, note: `${NO_DATA} (${e.message})` }; }
 }
 
+/** TASK_2429: bug cards per diagnosis arm (dispatch_prompt_stats.jsonl diagnose_arm) joined with the git first-pass verdicts of dispatchStats. */
+function diagnoseAbStats({ cwd, now, days, dispatch }) {
+  const arms = {}; // card number -> arm (latest dispatch record wins)
+  try {
+    for (const l of fs.readFileSync(path.join(cwd, '.kenaz', 'specialist', 'dispatch_prompt_stats.jsonl'), 'utf8').split('\n')) {
+      let r; try { r = JSON.parse(l); } catch (_) { continue; }
+      const m = r && r.diagnose_arm && /^TASK_(\d+)$/i.exec(r.task_id || '');
+      if (m && (ms(r.ts) || 0) >= now - days * DAY) arms[m[1]] = r.diagnose_arm;
+    }
+  } catch (_) { /* no records */ }
+  const rework = new Set(((dispatch && dispatch.rework) || []).map((x) => x.card));
+  const merged = new Set((dispatch && dispatch.mergedCards) || []);
+  const out = {};
+  for (const arm of ['with', 'without']) {
+    const cards = Object.keys(arms).filter((n) => arms[n] === arm).map((n) => 'TASK_' + n);
+    const m = cards.filter((c) => merged.has(c));
+    out[arm] = { cards: cards.length, merged: m.length, firstPass: m.filter((c) => !rework.has(c)).length };
+  }
+  return out;
+}
+
+/** TASK_2428: glossary size/use, and first-pass of merged cards that got injected terms vs those that did not. */
+function glossaryStats({ cwd, now, days, cur }) {
+  const g = require('../../.specialist/tools/glossary.js').stats(cwd, now, days);
+  const inj = new Set(g.cards);
+  const merged = cur.mergedCards || [];
+  const rework = new Set((cur.rework || []).map((r) => r.card));
+  const rate = (ids) => (ids.length ? { rate: ids.filter((c) => !rework.has(c)).length / ids.length, merged: ids.length } : null);
+  return { ...g, withTerms: rate(merged.filter((c) => inj.has(c))), withoutTerms: rate(merged.filter((c) => !inj.has(c))) };
+}
+
 function selfImprovementStats({ home, cwd, now, days }) {
   const src = '<project>/.kenaz/specialist/correction-nudges.jsonl + lessons + .kenaz/knowledge/.harvested.json + git (this window vs the previous one)';
   try {
@@ -216,7 +247,8 @@ function selfImprovementStats({ home, cwd, now, days }) {
     const prev = dispatchStats({ repo: cwd, now: now - days * DAY, days, until: now - days * DAY });
     const pick = (d) => (d.firstPassRate == null ? null : { rate: d.firstPassRate, merged: d.merged });
     return { source: src, ...require('../../.specialist/tools/lessons-harvest.js').selfStats({ projectPath: cwd, home, now, days }),
-      firstPass: { window: pick(cur), previous: pick(prev) } };
+      firstPass: { window: pick(cur), previous: pick(prev) }, diagnoseAb: diagnoseAbStats({ cwd, now, days, dispatch: cur }),
+      glossary: glossaryStats({ cwd, now, days, cur }) };
   } catch (e) { return { source: src, note: `${NO_DATA} (${e.message})` }; }
 }
 
@@ -282,6 +314,13 @@ function render(s) {
         `  lessons by source: ${Object.entries(si.bySource).map(([k, v]) => `${k}=${v.lessons} (fired ${v.fired}, recurred before first fire ${v.recurBefore}, after ${v.recurAfter})`).join('; ') || 'none'}`,
         `  graduated ${si.graduated}; harvest items open ${si.harvestOpen}, recorded ${si.harvestRecorded}`,
         `  first-pass merge rate: this window ${r(si.firstPass.window)}, previous window ${r(si.firstPass.previous)}`);
+      if (si.diagnoseAb) {
+        const a = (x) => `${x.cards} bug cards, first-pass ${x.firstPass}/${x.merged}${x.merged ? ` (${(100 * x.firstPass / x.merged).toFixed(0)}%)` : ''}`;
+        L.push(`  Bug diagnosis A/B: with: ${a(si.diagnoseAb.with)}; without: ${a(si.diagnoseAb.without)}${Math.min(si.diagnoseAb.with.merged, si.diagnoseAb.without.merged) < 10 ? ' (below 10 merged per arm: keep collecting)' : ''}`);
+      }
+      const g = si.glossary;
+      if (g) L.push(`  glossary: ${g.terms} terms, ${g.added} added in window; ${g.injections} injections in ${g.cards.length} cards`,
+        `  first-pass merge rate, cards with injected terms ${r(g.withTerms)}, without ${r(g.withoutTerms)}`);
     }
   }
   return L.join('\n');
@@ -297,4 +336,4 @@ function main(argv, out = console.log, opts = {}) {
 }
 
 if (require.main === module) process.exit(main(process.argv.slice(2)));
-module.exports = { main, collect, peerStats, dispatchStats, git, fieldStats, alayaStats, render };
+module.exports = { diagnoseAbStats, main, collect, peerStats, dispatchStats, git, fieldStats, alayaStats, render };

package/core/.formation/tools/kenaz-stats.test.js

@@ -161,6 +161,23 @@ test('alaya: bija counts, activations, exported and seed imports in window; miss
   assert.ok(S.alayaStats({ home: path.join(tmp, 'nohome'), now: NOW, days: 14 }).note.startsWith('no data'));
 });
 
+test('diagnose A/B: bug cards and first-pass per arm from fake records (TASK_2429)', () => {
+  const cwd = path.join(tmp, 'ab-proj');
+  const f = path.join(cwd, '.kenaz', 'specialist', 'dispatch_prompt_stats.jsonl');
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  const rec = (id, arm, ts = iso(1)) => JSON.stringify({ ts, task_id: id, diagnose_arm: arm });
+  fs.writeFileSync(f, [rec('TASK_1', 'with'), rec('TASK_2', 'with'), rec('TASK_3', 'without'), rec('TASK_4', 'without'), rec('TASK_5', 'without'),
+    rec('TASK_6', 'with', iso(60)), JSON.stringify({ ts: iso(1), task_id: 'TASK_9', diagnose_arm: null }), 'not json'].join('\n') + '\n');
+  const dispatch = { mergedCards: ['TASK_1', 'TASK_2', 'TASK_3', 'TASK_4', 'TASK_9'], rework: [{ card: 'TASK_2' }, { card: 'TASK_3' }] };
+  const r = S.diagnoseAbStats({ cwd, now: NOW, days: 14, dispatch });
+  assert.deepStrictEqual(r.with, { cards: 2, merged: 2, firstPass: 1 });
+  assert.deepStrictEqual(r.without, { cards: 3, merged: 2, firstPass: 1 });
+  assert.deepStrictEqual(S.diagnoseAbStats({ cwd: path.join(tmp, 'none'), now: NOW, days: 14, dispatch }).with, { cards: 0, merged: 0, firstPass: 0 });
+  const text = S.render({ days: 14, peer: { source: '-', note: 'no data' }, dispatch: { source: '-', note: 'no data' }, fieldReports: { source: '-', note: 'no data' }, alaya: { source: '-', note: 'no data' },
+    selfImprovement: { source: '-', nudges: 0, converted: 0, bySource: {}, graduated: 0, harvestOpen: 0, harvestRecorded: 0, firstPass: {}, diagnoseAb: r } });
+  assert.ok(text.includes('Bug diagnosis A/B: with: 2 bug cards, first-pass 1/2 (50%); without: 3 bug cards, first-pass 1/2 (50%) (below 10 merged per arm: keep collecting)'), text);
+});
+
 test('main: --json parses and all four sections print; bad --days exits 2', () => {
   const lines = [];
   assert.strictEqual(S.main(['--json'], (m) => lines.push(m), { home: path.join(tmp, 'home2'), cwd: path.join(tmp, 'repo'), now: NOW }), 0);

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

@@ -170,6 +170,9 @@ function buildSubagentPrompt(skillDef, taskInput, taskData, options = {}) {
   // TASK_2409: lessons the user's Ansuz learned for this project (bounded; nothing is added when there are none).
   const learned = projectLessons(taskData, options);
   if (learned.facts.length) lines.push('## Project lessons', ...learned.facts, '');
+  // TASK_2428: project glossary entries for the terms this card uses (nothing is added when none occur).
+  const terms = projectTerms(taskData, options);
+  if (terms.length) lines.push('## Project terms', ...terms, '');
 
   lines.push('## Verify and report');
   // Ponytail A/B 2026-10-10: the arm without this line broke an existing fixture test it never ran.
@@ -190,15 +193,33 @@ function buildSubagentPrompt(skillDef, taskInput, taskData, options = {}) {
   return lines.join('\n');
 }
 
+// Same-project dispatch passes no --project-path (only cross-project does), so the project whose lessons and
+// glossary apply is the Kenaz project around the cwd. Before this fallback, a plain dispatch injected neither
+// (measured 2026-10-12: 0 checks without --project-path, 3 with it, same card).
+function lessonProject(options) {
+  if (options.projectPath) return options.projectPath;
+  try { return require('../../.claude/hooks/_project-guard').findProjectRoot(process.cwd()); } catch { return null; }
+}
+
 function projectLessons(taskData, options) {
   const none = { facts: [], checks: [] };
-  if (!options.projectPath) return none;
+  const projectPath = lessonProject(options);
+  if (!projectPath) return none;
   try {
     const parsed = typeof taskData === 'string' ? JSON.parse(taskData) : taskData;
-    return require('../../.specialist/tools/lessons').dispatchLessons(options.projectPath, (parsed && parsed.scope_paths) || []);
+    return require('../../.specialist/tools/lessons').dispatchLessons(projectPath, (parsed && parsed.scope_paths) || []);
   } catch { return none; }
 }
 
+function projectTerms(taskData, options) {
+  const projectPath = lessonProject(options);
+  if (!projectPath) return [];
+  try {
+    const parsed = typeof taskData === 'string' ? JSON.parse(taskData) : taskData;
+    return require('../../.specialist/tools/glossary').dispatchTerms(projectPath, parsed || {}).lines;
+  } catch { return []; }
+}
+
 function extractTaskId(taskData) {
   try {
     const parsed = typeof taskData === 'string' ? JSON.parse(taskData) : taskData;

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

@@ -10,6 +10,7 @@ const test = require('node:test');
 const assert = require('node:assert/strict');
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 
 const {
   buildPrompt,
@@ -310,7 +311,14 @@ test('TASK_2391: subagent prompt keeps card + commit rule + report, drops boiler
     requirements: ['REQ-ONE'], acceptance_criteria: ['AC-ONE'], technical_notes: ['NOTE-ONE'],
     complexity: 'complex', rigor: 'high',
   };
-  const body = buildPrompt(loadDoSkill(), 'TASK_9001', JSON.stringify(card), { isSubagent: true, taskId: 'TASK_9001' });
+  // Built outside any Kenaz project: this measures the template, not the repo's own lessons/glossary
+  // (a dispatch without --project-path injects the cwd project's, see lessonProject in prompt.js).
+  const was = process.cwd();
+  let body;
+  try {
+    process.chdir(fs.mkdtempSync(path.join(os.tmpdir(), 'p2391-')));
+    body = buildPrompt(loadDoSkill(), 'TASK_9001', JSON.stringify(card), { isSubagent: true, taskId: 'TASK_9001' });
+  } finally { process.chdir(was); }
   for (const must of ['REQ-ONE', 'AC-ONE', 'NOTE-ONE', 'src/a.js', '--no-verify -m "[TASK_9001] task completed"', '<= 20 lines', 'commit sha', 'did not verify']) {
     assert.ok(body.includes(must), `missing: ${must}`);
   }

package/core/.kenaz/GLOSSARY.md

@@ -0,0 +1,7 @@
+# Glossary
+
+## Ansuz
+Kenaz's orchestrator persona: understands the request, does small fixes itself, dispatches cards to subagents, verifies on the real path, merges.
+
+## Yggdrasil
+Kenaz's multi-node collaboration: a shared room (team key ygk_...) on the relay where nodes exchange peer mail and task replicas.

package/core/.specialist/Ansuz/RULES.md

@@ -106,3 +106,6 @@ REA (github.com/morluto/rea, MCP server `rea`) is optional and user-installed; t
 ## Code navigation
 Grep/Glob for text; kenaz_lsp_definition / kenaz_lsp_callers / kenaz_lsp_references for symbols.
 The memory system (synapse/hippocampus/cortex/alaya) is frozen since 2026-10-10: do not call it; lessons go to the native memory files.
+
+## Project glossary (TASK_2428)
+When the user defines or corrects a project term, or a term is ambiguous and the user settles it, record it with `kenaz glossary add "<term>" --means "<meaning>" [--not <x>] [--see <ref>]` (on an npm install: through core-resolve.js, like lessons). Read `.kenaz/GLOSSARY.md` before asking the user what a term means. Dispatch prompts get only the entries whose term the card mentions; benefit is measured in `kenaz stats` and judged under the rule in dev/research/self-improvement/DESIGN.md.

package/core/.specialist/tools/__tests__/task-2428-glossary.test.js

@@ -0,0 +1,126 @@
+'use strict';
+// TASK_2428: project glossary. Temp projects and temp homes only.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const g = require('../glossary');
+const { buildPrompt } = require('../../../.formation/tools/prompt');
+
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+const proj = () => fs.mkdtempSync(path.join(os.tmpdir(), 'k2428-'));
+const skill = { name: 'dev', formation: 'unit' };
+const prompt = (p, card) => buildPrompt(skill, 'do it', JSON.stringify(card), { projectPath: p, isSubagent: true, taskId: card.id });
+const usage = (p) => { try { return fs.readFileSync(path.join(p, '.kenaz', 'specialist', 'glossary-usage.jsonl'), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l)).filter((r) => r.terms); } catch { return []; } };
+
+test('glossary: add / replace (case-insensitive) / list / rm, file created lazily', () => {
+  const p = proj();
+  assert.equal(fs.existsSync(path.join(p, '.kenaz', 'GLOSSARY.md')), false);
+  assert.equal(g.add(p, 'Lane A', 'the fast path', { not: 'lane B', see: 'ADR-3' }).ok, true);
+  assert.equal(g.add(p, 'lane a', 'the first lane').replaced, true);
+  const t = g.readTerms(p);
+  assert.equal(t.length, 1);
+  assert.equal(t[0].means[0], 'the first lane');
+  assert.equal(g.rm(p, 'LANE A').ok, true);
+  assert.equal(g.readTerms(p).length, 0);
+  assert.equal(g.rm(p, 'nope').ok, false);
+});
+
+test('glossary: 60-term cap refuses a new term but still replaces an existing one', () => {
+  const p = proj();
+  for (let i = 0; i < 60; i++) assert.equal(g.add(p, `T${i}`, 'm').ok, true);
+  const r = g.add(p, 'T60', 'm');
+  assert.equal(r.ok, false);
+  assert.match(r.message, /full \(60 terms\)/);
+  assert.equal(g.add(p, 't3', 'new').ok, true);
+  assert.equal(g.readTerms(p).length, 60);
+});
+
+test('glossary: boot line only with terms', () => {
+  const p = proj();
+  const boot = () => spawnSync(process.execPath, [path.join(ROOT, '.specialist', 'tools', 'ansuz-boot-fast.js'), '--project-path=' + p, '--conversation-id=s2428', '--mcp-base-url=http://127.0.0.1:1'],
+    { encoding: 'utf8', cwd: p, env: { ...process.env, CLAUDE_PROJECT_DIR: p }, timeout: 30000 }).stdout;
+  assert.doesNotMatch(boot(), /\[glossary\]/);
+  g.add(p, 'Prism', 'the renderer');
+  assert.match(boot(), /\[glossary\] 1 terms \(\.kenaz\/GLOSSARY\.md\)/);
+});
+
+test('dispatch: only terms the card mentions are injected; a card without terms gets no section; logged', () => {
+  const p = proj();
+  g.add(p, 'Prism', 'the renderer');
+  g.add(p, 'NGO', 'non-profit partner');
+  assert.doesNotMatch(prompt(p, { id: 'TASK_1', title: 'fix typo', description: 'plain' }), /## Project terms/);
+  assert.equal(usage(p).length, 0);
+  const out = prompt(p, { id: 'TASK_2', title: 'Update prism output', requirements: ['keep it fast'] });
+  assert.match(out, /## Project terms\n- Prism: the renderer/);
+  assert.doesNotMatch(out, /NGO: non-profit/);
+  assert.doesNotMatch(prompt(p, { id: 'TASK_3', title: 'prisms and ngos' }), /## Project terms/, 'whole word only');
+  const u = usage(p);
+  assert.equal(u.length, 1);
+  assert.deepEqual([u[0].task, u[0].terms], ['TASK_2', ['Prism']]);
+  assert.match(prompt(p, { id: 'TASK_4', title: 'x', acceptance_criteria: ['NGO flow works'] }), /NGO: non-profit/);
+});
+
+test('dispatch: at most 8 entries and 800 bytes; CJK term matches by substring', () => {
+  const p = proj();
+  const names = Array.from({ length: 12 }, (_, i) => `Term${i}`);
+  for (const n of names) g.add(p, n, 'short');
+  const r = g.dispatchTerms(p, { id: 'TASK_5', title: names.join(' ') });
+  assert.equal(r.terms.length, 8);
+  const q = proj();
+  for (const n of names) g.add(q, n, 'x'.repeat(200));
+  const r2 = g.dispatchTerms(q, { id: 'TASK_6', title: names.join(' ') });
+  assert.ok(Buffer.byteLength(r2.lines.join('\n')) <= 800);
+  assert.ok(r2.terms.length >= 1 && r2.terms.length < 8);
+  const c = proj();
+  g.add(c, '通道', '資料傳輸路徑');
+  assert.deepEqual(g.dispatchTerms(c, { id: 'TASK_7', description: '修正通道逾時' }).terms, ['通道']);
+});
+
+test('stats: terms added, injections and cards in the window', () => {
+  const p = proj();
+  g.add(p, 'Prism', 'r');
+  g.dispatchTerms(p, { id: 'TASK_9', title: 'prism' });
+  const s = g.stats(p, Date.now() + 1000, 30);
+  assert.deepEqual([s.terms, s.added, s.injections, s.cards], [1, 1, 1, ['TASK_9']]);
+  assert.equal(g.stats(p, Date.now() + 1000 + 40 * 86400000, 30).injections, 0);
+});
+
+test('cli: kenaz glossary through packages/kenaz/lib/cli.js with a staged core', () => {
+  const home = proj();
+  const p = proj();
+  const tools = path.join(home, '.kenaz', 'core', '.specialist', 'tools');
+  fs.mkdirSync(tools, { recursive: true });
+  fs.copyFileSync(path.join(ROOT, '.specialist', 'tools', 'glossary.js'), path.join(tools, 'glossary.js'));
+  const cli = path.join(ROOT, 'packages', 'kenaz', 'bin', 'kenaz.js');
+  const run = (...a) => spawnSync(process.execPath, [cli, 'glossary', ...a, '--project-path', p], { encoding: 'utf8', env: { ...process.env, HOME: home, USERPROFILE: home } });
+  let r = run('add', 'Lane A', '--means', 'fast path', '--not', 'lane B');
+  assert.equal(r.status, 0, r.stdout + r.stderr);
+  r = run('list');
+  assert.match(r.stdout, /Lane A: fast path \(not lane B\)/);
+  assert.match(fs.readFileSync(path.join(p, '.kenaz', 'GLOSSARY.md'), 'utf8'), /## Lane A/);
+  assert.equal(run('rm', 'lane a').status, 0);
+});
+
+test('same-project dispatch (no projectPath) still injects terms: the Kenaz project around the cwd applies', () => {
+  const p = proj();
+  fs.mkdirSync(path.join(p, '.kenaz'), { recursive: true });
+  fs.writeFileSync(path.join(p, '.kenaz', 'project.yaml'), 'name: t\n');
+  g.add(p, 'Prism', 'the replacement network layer');
+  fs.mkdirSync(path.join(p, 'src'));
+  const was = process.cwd();
+  try {
+    process.chdir(path.join(p, 'src'));
+    const card = { id: 'TASK_9', title: 'Port the Prism handshake' };
+    const out = buildPrompt(skill, 'do it', JSON.stringify(card), { isSubagent: true, taskId: card.id });
+    assert.match(out, /## Project terms\n- Prism: the replacement network layer/);
+  } finally { process.chdir(was); }
+  // control: outside any Kenaz project nothing is injected
+  const bare = proj();
+  try {
+    process.chdir(bare);
+    assert.doesNotMatch(buildPrompt(skill, 'do it', JSON.stringify({ id: 'TASK_9', title: 'Port the Prism handshake' }), { isSubagent: true, taskId: 'TASK_9' }), /## Project terms/);
+  } finally { process.chdir(was); }
+});

package/core/.specialist/tools/ansuz-boot-fast.js

@@ -1027,6 +1027,7 @@ async function main() {
   if (landedLine) lines.push(landedLine);
   try { const rea = require('./rea-detect'); const l = rea.reaBannerLine(rea.detectRea({ projectPath: BASE })); if (l) lines.push(l); } catch { /* optional */ }
   try { for (const l of require('./lessons').bannerLines(BASE)) lines.push(l); } catch { /* optional */ }
+  try { for (const l of require('./glossary').bannerLines(BASE)) lines.push(l); } catch { /* optional */ }
   const peerLines = await fetchPendingPeerLines(mcpBase, WISH_TIMEOUT_MS, IS_PINNED ? BASE : process.env.CLAUDE_PROJECT_DIR || process.cwd());
   for (const l of peerLines) lines.push(l);
   lines.push('（boot 完成：' + (findHandoffDocs(BASE).length ? '先讀 → 標記的 handoff 全文，再' : '') + '依 Open cards 提議程；小修正直接做，中型工作開卡派工）');

package/core/.specialist/tools/glossary.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Project glossary (TASK_2428): each project keeps its own terms so agents use its language
+ * instead of re-deriving it. Idea adapted from the domain-modeling skill of
+ * github.com/mattpocock/skills (MIT license, Matt Pocock).
+ *
+ * File: <project>/.kenaz/GLOSSARY.md (a root GLOSSARY.md is also read). Format per term:
+ *   ## <Term>
+ *   1-3 lines of meaning
+ *   Not: <confusable term>
+ *   See: <ADR/link>
+ * Created lazily on the first term. Injected into dispatch prompts only for terms the card mentions.
+ * <project>/.kenaz/specialist/glossary-usage.jsonl: one line per injection {ts, task, terms}
+ * and per added term {ts, added} (read by kenaz stats).
+ *
+ *   kenaz glossary add "<term>" --means "<meaning>" [--not <x>] [--see <ref>] [--project-path <dir>]
+ *   kenaz glossary list | rm <term>
+ */
+const fs = require('fs');
+const path = require('path');
+
+const MAX_TERMS = 60;
+const INJECT_MAX_ENTRIES = 8;
+const INJECT_MAX_BYTES = 800;
+
+const fileOf = (p) => path.join(p, '.kenaz', 'GLOSSARY.md');
+const logOf = (p) => path.join(p, '.kenaz', 'specialist', 'glossary-usage.jsonl');
+const key = (t) => String(t).trim().toLowerCase();
+
+function parse(text) {
+  const terms = [];
+  let cur = null;
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const h = /^##\s+(.+?)\s*$/.exec(line);
+    if (h) { cur = { term: h[1], means: [], not: '', see: '' }; terms.push(cur); continue; }
+    if (!cur) continue;
+    const n = /^Not:\s*(.*)$/.exec(line);
+    const s = /^See:\s*(.*)$/.exec(line);
+    if (n) cur.not = n[1].trim();
+    else if (s) cur.see = s[1].trim();
+    else if (line.trim()) cur.means.push(line.trim());
+  }
+  return terms;
+}
+
+function render(terms) {
+  return '# Glossary\n\n' + terms.map((t) => `## ${t.term}\n${t.means.join('\n')}\n${t.not ? `Not: ${t.not}\n` : ''}${t.see ? `See: ${t.see}\n` : ''}`).join('\n');
+}
+
+function log(projectPath, row) {
+  try {
+    fs.mkdirSync(path.dirname(logOf(projectPath)), { recursive: true });
+    fs.appendFileSync(logOf(projectPath), JSON.stringify(row) + '\n');
+  } catch { /* measurement only */ }
+}
+
+/** Terms from .kenaz/GLOSSARY.md first, then a root GLOSSARY.md (the .kenaz one wins on a duplicate term). */
+function readTerms(projectPath) {
+  const out = [];
+  const seen = new Set();
+  for (const f of [fileOf(projectPath), path.join(projectPath, 'GLOSSARY.md')]) {
+    let txt = '';
+    try { txt = fs.readFileSync(f, 'utf8'); } catch { continue; }
+    for (const t of parse(txt)) if (!seen.has(key(t.term))) { seen.add(key(t.term)); out.push(t); }
+  }
+  return out;
+}
+
+function add(projectPath, term, means, extra = {}) {
+  term = String(term || '').trim();
+  means = String(means || '').trim();
+  if (!term || !means) return { ok: false, message: 'usage: kenaz glossary add "<term>" --means "<meaning>" [--not <x>] [--see <ref>]' };
+  let own = [];
+  try { own = parse(fs.readFileSync(fileOf(projectPath), 'utf8')); } catch { /* created lazily */ }
+  const entry = { term, means: means.split(/\r?\n/).slice(0, 3), not: extra.not || '', see: extra.see || '' };
+  const i = own.findIndex((t) => key(t.term) === key(term));
+  if (i < 0 && own.length >= MAX_TERMS) return { ok: false, message: `glossary is full (${MAX_TERMS} terms): remove one with \`kenaz glossary rm <term>\` first` };
+  if (i >= 0) own[i] = entry; else own.push(entry);
+  fs.mkdirSync(path.dirname(fileOf(projectPath)), { recursive: true });
+  fs.writeFileSync(fileOf(projectPath), render(own));
+  if (i < 0) log(projectPath, { ts: new Date().toISOString(), added: term });
+  return { ok: true, replaced: i >= 0, count: own.length };
+}
+
+function rm(projectPath, term) {
+  let own = [];
+  try { own = parse(fs.readFileSync(fileOf(projectPath), 'utf8')); } catch { return { ok: false }; }
+  const left = own.filter((t) => key(t.term) !== key(term));
+  if (left.length === own.length) return { ok: false };
+  fs.writeFileSync(fileOf(projectPath), render(left));
+  return { ok: true };
+}
+
+const CJK = /[　-鿿가-힯＀-￯]/;
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Whole word, case-insensitive; CJK terms by substring (no word boundaries in CJK text). */
+function mentions(text, term) {
+  if (CJK.test(term)) return text.toLowerCase().includes(term.toLowerCase());
+  return new RegExp(`(^|[^\\p{L}\\p{N}_])${esc(term)}(?![\\p{L}\\p{N}_])`, 'iu').test(text);
+}
+
+function cardText(card) {
+  const list = (v) => (Array.isArray(v) ? v.map((x) => (typeof x === 'string' ? x : JSON.stringify(x))).join('\n') : String(v || ''));
+  return [card.title, card.description, list(card.requirements), list(card.acceptance_criteria)].filter(Boolean).join('\n');
+}
+
+/** Entries (<= 8, <= 800 bytes) for the glossary terms that occur in the card; logs the injection. */
+function dispatchTerms(projectPath, card, now = Date.now()) {
+  const none = { lines: [], terms: [] };
+  try {
+    const text = cardText(card || {});
+    const lines = [];
+    const used = [];
+    let bytes = 0;
+    for (const t of readTerms(projectPath)) {
+      if (used.length >= INJECT_MAX_ENTRIES || !mentions(text, t.term)) continue;
+      const line = `- ${t.term}: ${t.means.join(' ')}${t.not ? ` (not ${t.not})` : ''}${t.see ? ` [see ${t.see}]` : ''}`;
+      if (bytes + Buffer.byteLength(line) + 1 > INJECT_MAX_BYTES) break;
+      bytes += Buffer.byteLength(line) + 1;
+      lines.push(line);
+      used.push(t.term);
+    }
+    if (!used.length) return none;
+    log(projectPath, { ts: new Date(now).toISOString(), task: (card && card.id) || null, terms: used });
+    return { lines, terms: used };
+  } catch { return none; }
+}
+
+function bannerLines(projectPath) {
+  const n = readTerms(projectPath).length;
+  return n ? [`[glossary] ${n} terms (.kenaz/GLOSSARY.md)`] : [];
+}
+
+/** For kenaz stats: terms now, terms added / injections / cards with injections inside the window. */
+function stats(projectPath, now, days) {
+  const since = now - days * 86400000;
+  const rows = [];
+  try {
+    for (const l of fs.readFileSync(logOf(projectPath), 'utf8').split('\n')) {
+      if (!l.trim()) continue;
+      try { const r = JSON.parse(l); if (Date.parse(r.ts) >= since && Date.parse(r.ts) <= now) rows.push(r); } catch { /* skip bad line */ }
+    }
+  } catch { /* no log yet */ }
+  const inj = rows.filter((r) => r.terms);
+  return {
+    terms: readTerms(projectPath).length,
+    added: rows.filter((r) => r.added).length,
+    injections: inj.length,
+    cards: [...new Set(inj.map((r) => r.task).filter(Boolean))],
+  };
+}
+
+function main(argv, out = console.log) {
+  const args = argv.slice();
+  const take = (flag) => { const i = args.indexOf(flag); if (i < 0) return undefined; const v = args[i + 1]; args.splice(i, 2); return v; };
+  const projectPath = path.resolve(take('--project-path') || process.cwd());
+  const means = take('--means');
+  const not = take('--not');
+  const see = take('--see');
+  const [cmd, ...rest] = args;
+  if (cmd === 'add') {
+    const r = add(projectPath, rest.join(' '), means, { not, see });
+    out(r.ok ? `${r.replaced ? 'replaced' : 'added'} "${rest.join(' ')}" (${r.count} terms)` : r.message);
+    return r.ok ? 0 : 1;
+  }
+  if (cmd === 'rm' && rest.length) {
+    const r = rm(projectPath, rest.join(' '));
+    out(r.ok ? `removed "${rest.join(' ')}"` : `no such term: ${rest.join(' ')}`);
+    return r.ok ? 0 : 1;
+  }
+  if (cmd === 'list') {
+    const t = readTerms(projectPath);
+    if (!t.length) out('no glossary terms');
+    else for (const x of t) out(`${x.term}: ${x.means.join(' ')}${x.not ? ` (not ${x.not})` : ''}${x.see ? ` [see ${x.see}]` : ''}`);
+    return 0;
+  }
+  out('usage: kenaz glossary <add "<term>" --means "<meaning>" [--not <x>] [--see <ref>] | list | rm <term>> [--project-path <dir>]');
+  return 2;
+}
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));
+module.exports = { main, add, rm, readTerms, dispatchTerms, bannerLines, stats, parse, mentions };

package/core/.specialist/tools/lessons-harvest.js

@@ -168,7 +168,11 @@ function openCount(projectPath, now = Date.now(), o = {}) {
   try { c = JSON.parse(fs.readFileSync(cacheFile(projectPath), 'utf8')); } catch (_) { /* no cache */ }
   if (c && now - c.t < CACHE_TTL_MS) return c.n;
   if (o.sync) return writeCount(projectPath, now);
-  (o.refresh || ((p) => require('child_process').spawn(process.execPath, [__filename, '--refresh-cache', p], { detached: true, stdio: 'ignore', windowsHide: true }).unref()))(projectPath);
+  // No git, no history to scan: never start a background process (its git calls hold the folder open on Windows).
+  if (!fs.existsSync(path.join(root(projectPath), '.git'))) return c ? c.n : 0;
+  // cwd = home, not the project: on Windows a process whose cwd is the project locks that folder for the ~20 s
+  // the scan takes (no delete/rename; broke two boot tests' temp-dir cleanup with EPERM). The path is absolute.
+  (o.refresh || ((p) => require('child_process').spawn(process.execPath, [__filename, '--refresh-cache', path.resolve(p)], { cwd: require('os').homedir(), detached: true, stdio: 'ignore', windowsHide: true }).unref()))(projectPath);
   return c ? c.n : 0;
 }
 

package/core/KENAZ_CORE_VERSION

@@ -1 +1 @@
-0.3.13
+0.3.15

package/core/plugins/kenaz/commands/Ansuz.md

@@ -1,52 +1,43 @@
 ## 專案路徑
-ARGUMENTS 含 `[專案: X]` 或 `--project-path X` → PROJECT_PATH = X，下方 boot 腳本與 task-api / dispatch 呼叫都附加 `--project-path "<PROJECT_PATH>"`。沒有就留空，什麼都不加。
+ARGUMENTS 含 `[專案: X]` 或 `--project-path X` → PROJECT_PATH = X，下方 boot、task-api、dispatch 都附加 `--project-path "<PROJECT_PATH>"`。沒有就不加。
 
 # Ansuz boot
 
-你是 **Ansuz**，Kenaz 的 orchestrator：理解需求，依情境決定自己動手或拆任務派給 subagent，合併前在真實路徑上驗證，然後回報。先查現況、確認 scope，再動手。
-
-## Boot（一次 Bash，無其他儀式）
-1. Turn Context 若有 `[session] session_id=<id>`，記住 `<id>`。
-2. 執行 `node "${CLAUDE_PLUGIN_ROOT}/hooks/core-resolve.js" .specialist/tools/ansuz-boot-fast.js`（有 `<id>` 加 `--conversation-id="<id>"`；有 PROJECT_PATH 加 `--project-path`）。
-3. banner 有 `📎 Project handoff` 時，**先用 Read 讀 → 標記的那份全文**（不用問用戶），以它為準接續上一個 session。
-4. 把 banner 轉述給用戶（Bash 輸出在 UI 會摺疊），依 handoff 的 R 段與 `📋 Open cards` 直接提出議程。
-
-## 每件工作的做法
-- **自己做**：小而明確的修正（約 30 行內、單一檔案或少數檔案）→ 直接改，跑最近的測試，提交。
-- **開卡派工**：中型、可平行、或高風險路徑的工作：
-  1. 用 `kenaz_task_create` 開卡（`projectPath` = 目前專案；寫清楚 requirements、acceptance criteria、scope paths）。查卡、改狀態用 `kenaz_task_list` / `kenaz_task_get` / `kenaz_task_update`。
-  2. 產生派工內容：`node "${CLAUDE_PLUGIN_ROOT}/hooks/core-resolve.js" .formation/tools/dispatch.js --skill=do --task=TASK_XXX --dispatch-mode=subagent`（有 PROJECT_PATH 加 `--project-path`）。把輸出 JSON 的 `promptText` 交給 subagent，`agentParams` 照用（模型不要自己換）。
-  3. subagent 在 worktree 裡改完並 commit；你驗證後合併。
-     若輸出是 `executor` 區塊（模型為 `codex:<id>` / `deepseek:<model>`，無 agentParams）：用 Bash run_in_background 執行 `executor.command`，等完成通知，讀 `executor.resultFile`（ok、commits；`no commits` = 失敗），再照常驗證並合併 `executor.branchName`。
-- 開卡前先確認 scope 與驗收條件對準真正的問題，不要照著錯的假設派工。
-
-## 驗證（合併前一定做，強度跟風險相稱）
-- 走**真實路徑**：實際執行會被使用者用到的那條路（真的安裝、真的啟動、真的收發訊息），不只看單元測試。
-- 有**對照組**：證明測試在舊程式上會失敗，或修改前後結果不同。
-- subagent 回報「未驗證」的項目，由你補驗或明講仍未驗證。
-- 合併：`git merge` 後跑相關測試（或 `node "${CLAUDE_PLUGIN_ROOT}/hooks/core-resolve.js" .specialist/Ansuz/tools/verify-and-land.js`），用這個專案自己的測試指令。
-
-## 交接（handoff，ISBAR）
-用戶說交接／暫停／換 session、context 快滿、或結束時仍有未完成的工作 → 寫交接：
-1. `node "${CLAUDE_PLUGIN_ROOT}/hooks/core-resolve.js" .specialist/tools/handoff-doc.js new --topic "<主題>" --session <id>`（有 PROJECT_PATH 加 `--project-path`），建立 `<專案>/.kenaz/handoffs/<日期時間>-<主題>.md`，I 段已自動填好。
-2. 用 Edit 填 S（現況）、B（背景：用戶決定原話、相關卡與 commit）、A（已驗證／未驗證／風險）、R（下一個 session 第一步、待用戶決定的事）。寫給「沒看過這段對話的人」，不寫空泛句。
-3. 一份交接一個檔，不覆寫舊的；下一個 session 的 boot 會自動列出並讀最新那份。
+你是 **Ansuz**，Kenaz 的 orchestrator：理解需求，自己動手或拆卡派給 subagent，合併前在真實路徑上驗證，然後回報。先查現況、確認 scope，再動手。
+
+## Boot（一次 Bash）
+1. Turn Context 有 `[session] session_id=<id>` 就記住 `<id>`。
+2. `node "${CLAUDE_PLUGIN_ROOT}/hooks/core-resolve.js" .specialist/tools/ansuz-boot-fast.js`（有 `<id>` 加 `--conversation-id="<id>"`；有 PROJECT_PATH 加 `--project-path`）。
+3. banner 有 `📎 Project handoff`：先 Read → 標記的那份全文，以它接續。
+4. 轉述 banner，依 handoff 的 R 段與 `📋 Open cards` 提出議程。`[lessons]`、`[learn]`、`[glossary]` 行照 RULES.md 的 Lessons / Project glossary 處理。
+
+## 工作方式
+- **自己做**：約 30 行內的小修正 → 直接改，跑最近的測試，提交。
+- **開卡派工**（中型、可平行、高風險）：`kenaz_task_create` 開卡（requirements、acceptance criteria、scope paths）→ `node "${CLAUDE_PLUGIN_ROOT}/hooks/core-resolve.js" .formation/tools/dispatch.js --skill=do --task=TASK_XXX --dispatch-mode=subagent` → `promptText` 給 subagent、`agentParams` 照用（不換模型）；輸出是 `executor` 區塊時照 RULES.md 的 Dispatch 執行。subagent 在 worktree commit，你驗證後合併。
+- 開卡前確認 scope 與驗收條件對準真正的問題。
+
+## 驗證（合併前，強度跟風險相稱）
+- **真實路徑**：實際跑使用者會走的路，不只看單元測試。
+- **對照組**：證明測試在舊程式上會失敗。
+- subagent 的「未驗證」由你補驗或明講。合併後跑相關測試（含被改檔案的既有測試）。
+
+## 交接
+用戶說交接／暫停、context 快滿、或結束時有未完成工作：`node "${CLAUDE_PLUGIN_ROOT}/hooks/core-resolve.js" .specialist/tools/handoff-doc.js new --topic "<主題>" --session <id>`，再填 S/B/A/R（見 RULES.md 的 Handoff）。
 
 ## 回報與提問
-- 一律用用戶的語言（中文訊息 → 中文回覆，含提問選項）。
-- 需要用戶決定時用 `AskUserQuestion`（2-4 個選項、建議的放第一個），不要在文字裡列選項等回覆；有證據能自己判斷的事不問。
-- 回報說清楚：做了什麼、怎麼驗證的、還有什麼沒驗證或需要用戶決定。不說「應該可以」。
+- 用用戶的語言（中文訊息 → 中文，含提問選項）。
+- 需要用戶決定時用 `AskUserQuestion`（2-4 選項、建議的放第一），有證據能自己判斷的不問。
+- 說清楚做了什麼、怎麼驗證、什麼沒驗證或要用戶決定。不說「應該可以」。
 
-## Kenaz 本身出問題時：先回報再繞過
-Kenaz 的工具、hook、安裝、peer、派工擋住或拖慢工作時，**繞過之前**先 `kenaz_wish_create`（`projectPath`；`scope` kenaz|project；`wish_type` bug|feature|question；`content` = 一行重現 + 預期 vs 實際 + `npx kenaz doctor` 版本 + session id，不貼金鑰）。一個問題報一次，報完照常完成工作並告訴用戶；用戶說「回報這個問題」也用它（`source`=`user`）。
+## Kenaz 本身出問題：先回報再繞過
+繞過之前先 `kenaz_wish_create`（`scope` kenaz|project；`wish_type` bug|feature|question；一行重現 + 預期 vs 實際 + `npx kenaz doctor` 版本 + session id，不貼金鑰），報完照常完成工作。
 
 ## 自主模式
-用戶明確授權自主時：立刻 `node "${CLAUDE_PLUGIN_ROOT}/hooks/core-resolve.js" .specialist/tools/autonomy.js grant --session <id> --scope "<範圍>"`，讀 RULES.md 的 Autonomy。之後結束回合會被 Stop hook 擋回：自己決定、一路做完，不在結尾問「要我…嗎？」；只有必要停點才 `pause`，做完才 `done`。
+用戶明確授權自主時：`node "${CLAUDE_PLUGIN_ROOT}/hooks/core-resolve.js" .specialist/tools/autonomy.js grant --session <id> --scope "<範圍>"`，讀 RULES.md 的 Autonomy；只在必要停點 `pause`，做完 `done`。
 
-## 參考產品（REA）與學習教訓
-- banner `[rea]` 行：用戶提到參考產品時，有 REA 就提議分析，沒有就提示一次 `npx rea-agents setup`（範圍見 RULES.md 的 REA）。
-- 用戶糾正/重複指示、推翻決定、或驗證抓到失敗時，自動寫教訓並在回報點名一行：`node "${CLAUDE_PLUGIN_ROOT}/hooks/core-resolve.js" .specialist/tools/lessons.js add --scope user|project --type pref|fact|pitfall|check --text "..."`（規則見 RULES.md 的 Lessons）。
-- banner 出現 `[lessons] N to graduate`：跑 `kenaz learn review`，提議把排第一的教訓改成代碼（測試、hook 檢查或專案 CLAUDE.md/AGENTS.md 規則，這是首選結果）；糾正若與既有教訓相符屬於重複（recurrence），不是新教訓（`add` 會自動累加）。
-- banner 出現 `[learn] N history items to review`：跑 `kenaz learn review`，每個歷史項目（返工、executor 失敗、blocked 卡、handoff 風險行）有現成的 `kenaz learn add ... --source harvest:<id>`，值得記的補上 why 後執行，其餘忽略；指標建議（各 rigor 一次過率、返工最多的檔案）只建議給用戶，不自行套用。詳見 RULES.md。
+## 教訓、詞彙、參考產品
+- 用戶糾正、推翻決定、或驗證抓到失敗：`node "${CLAUDE_PLUGIN_ROOT}/hooks/core-resolve.js" .specialist/tools/lessons.js add --scope user|project --type pref|fact|pitfall|check --text "..."`，回報點名一行。
+- 用戶定義或拍板專案術語：`kenaz glossary add "<term>" --means "..."`；問術語前先讀 `.kenaz/GLOSSARY.md`。
+- `[rea]` 行、教訓生命週期與歷程收割：見 RULES.md（REA、Lessons）。
 
-需要更多規則時（授權自主、派工前、合併前、參考產品、寫教訓）讀 `${CLAUDE_PLUGIN_ROOT}/../../.specialist/Ansuz/RULES.md`。
+需要更多規則時（自主、派工、合併、交接、教訓、REA）讀 `${CLAUDE_PLUGIN_ROOT}/../../.specialist/Ansuz/RULES.md`。

package/lib/cli.js

@@ -14,7 +14,7 @@ const dash = require('./dashboard');
 const PKG_ROOT = path.resolve(__dirname, '..');
 const PKG = require('../package.json');
 const MIN_NODE = 18;
-const USAGE = 'usage: kenaz <install|uninstall|status|doctor|init|ygg join <key>|ygg create [--name N]|ygg status|ygg leave|alaya status|alaya register|subagent [set <id>|unset] [--rigor r]|launch --provider deepseek [--model id]|stats [--days N] [--json]|learn <add|list|rm|review|merge|graduate>> [--dry-run] [--home <dir>] [--no-service] [--no-claude] [--no-codex] [--keep-dashboard] [--server-bin <path>]';
+const USAGE = 'usage: kenaz <install|uninstall|status|doctor|init|ygg join <key>|ygg create [--name N]|ygg status|ygg leave|alaya status|alaya register|subagent [set <id>|unset] [--rigor r]|launch --provider deepseek [--model id]|stats [--days N] [--json]|learn <add|list|rm|review|merge|graduate>|glossary <add|list|rm>> [--dry-run] [--home <dir>] [--no-service] [--no-claude] [--no-codex] [--keep-dashboard] [--server-bin <path>]';
 
 function parseArgs(argv) {
   const o = { cmd: argv[0], flags: {} };
@@ -42,6 +42,7 @@ function coreModule(p, ...rel) {
 }
 const reaDetect = (p) => coreModule(p, '.specialist', 'tools', 'rea-detect.js');
 const lessons = (p) => coreModule(p, '.specialist', 'tools', 'lessons.js');
+const glossary = (p) => coreModule(p, '.specialist', 'tools', 'glossary.js');
 const dispatchModel = (p) => coreModule(p, '.formation', 'tools', 'dispatch-model.js');
 const providerLaunch = (p) => coreModule(p, '.formation', 'bifrost', 'provider-launch.js');
 const kenazStats = (p) => coreModule(p, '.formation', 'tools', 'kenaz-stats.js');
@@ -356,6 +357,11 @@ function run(argv, out = console.log, deps = {}) {
     if (!ks) { out('kenaz-core not installed: run `kenaz install`'); return 1; }
     return ks.main(argv.slice(1), out);
   }
+  if (argv[0] === 'glossary') {
+    const gl = glossary(paths(os.homedir()));
+    if (!gl) { out('kenaz-core not installed: run `kenaz install`'); return 1; }
+    return gl.main(argv.slice(1), out);
+  }
   if (argv[0] === 'learn') {
     const hi = argv.indexOf('--home');
     const lm = lessons(paths(hi >= 0 && argv[hi + 1] ? path.resolve(argv[hi + 1]) : os.homedir()));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kenaz",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "description": "Install Kenaz (plugin, hooks, kenaz-server) for Claude Code and Codex: npx kenaz install",
   "bin": {
     "kenaz": "bin/kenaz.js"
@@ -20,11 +20,11 @@
     "test": "node --test lib/cli.test.js"
   },
   "optionalDependencies": {
-    "@kenazai/server-darwin-arm64": "0.3.13",
-    "@kenazai/server-darwin-x64": "0.3.13",
-    "@kenazai/server-linux-arm64": "0.3.13",
-    "@kenazai/server-linux-x64": "0.3.13",
-    "@kenazai/server-win32-x64": "0.3.13"
+    "@kenazai/server-darwin-arm64": "0.3.15",
+    "@kenazai/server-darwin-x64": "0.3.15",
+    "@kenazai/server-linux-arm64": "0.3.15",
+    "@kenazai/server-linux-x64": "0.3.15",
+    "@kenazai/server-win32-x64": "0.3.15"
   },
   "license": "UNLICENSED",
   "repository": {