kenaz 0.0.0-stage → 0.3.2

package/core/.specialist/tests/runtime-discovery/tail-cli-project-path.test.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * tail-cli-project-path.test.js (TASK_1812)
+ *
+ * Contract: boot boundary invariant 1 (sigil_d3b8f855) for the two TAIL CLIs
+ * that touch .kenaz/ state:
+ *
+ *   .specialist/tools/lesson-guard.js
+ *   .specialist/tools/failure-detector.js
+ *
+ * Both must resolve their .kenaz/ path constants through the shared
+ * projectResolver (lib/project-resolver.js), with --project-path extracted
+ * BEFORE module-level path constants are computed (phase-gate.js paradigm).
+ *
+ * Assertions:
+ *   A. Backward-compat arm: no --project-path + unpinnable --session-id
+ *      -> .kenaz/ paths anchor on BASE_DIR (core), byte-identical to the
+ *         pre-TASK_1812 hard-coded behavior.
+ *   B. Project arm: --project-path=<tmp> -> .kenaz/ paths anchor on <tmp>,
+ *      while SYSTEM config (lesson_guards.yaml under .specialist/) stays on
+ *      BASE_DIR — guard definitions never move with the project.
+ *   C. Write-path arm (real CLI subprocess, real writes): with
+ *      --project-path=<tmp>, lesson-guard record-acted-on and
+ *      failure-detector run append their jsonl records under <tmp>/.kenaz/
+ *      and do NOT touch the core .kenaz jsonl files. Space-separated flag
+ *      form ("--project-path X") must not pollute positional args.
+ *
+ * Arms A/B probe module exports via `node -e` subprocesses so that the real
+ * module-level IIFE extraction is exercised (argv is set before require).
+ * Arm C goes through the actual CLI entry points (defect path, not a mock).
+ *
+ * Exit codes: 0 = all pass, 1 = one or more failures.
+ */
+
+'use strict';
+
+const fs     = require('fs');
+const os     = require('os');
+const path   = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const ROOT      = path.resolve(__dirname, '..', '..', '..');
+const TOOLS_DIR = path.join(ROOT, '.specialist', 'tools');
+const LESSON_GUARD    = path.join(TOOLS_DIR, 'lesson-guard.js');
+const FAIL_DETECTOR   = path.join(TOOLS_DIR, 'failure-detector.js');
+const GUARDS_YAML     = path.join(ROOT, '.specialist', 'Ansuz', 'guards', 'lesson_guards.yaml');
+const CORE_ACTED_ON   = path.join(ROOT, '.kenaz', 'specialist', 'lesson_guard_acted_on.jsonl');
+const CORE_SHADOW     = path.join(ROOT, '.kenaz', 'specialist', 'guard_detector_shadow.jsonl');
+
+function uid() { return crypto.randomBytes(4).toString('hex'); }
+function norm(p) { return p ? path.resolve(p).replace(/\\/g, '/') : null; }
+function readOrNull(p) { try { return fs.readFileSync(p, 'utf8'); } catch { return null; } }
+
+let passed = 0, failed = 0, skipped = 0;
+function check(name, ok, detail) {
+  if (ok) { passed++; console.log(`  PASS  ${name}`); }
+  else    { failed++; console.log(`  FAIL  ${name}${detail ? ' — ' + detail : ''}`); }
+}
+function skip(name, why) { skipped++; console.log(`  SKIP  ${name} — ${why}`); }
+
+// A --session-id that cannot exist in any pin file: forces the resolver past
+// the pin level deterministically, so arm A is stable even on machines with
+// live session pins.
+const NO_PIN_SID = `t1812-no-such-session-${uid()}`;
+
+// Probe cwd: a FRESH temp dir without .kenaz/, so the resolver's cwd
+// auto-detect level cannot fire. (os.tmpdir() itself is unsafe — a stray
+// .kenaz/ at the tmp root makes cwd auto-detect resolve to tmp.)
+const tmpCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'kenaz-t1812-cwd-'));
+
+/** Require a tool in a child process with controlled argv, print JSON of exports. */
+function probeExports(toolPath, extraArgv, keys) {
+  const script = [
+    // `node -e` starts with argv length 1 — pad so pushed flags land at
+    // index >= 2 and survive the modules' process.argv.slice(2).
+    `while (process.argv.length < 2) process.argv.push('');`,
+    `process.argv.push(${extraArgv.map(a => JSON.stringify(a)).join(',')});`,
+    `const m = require(${JSON.stringify(toolPath)});`,
+    `console.log(JSON.stringify(Object.fromEntries(${JSON.stringify(keys)}.map(k => [k, m[k]]))));`,
+  ].join('\n');
+  const r = spawnSync(process.execPath, ['-e', script], {
+    cwd: tmpCwd,
+    encoding: 'utf8',
+    timeout: 30000,
+    windowsHide: true,
+  });
+  if (r.status !== 0) return { error: (r.stderr || '').trim().split('\n')[0] || `exit ${r.status}` };
+  try { return JSON.parse(r.stdout.trim().split('\n').pop()); }
+  catch (e) { return { error: `bad probe output: ${e.message}` }; }
+}
+
+function runCli(toolPath, argv) {
+  return spawnSync(process.execPath, [toolPath, ...argv], {
+    cwd: tmpCwd,
+    encoding: 'utf8',
+    timeout: 60000,
+    windowsHide: true,
+  });
+}
+
+// js-yaml must be resolvable from the tools dir (isolated worktrees without
+// node_modules need NODE_PATH); lesson-guard requires it at module level.
+const jsyamlOk = spawnSync(process.execPath, ['-e', "require('js-yaml')"], {
+  cwd: TOOLS_DIR, encoding: 'utf8', timeout: 30000, windowsHide: true,
+}).status === 0;
+
+console.log('tail-cli-project-path.test.js (TASK_1812)');
+console.log(`ROOT = ${ROOT}`);
+
+const tmpProj = fs.mkdtempSync(path.join(os.tmpdir(), 'kenaz-t1812-proj-'));
+
+try {
+  // ── Arm A: backward compat — no --project-path -> BASE_DIR anchoring ──────
+  console.log('\n[A] no --project-path -> core (BASE_DIR) paths');
+
+  const fdBase = probeExports(FAIL_DETECTOR, ['--session-id', NO_PIN_SID],
+    ['BASE_DIR', 'PROJECT_DIR', 'SHADOW_LOG_PATH', 'EXPIRE_LOG_PATH', 'AMBIENT_SIGNALS']);
+  check('failure-detector probe loads', !fdBase.error, fdBase.error);
+  if (!fdBase.error) {
+    check('failure-detector PROJECT_DIR === BASE_DIR', norm(fdBase.PROJECT_DIR) === norm(fdBase.BASE_DIR),
+      `${fdBase.PROJECT_DIR} vs ${fdBase.BASE_DIR}`);
+    check('failure-detector SHADOW_LOG_PATH under core .kenaz',
+      norm(fdBase.SHADOW_LOG_PATH) === norm(path.join(fdBase.BASE_DIR, '.kenaz', 'specialist', 'guard_detector_shadow.jsonl')),
+      fdBase.SHADOW_LOG_PATH);
+    check('failure-detector EXPIRE_LOG_PATH under core .kenaz',
+      norm(fdBase.EXPIRE_LOG_PATH) === norm(path.join(fdBase.BASE_DIR, '.kenaz', 'specialist', 'guard_expire_log.jsonl')),
+      fdBase.EXPIRE_LOG_PATH);
+  }
+
+  if (jsyamlOk) {
+    const lgBase = probeExports(LESSON_GUARD, ['--session-id', NO_PIN_SID],
+      ['BASE_DIR', 'PROJECT_DIR', 'ACTED_ON_LOG_PATH', 'LESSON_GUARDS_YAML']);
+    check('lesson-guard probe loads', !lgBase.error, lgBase.error);
+    if (!lgBase.error) {
+      check('lesson-guard PROJECT_DIR === BASE_DIR', norm(lgBase.PROJECT_DIR) === norm(lgBase.BASE_DIR),
+        `${lgBase.PROJECT_DIR} vs ${lgBase.BASE_DIR}`);
+      check('lesson-guard ACTED_ON_LOG_PATH under core .kenaz',
+        norm(lgBase.ACTED_ON_LOG_PATH) === norm(path.join(lgBase.BASE_DIR, '.kenaz', 'specialist', 'lesson_guard_acted_on.jsonl')),
+        lgBase.ACTED_ON_LOG_PATH);
+    }
+  } else {
+    skip('lesson-guard arm A', 'js-yaml not resolvable from tools dir (set NODE_PATH)');
+  }
+
+  // ── Arm B: --project-path -> project .kenaz, system config stays core ─────
+  console.log('\n[B] --project-path=<tmp> -> project .kenaz paths, .specialist stays core');
+
+  const fdProj = probeExports(FAIL_DETECTOR, ['--project-path', tmpProj],
+    ['BASE_DIR', 'PROJECT_DIR', 'SHADOW_LOG_PATH', 'EXPIRE_LOG_PATH', 'AMBIENT_SIGNALS']);
+  check('failure-detector PROJECT_DIR honors --project-path', !fdProj.error && norm(fdProj.PROJECT_DIR) === norm(tmpProj),
+    fdProj.error || fdProj.PROJECT_DIR);
+  if (!fdProj.error) {
+    check('failure-detector SHADOW_LOG_PATH under project .kenaz',
+      norm(fdProj.SHADOW_LOG_PATH) === norm(path.join(tmpProj, '.kenaz', 'specialist', 'guard_detector_shadow.jsonl')),
+      fdProj.SHADOW_LOG_PATH);
+    check('failure-detector AMBIENT_SIGNALS under project .kenaz',
+      norm(fdProj.AMBIENT_SIGNALS) === norm(path.join(tmpProj, '.kenaz', 'specialist', 'ambient_signals.json')),
+      fdProj.AMBIENT_SIGNALS);
+  }
+
+  if (jsyamlOk) {
+    const lgProj = probeExports(LESSON_GUARD, ['--project-path=' + tmpProj],
+      ['BASE_DIR', 'PROJECT_DIR', 'ACTED_ON_LOG_PATH', 'LESSON_GUARDS_YAML']);
+    check('lesson-guard PROJECT_DIR honors --project-path=', !lgProj.error && norm(lgProj.PROJECT_DIR) === norm(tmpProj),
+      lgProj.error || lgProj.PROJECT_DIR);
+    if (!lgProj.error) {
+      check('lesson-guard ACTED_ON_LOG_PATH under project .kenaz',
+        norm(lgProj.ACTED_ON_LOG_PATH) === norm(path.join(tmpProj, '.kenaz', 'specialist', 'lesson_guard_acted_on.jsonl')),
+        lgProj.ACTED_ON_LOG_PATH);
+      check('lesson-guard LESSON_GUARDS_YAML stays on core (.specialist system config)',
+        norm(lgProj.LESSON_GUARDS_YAML) === norm(path.join(lgProj.BASE_DIR, '.specialist', 'Ansuz', 'guards', 'lesson_guards.yaml')),
+        lgProj.LESSON_GUARDS_YAML);
+    }
+  } else {
+    skip('lesson-guard arm B', 'js-yaml not resolvable from tools dir (set NODE_PATH)');
+  }
+
+  // ── Arm C: real CLI writes land in project .kenaz, core untouched ─────────
+  console.log('\n[C] real CLI writes: project .kenaz written, core .kenaz untouched');
+
+  if (!jsyamlOk) {
+    skip('arm C', 'js-yaml not resolvable from tools dir (set NODE_PATH)');
+  } else {
+    const yamlText = readOrNull(GUARDS_YAML) || '';
+    const guardIdM = yamlText.match(/^ {2}(L-\d+):/m);
+    if (!guardIdM) {
+      skip('arm C', `no L-XXX guard found in ${GUARDS_YAML}`);
+    } else {
+      const guardId = guardIdM[1];
+      const coreActedBefore  = readOrNull(CORE_ACTED_ON);
+      const coreShadowBefore = readOrNull(CORE_SHADOW);
+      const yamlBefore = yamlText;
+      try {
+        // lesson-guard: space-separated flag form — also proves positional args
+        // (<guard-id> <session-id>) survive the resolver flags.
+        const sid = `t1812-contract-${uid()}`;
+        const r1 = runCli(LESSON_GUARD,
+          ['record-acted-on', guardId, sid, '--project-path', tmpProj, '--reason=t1812 contract test']);
+        check('lesson-guard record-acted-on exits 0 (space-form flag)', r1.status === 0,
+          (r1.stderr || r1.stdout || '').trim().split('\n')[0]);
+        const projActed = readOrNull(path.join(tmpProj, '.kenaz', 'specialist', 'lesson_guard_acted_on.jsonl'));
+        check('acted-on record written under project .kenaz',
+          !!projActed && projActed.includes(sid), projActed === null ? 'file missing' : 'session id not found');
+        check('core acted-on jsonl untouched', readOrNull(CORE_ACTED_ON) === coreActedBefore);
+
+        // failure-detector: run one guard against a nonexistent task — shadow
+        // mode logs the (undetectable) decision to the project shadow log.
+        const probeTask = `TASK_T1812_${uid().toUpperCase()}`;
+        const r2 = runCli(FAIL_DETECTOR,
+          ['run', `--task=${probeTask}`, `--guard=${guardId}`, `--project-path=${tmpProj}`]);
+        check('failure-detector run exits 0', r2.status === 0,
+          (r2.stderr || r2.stdout || '').trim().split('\n')[0]);
+        const projShadow = readOrNull(path.join(tmpProj, '.kenaz', 'specialist', 'guard_detector_shadow.jsonl'));
+        check('shadow record written under project .kenaz',
+          !!projShadow && projShadow.includes(probeTask), projShadow === null ? 'file missing' : 'task id not found');
+        check('core shadow jsonl untouched', readOrNull(CORE_SHADOW) === coreShadowBefore);
+      } finally {
+        // record-acted-on mutates the (core, system-config) guards yaml — restore.
+        if (yamlBefore) fs.writeFileSync(GUARDS_YAML, yamlBefore, 'utf8');
+      }
+      check('guards yaml restored byte-identical', readOrNull(GUARDS_YAML) === yamlBefore);
+    }
+  }
+} finally {
+  try { fs.rmSync(tmpProj, { recursive: true, force: true }); } catch { /* best-effort */ }
+  try { fs.rmSync(tmpCwd, { recursive: true, force: true }); } catch { /* best-effort */ }
+}
+
+console.log(`\nResult: ${passed} passed, ${failed} failed, ${skipped} skipped`);
+process.exit(failed > 0 ? 1 : 0);

package/core/.specialist/tools/MEMORY_RECALL_TRIGGERS.md

@@ -0,0 +1,156 @@
+# Memory Recall Trigger Map (TASK_1077)
+
+Canonical mapping of specialist decision points to required recall operations,
+source types, and conflict resolution. This document is the authoritative trigger
+contract. Telemetry instrumentation (`memory-action-log.js`, `acted_on` events)
+is built on top of this contract by TASK_1072 — do not mix the layers.
+
+**Machine-consumable counterpart:**
+`.kenaz/specialist/memory_source_priority.yaml`
+
+**Rule enforcement:**
+`.rule/general/memory-source-priority.yaml` (MSP-001 through MSP-005)
+
+---
+
+## Core Principle
+
+> Memory is only valuable when it changes a decision.
+
+Every recall call has a **decision point** on the other side. If you cannot
+name the decision the recall will inform, you are loading context for show.
+The trigger map below makes this concrete: for each phase or moment, it
+specifies _what_ to recall, _from which source_, and _what happens next_.
+
+---
+
+## Trigger Map
+
+| Phase / Moment | Tool | Sources Surfaced | Required vs Optional | Conflict Mode |
+|---|---|---|---|---|
+| **Phase 0 — Boot** | `cortex_recall(type=ash, limit=5)` | `summary_or_ash_rune` | Required | advisory |
+| **Phase 0 — Boot** | `synapse_sigils(projectPath)` | `sigil` | Required | advisory |
+| **Phase 0 — Boot** | `hippocampus_episode_recall(limit=3)` | `episode`, `session_handoff` | Conditional (prior session exists) | advisory |
+| **Phase 0 — Boot** | Read `ansuz_self_model.json` | `self_model_lesson` | Required | advisory |
+| **Phase 0 — Boot** | Auto-load handoff slot | `session_handoff` | Conditional (fatigue_warning in prior session) | advisory |
+| **Phase 1 — Requirements** | `synapse_recall(query=task_title+scope)` | `insight_or_pattern_rune`, `risk_or_fix_rune`, `episode` | Required | advisory |
+| **Before editing a symbol** | `synapse_recall(symbol_name)` + `kenaz_lsp_callers` | `risk_or_fix_rune`, `verified_decision_rune` | Required (non-trivial changes) | strict (risk/fix) |
+| **Phase 3 — Decomposition** | `kenaz_lsp_callers(scope symbols)` | `risk_or_fix_rune`, `sigil` | Required | strict (risk/fix) |
+| **Phase 8 — Dispatch** | `synapse_recall(dispatch patterns)` | `sigil`, `self_model_lesson`, `session_handoff` | Optional | advisory |
+| **Phase 9 — Verification** | `git diff --stat` + `synapse_recall(symbols)` | `risk_or_fix_rune`, `sigil` | Required | strict (risk) |
+| **Retry / Bail decision** | `synapse_recall(error signature)` | `risk_or_fix_rune`, `episode` | Required | strict (fix) |
+| **Phase-gate blocked exit** | `lesson_guards` auto-surfaced | `lesson_guard`, `session_handoff` | Auto (phase-gate handles) | advisory |
+
+### Conditional triggers (detail)
+
+- **Handoff load (Phase 0):** Only if a per-session slot exists under
+  `.kenaz/specialist/handoffs/` (newest `generated_at` wins — resolved via
+  `handoff-resolver.js readLatestHandoff`; the legacy singular
+  `ansuz_session_handoff.json` is retired read-only fallback, M3/TASK_1760)
+  AND its `generated_at` timestamp is within the `ttl_hours: 72` window. Stale handoffs
+  are ignored (they contain context from a cycle too far in the past).
+
+- **Episode recall (Phase 0):** Only when `hippocampus_episode_recall` returns ≥ 1 result.
+  If the project has no episodes yet (cold start), skip silently — do not error.
+
+- **Phase 1 deep episode drill:** If Phase 0 episode summary mentions a `task_id` relevant
+  to current requirements, call `hippocampus_episode_recall(task_id=that_id)` to get full entries.
+
+- **synapse_recall before edit:** May skip for trivial changes (config value, typo, < 5 lines).
+  Judgment required. If skipping, note it explicitly (FAIL-009 records past recall-skips that
+  caused regressions; pulse itself is retired, recall is the replacement).
+
+---
+
+## Decision-Point Checklist
+
+Before a recalled item can be treated as **acted-on** (influencing a decision),
+confirm all three:
+
+1. **Name the specific recalled item.**
+   `source_id` = rune_id, episode_id, sigil_id, guard id (L-XXX), blind-spot id (B-XXX),
+   handoff `session_id`, or self_model `growth` entry hash.
+
+2. **The recall changed what you were about to do.**
+   State the "before" plan and the "after" plan in one sentence each. If the plan
+   did not change, the recall is informational only — still worth noting, but not acted-on.
+
+3. **The reason explains the delta, not the lookup.**
+   "Recalled L-003" is not evidence.
+   "L-003 flagged scope expansion requires a sub-task — created TASK_1077.1" is evidence.
+
+---
+
+## Conflict Resolution Contract
+
+When two sources disagree (e.g. an episode says "retry", a rune says "bail"):
+
+1. Apply `priority_rank` from `memory_source_priority.yaml` — higher rank wins.
+2. If same rank: apply `tie_breakers` in order (confidence DESC → freshness ASC → source_id ASC).
+3. Apply the winner's `conflict_mode`:
+   - **strict** → hide the loser from the agent; log with `conflict_with: <winner_source_id>`
+   - **advisory** → show both; label the loser as "competing view (rank: N)"
+4. If the agent disagrees with the winner's guidance, it must document the override reason
+   before proceeding (no silent overrides).
+
+### Conflict examples
+
+| Winner | Loser | Mode | What happens |
+|---|---|---|---|
+| `risk_or_fix_rune` (rank 60) | `episode` (rank 30) says "proceed" | strict | Agent follows rune; episode suppressed; override requires user statement |
+| `session_handoff` (rank 80) | `insight_or_pattern_rune` (rank 40) | advisory | Both surfaced; agent chooses with documented reason |
+| `verified_decision_rune` (rank 90) | `self_model_lesson` (rank 70) | strict | Agent follows decision rune; self-model view logged only |
+
+---
+
+## Anti-Patterns
+
+| Pattern | Why it fails |
+|---|---|
+| Recalling every source at every phase | Phase 0 boot cost grows unbounded; irrelevant context degrades signal |
+| Skipping recall at phase boundaries | Misses the decision point; FAIL-009 shows this causes regressions |
+| Treating lesson_guards as primary evidence | They are the *lowest* rank (10); trace back to the originating rune/episode |
+| Loading Phase 0 handoff even when > 72h old | Stale handoffs inject obsolete context; TTL exists for this reason |
+| "Recalling" from a source not actually queried | Incoherent audit trail; metrics show recall=0 / acted_on=1 |
+
+---
+
+## Minimal Integration Contract for New Specialists
+
+A specialist flow integrating with this system needs exactly two behaviors:
+
+1. **At each trigger boundary** (see Trigger Map above), call the listed tool.
+   Pass `projectPath` to every Synapse/Hippocampus call — omitting it causes
+   multi-session collision on the global default project.
+
+2. **When a recalled item changes a decision**, mark it as acted-on via the
+   `memory_acted_on` field on phase-gate exit OR via `memory-action-log.js`
+   `recordActedOn()` directly (TASK_1072 adds this layer).
+
+Both behaviors are independently useful: #1 is the contract defined here;
+#2 is observability added by TASK_1072. Do not depend on #2 being present.
+
+---
+
+## Rule References
+
+| Rule | File | Scope |
+|---|---|---|
+| MSP-001 through MSP-005 | `.rule/general/memory-source-priority.yaml` | Priority ordering, conflict modes, required triggers |
+| SYN-001 through SYN-007 | `.rule/general/synapse-code-intelligence.yaml` | Which Synapse tool at which moment |
+| SYN-008 through SYN-011 | `.rule/general/synapse-cognitive-fusion.yaml` | When to promote recalled patterns to runes/sigils |
+| MEM-LANG-001 | `.rule/general/memory-language.yaml` | All memory writes must be in English |
+| DDx stack | `.rule/general/ddx-synapse-stack.yaml` | Recall before writing code (pulse-or-recall gate) |
+
+---
+
+## File Locations
+
+| File | Purpose |
+|---|---|
+| `.kenaz/specialist/memory_source_priority.yaml` | Machine-consumable priority + conflict contract |
+| `.specialist/tools/MEMORY_RECALL_TRIGGERS.md` | This file — human-readable trigger map |
+| `.specialist/tools/memory-action-log.js` | Telemetry layer (TASK_1072) — `recordRecall` / `recordActedOn` |
+| `.specialist/Ansuz/modules/recall.yaml` | Ansuz-specific recall protocol (Tier 1/2/3 boot sequence) |
+| `.specialist/Ansuz/guards/lesson_guards.yaml` | L-XXX lesson guards surfaced by phase-gate |
+| `.kenaz/specialist/memory_action_log.jsonl` | Append-only event log (TASK_1072) |

package/core/.specialist/tools/README.md

@@ -0,0 +1,129 @@
+# Specialist 工具
+
+此目錄包含用於管理和建立 Specialist 的工具腳本。
+
+## session.js
+
+全系統通用的 Specialist Session 管理工具。程式化載入 Specialist 的 persona，不依賴 `.claude/commands/`。
+
+### 設計理念
+
+| 現行方式 | session.js |
+|---------|-----------|
+| `/Ansuz` slash command | `session.js prompt Ansuz` |
+| 只能在 Claude Code 內用 | Formation、Dashboard、subagent、CLI、API 都能呼叫 |
+| 回傳「去讀這些檔案」 | 回傳完整組裝好的 prompt（或 reference 模式） |
+| 無 session 狀態管理 | 有 start/end/active 生命週期 |
+
+### 雙模式
+
+| 模式 | 說明 | 用途 |
+|------|------|------|
+| **assembled**（預設） | 將所有 YAML 內容內嵌到 prompt | headless.js、API、Dashboard |
+| **reference** | 回傳檔案讀取指令（同 slash command） | Claude Code 內互動 |
+
+### CLI 用法
+
+```bash
+# 列出所有 Specialist
+node .specialist/tools/session.js list
+node .specialist/tools/session.js list --json
+
+# 查看 Specialist 配置
+node .specialist/tools/session.js resolve Ansuz
+
+# 產生 prompt
+node .specialist/tools/session.js prompt Ansuz
+node .specialist/tools/session.js prompt Ansuz --mode=reference
+node .specialist/tools/session.js prompt Ansuz --exclude=workflow,knowledge
+
+# Session 管理
+node .specialist/tools/session.js start Ansuz --consumer=formation --task="Build auth"
+node .specialist/tools/session.js active
+node .specialist/tools/session.js end <sessionId>
+node .specialist/tools/session.js clean --keep=5
+```
+
+### Module 用法
+
+```js
+const session = require('.specialist/tools/session');
+
+// 列出 Specialist
+const specialists = session.list();
+// → [{ name: 'Ansuz', purpose: '...', symbol: 'ᚨ ...', version: '1.0.0' }]
+
+// 載入配置
+const spec = session.resolve('Ansuz');
+// → { name, purpose, symbol, dir, fileList, loadedFiles, exitTriggers }
+
+// 組裝 prompt
+const prompt = session.buildPrompt('Ansuz', {
+  mode: 'assembled',       // 'assembled' | 'reference'
+  task: 'TASK_200',        // 注入任務
+  context: '...',          // 注入 context
+  exclude: ['workflow'],   // 排除指定區塊
+});
+
+// 開始 session
+const { sessionId, prompt, metadata } = session.startSession('Ansuz', {
+  consumer: 'formation',
+});
+
+// 結束 session
+session.endSession(sessionId);
+
+// 查看活躍 session
+const active = session.getActiveSessions();
+```
+
+### 整合範例
+
+**Formation headless.js**:
+```js
+const { buildPrompt } = require('../.specialist/tools/session');
+const prompt = buildPrompt('Ansuz', { task: taskData, mode: 'assembled' });
+// → 傳給 claude CLI 作為 system prompt
+```
+
+**Dashboard (Tauri)**:
+```bash
+node .specialist/tools/session.js list --json
+node .specialist/tools/session.js start Ansuz --consumer=dashboard --json
+```
+
+**Subagent (Task tool)**:
+```js
+const { buildPrompt } = require('.specialist/tools/session');
+// 用 prompt 作為 Task tool 的 prompt 參數
+```
+
+### Session 狀態
+
+Session 狀態存放於 `.specialist/sessions/`（已加入 .gitignore）。
+
+每個 session 是一個 JSON 檔案：
+```json
+{
+  "id": "session_1708xxx_abc123",
+  "specialist": "Ansuz",
+  "symbol": "ᚨ ...",
+  "consumer": "formation",
+  "status": "active",
+  "startedAt": "2026-02-23T...",
+  "endedAt": null,
+  "promptLength": 37528
+}
+```
+
+### Flags
+
+| Flag | 說明 |
+|------|------|
+| `--json` | JSON 格式輸出 |
+| `--mode=assembled\|reference` | prompt 模式（預設 assembled） |
+| `--consumer=<type>` | session 使用者（cli/formation/dashboard/subagent） |
+| `--task=<text>` | 注入任務描述到 prompt |
+| `--context=<text>` | 注入額外 context 到 prompt |
+| `--exclude=a,b` | 排除指定區塊（如 workflow,knowledge） |
+| `--with-prompt` | start 時輸出完整 prompt |

package/core/.specialist/tools/__tests__/freya-cli-contract.test.js

@@ -0,0 +1,156 @@
+'use strict';
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const vm = require('node:vm');
+const { spawnSync } = require('node:child_process');
+const ROOT = path.resolve(__dirname, '../../..');
+const LEASE = path.join(ROOT, '.specialist/tools/stream-lease.js');
+
+function sandbox(t) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freya-cli-'));
+  fs.mkdirSync(path.join(dir, '.kenaz/specialist/sessions/leases'), { recursive: true });
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+function seed(dir, sid, hours, extra = {}) {
+  const row = { session_id: sid, label: sid, heartbeat_at: new Date(Date.now() - hours * 3600000).toISOString(), ...extra };
+  fs.writeFileSync(path.join(dir, '.kenaz/specialist/sessions/leases', sid + '.json'), JSON.stringify(row));
+}
+function leases(dir) {
+  return fs.readdirSync(path.join(dir, '.kenaz/specialist/sessions/leases')).sort();
+}
+function register(dir, args) {
+  const r = spawnSync(process.execPath, [LEASE, 'register', ...args], {
+    encoding: 'utf8', timeout: 10000, windowsHide: true,
+    env: { ...process.env, CLAUDE_PROJECT_DIR: dir },
+  });
+  assert.equal(r.status, 0, r.stderr);
+  return r;
+}
+
+test('create help documents repeated flags, args-file and exact quality minima', () => {
+  const r = spawnSync(process.execPath, [path.join(ROOT, '.collaboration/core/task-api.js'),
+    '--project-path=' + path.resolve(ROOT, '../quotation'), '--help'],
+  { encoding: 'utf8', timeout: 10000, windowsHide: true });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, /--requirements "R1" --requirements "R2"/);
+  assert.match(r.stdout, /--technical-notes "T1" --technical-notes "T2"/);
+  assert.match(r.stdout, /--args-file PATH/);
+  assert.match(r.stdout, /requirements >= 3，acceptance_criteria >= 3，technical_notes >= 2/);
+  assert.doesNotMatch(r.stdout, /--requirements "R1" "R2"/);
+});
+
+test('register reaps only old known stale peers and preserves current, live, recent and unknown leases', t => {
+  const dir = sandbox(t);
+  seed(dir, 'expired', 25);
+  seed(dir, 'live', 1);
+  seed(dir, 'stale-below-bulk', 12);
+  seed(dir, 'current', 30);
+  seed(dir, 'own', 30);
+  seed(dir, 'missing-time', 30, { heartbeat_at: null });
+  seed(dir, 'invalid-time', 30, { heartbeat_at: 'invalid' });
+  fs.writeFileSync(path.join(dir, '.kenaz/specialist/current_stream.json'), JSON.stringify({ session_id: 'current' }));
+  const r = register(dir, ['--session-id=own']);
+  assert.match(r.stderr, /without --conversation-id/);
+  assert.deepEqual(leases(dir), ['current.json', 'invalid-time.json', 'live.json', 'missing-time.json', 'own.json', 'stale-below-bulk.json']);
+  assert.equal(JSON.parse(fs.readFileSync(path.join(dir, '.kenaz/specialist/current_stream.json'))).session_id, 'current');
+});
+
+test('register retains a resumed conversation lease and its claimed state', t => {
+  const dir = sandbox(t);
+  seed(dir, 'resumed', 48, { conversation_id: 'real-conversation', claimed_tasks: ['TASK_1'], scope_leases: ['src/'] });
+  seed(dir, 'expired-peer', 48);
+  const r = register(dir, ['--session-id=proposed', '--conversation-id=real-conversation']);
+  assert.match(r.stdout, /registered resumed .*reused/);
+  assert.deepEqual(leases(dir), ['resumed.json']);
+  const row = JSON.parse(fs.readFileSync(path.join(dir, '.kenaz/specialist/sessions/leases/resumed.json')));
+  assert.deepEqual(row.claimed_tasks, ['TASK_1']);
+  assert.deepEqual(row.scope_leases, ['src/']);
+});
+
+test('automatic reap re-reads heartbeat before deletion', t => {
+  const dir = sandbox(t);
+  seed(dir, 'renewed', 48);
+  const target = path.join(dir, '.kenaz/specialist/sessions/leases/renewed.json');
+  let reads = 0;
+  const fakeFs = Object.create(fs);
+  fakeFs.readFileSync = (file, ...args) => {
+    if (file === target && ++reads === 2) seed(dir, 'renewed', 0);
+    return fs.readFileSync(file, ...args);
+  };
+  const mod = { exports: {} };
+  const ctx = { module: mod, __dirname: path.dirname(LEASE), process: { ...process, env: { CLAUDE_PROJECT_DIR: dir } },
+    require: name => name === 'fs' ? fakeFs : require(name) };
+  vm.runInNewContext(fs.readFileSync(LEASE, 'utf8'), ctx, { filename: LEASE });
+  assert.equal(mod.exports.reapExpiredLeases([]).length, 0);
+  assert.ok(fs.existsSync(target));
+  assert.equal(reads, 2);
+});
+
+// Execute the actual CLI entry with mocked worktree/prompt dependencies. No git,
+// task creation, model call or live dispatch occurs; resource files stay in dir.
+for (const failWorktree of [false, true]) {
+  test('subagent stdout remains one JSON payload with resources and worktree ' + (failWorktree ? 'fallback' : 'progress'), async t => {
+    const dir = sandbox(t);
+    fs.mkdirSync(path.join(dir, '.git'));
+    let stdout = '', stderr = '';
+    const consoleStub = {
+      log: (...a) => { stdout += a.join(' ') + '\n'; },
+      error: (...a) => { stderr += a.join(' ') + '\n'; },
+      warn: (...a) => { stderr += a.join(' ') + '\n'; },
+    };
+    const originalLog = consoleStub.log;
+    const models = { dispatchFamily: 'claude', dispatchModel: 'claude-sonnet-5', dispatchMode: 'auto' };
+    const dependencies = {
+      './loader': { loadSkill: () => ({}), loadTask: () => JSON.stringify({ resources: ['build-cache'] }) },
+      './prompt': { buildPrompt: () => 'assembled prompt', SUBAGENT_PREFIX: 'native:', SUBAGENT_PREFIX_DIRECT: 'direct:', buildSubagentWorktreePrefix: () => 'worktree:',
+        // pure helpers dispatch.js destructures at load (TASK_1998/2252 rigor gate); neutral values
+        promptProfile: () => ({}), extractRigor: () => 'medium', extractComplexity: () => 'medium',
+        splitPromptSections: () => [], applyRustCheckToPrefix: prefix => prefix },
+      './runner': {}, './remote-conflict': {},
+      // TASK_2297 free-space gate before worktree creation; enough space in the fixture
+      './worktree-reclaim': { ensureWorktreeSpace: () => ({ ok: true }) },
+      './utils': { ROOT: path.join(dir, 'core'), loadDashboardModels: () => models,
+        resolveWorktreeDecision: () => ({ useWorktree: true, source: 'test' }),
+        ensureWorktreeDirIgnored: () => consoleStub.log('ignore progress'),
+        createWorktree: () => { consoleStub.log('worktree progress'); if (failWorktree) throw new Error('fixture failure'); },
+        getVerifyOfflineCommand: () => null,
+        dispatchLockPath: () => path.join(dir, 'dispatch.lock'),
+        tryAcquireDispatchLock: () => ({ acquired: true }),
+      },
+    };
+    // loadDispatchRouting reads the real, sandboxed model settings file.
+    fs.writeFileSync(path.join(dir, '.kenaz/dashboard-models.json'), JSON.stringify(models));
+    const mod = { exports: {} };
+    const req = name => {
+      if (Object.hasOwn(dependencies, name)) return dependencies[name];
+      if (name === 'fs' || name === 'path' || name === 'child_process') return require(name);
+      throw new Error('Unexpected dependency: ' + name);
+    };
+    req.main = mod;
+    const ctx = { module: mod, require: req, console: consoleStub, __dirname: path.join(ROOT, '.formation/tools'),
+      process: { ...process, env: {}, argv: ['node', 'dispatch.js', '--skill=do', '--task=TASK_28', '--dispatch-mode=subagent', '--project-path=' + dir],
+        stdout: { write: s => { stdout += s; } }, stderr: { write: s => { stderr += s; } },
+        exit: code => { throw new Error('Unexpected exit: ' + code); } },
+    };
+    const source = fs.readFileSync(path.join(ROOT, '.formation/tools/dispatch.js'), 'utf8').replace(/^#![^\n]*\n/, '');
+    vm.runInNewContext('(function(){\n' + source + '\n})()', ctx);
+    await new Promise(resolve => setImmediate(resolve));
+    const payload = JSON.parse(stdout);
+    assert.match(payload.promptText, /assembled prompt/);
+    assert.equal(payload.agentParams.model, 'sonnet');
+    assert.equal(payload.agentParams.isolation, undefined);
+    assert.equal(payload.dispatchMode, 'auto');
+    assert.equal(payload.effectiveMode, 'subagent');
+    assert.equal(payload.isolation.mode, failWorktree ? 'serial_lock' : 'target_repo_worktree');
+    if (!failWorktree) assert.equal(payload.isolation.worktreePath, path.join(dir, '.formation/worktrees/task_task_28'));
+    assert.match(stderr, /Resource locks acquired/);
+    assert.match(stderr, /ignore progress/);
+    assert.match(stderr, /worktree progress/);
+    assert.match(stderr, /NOT expressible/);
+    assert.equal(consoleStub.log, originalLog, 'logging restored even on worktree failure');
+  });
+}