kenaz 0.3.7 → 0.3.9

package/core/k-cli/README.md

@@ -1,330 +0,0 @@
-# k-cli
-
-KenazAI 的獨立 CLI 工具 — 無需 Dashboard，直接操作 Specialist、Task、Dispatch、Project 等核心功能。
-
-## 快速開始
-
-```bash
-cd k-cli && npm install && npm run build
-
-# 1. 確認 CLI 可用
-k-cli ping
-
-# 2. 查看專案狀態
-k-cli project status
-
-# 3. 若尚未初始化（status 顯示 mode: unknown）→ 初始化（core-path 自動偵測）
-k-cli project initialize
-
-# 4. 查看使用指南（初始化時自動產生）
-cat k-cli.md
-```
-
-**建議流程**：`ping` → `status` → （未初始化則 `initialize`）→ 正常使用
-
-## 定位
-
-| 比較 | Dashboard MCP (Rust) | mcp-server (Node，已於 TASK_2027 移除) | **k-cli** |
-|------|---------------------|-------------------|-------------|
-| 運行方式 | HTTP server（需 Dashboard） | stdio MCP server | **獨立 CLI** |
-| 依賴 | Tauri app 運行中 | MCP client 呼叫 | **無依賴，直接執行** |
-| 用途 | Claude Code 透過 `.mcp.json` 使用 | 已移除（TASK_2027） | **人類 + 腳本直接操作** |
-
-## 核心價值
-
-- **零依賴**：不需要 Dashboard 運行，直接呼叫底層工具
-- **spawnClaude 架構**：寫入操作透過 `spawnClaude` 直接啟動 Claude CLI
-- **dry-run 支援**：所有寫入命令支援 `--dry-run`，驗證但不執行
-- **可腳本化**：所有輸出支援 `--json` 格式，方便 pipe 和自動化
-- **明確偵測**：不猜測、不 fallback、不向上找目錄，偵測失敗就是失敗
-
-## 設計原則
-
-```
-讀取操作 → 直接呼叫底層工具（快速、無副作用）
-寫入操作 → spawnClaude 啟動 Claude CLI（Specialist 執行 / Ansuz 決策）
-```
-
-| 操作類型 | 命令 | 執行方式 |
-|---------|------|---------|
-| 讀取 | specialist list, task list, task get, project status... | 直接呼叫 |
-| 寫入（任務） | task create | → spawnClaude + Ansuz（分析需求 → Amelia 審查 role → 建立） |
-| 刪除 | task delete | → 直接 rm 檔案 |
-| 執行 | specialist run | → spawnClaude + 指定 Specialist |
-
-## 命令一覽
-
-```
-k-cli <command> [subcommand] [options]
-```
-
-### Specialist 命令
-
-| 命令 | 說明 | 執行方式 |
-|------|------|---------|
-| `k-cli specialist list` | 列出所有 Specialist（名稱 + prompt） | 直接讀取 |
-| `k-cli specialist run` | 啟動 Specialist 執行任務 | spawnClaude |
-
-```bash
-# 列出所有 Specialist 和 prompt
-k-cli specialist list
-
-# 啟動 Ansuz（positional args 作為 user prompt）
-k-cli specialist run --agent Ansuz 幫我檢查 git 狀態
-
-# 啟動 Amelia 協調多 Agent
-k-cli specialist run --agent Amelia 執行 TASK_340
-
-# dry-run：顯示會做什麼，不實際啟動
-k-cli specialist run --agent Ansuz 分析需求 --dry-run
-```
-
-### Task 命令
-
-| 命令 | 說明 | 執行方式 |
-|------|------|---------|
-| `k-cli task list` | 列出任務 | 直接讀取 |
-| `k-cli task get <id>` | 取得任務詳情 | 直接讀取 |
-| `k-cli task create <描述>` | 建立新任務（自然語言，人類用） | → spawnClaude + Ansuz + Amelia |
-| `k-cli task submit --title ... ` | 建立新任務（結構化欄位，process/script 用，TASK_2147） | 直接呼叫 task-api.js，無 Claude 依賴 |
-| `k-cli task delete <id>` | 刪除任務 | → 直接 rm 檔案 |
-
-```bash
-# 讀取（直接）
-k-cli task list --status backlog
-k-cli task get TASK_340
-
-# 建立任務（語意描述 → Ansuz 分析 → Amelia 審查 role → 建立高品質任務）
-k-cli task create 幫我創建 hello_world.js 輸出 Hello World
-k-cli task create 實作登入 API 支援 OAuth2 --dry-run
-
-# 刪除（直接 rm 檔案，不限狀態）
-k-cli task delete TASK_340
-k-cli task delete TASK_340 --dry-run
-```
-
-#### task submit（TASK_2147：子專案 process 用，無 Claude 依賴）
-
-`task create` 的輕量版：不分析自然語言、不呼叫 Ansuz/Amelia，直接把旗標轉成
-`task-api.js create` 呼叫。給已經知道自己要建什麼卡的 process/script 用（例如子專案裡的
-in-app agent 把一個改良提案變成任務）。core 解析沿用 `resolveProject()`（讀
-`.kenaz/project.yaml`），呼叫端不需要設定 `KENAZ_SOURCE_DIR`。
-
-```bash
-k-cli task submit \
-  --title "標題" --description "描述" --priority P3 --role developer \
-  --requirements "r1" --requirements "r2" --requirements "r3" \
-  --acceptance-criteria "a1" --acceptance-criteria "a2" --acceptance-criteria "a3" \
-  --technical-notes "n1" --technical-notes "n2" \
-  --origin "my-sub-project-agent" \
-  --project-path /path/to/subproject --json
-```
-
-- 任務一律落在 `backlog/`（正常 triage），**不會 auto-dispatch**。
-- `--origin`（= `--source`）未指定時，預設為子專案名稱；用來標記任務來源方便追溯。
-- 品質門檻（requirements/acceptance_criteria ≥ 3、technical_notes ≥ 2）與 `task create` 相同，不放寬。
-- `--json` 會在建立後自動 `task get` 回完整任務 JSON（含 `id`/`source`/`status`），方便腳本直接讀回結果。
-- `--dry-run` 顯示會執行的 task-api.js 指令，不實際建立。
-
-#### task create 流程
-
-```
-k-cli task create "描述"
-  │
-  ├─ k-cli 預先組裝 Ansuz + Amelia prompts（並行）
-  │
-  └→ spawnClaude(Ansuz) [allowedTools 含 Agent]
-       ├─ Step 1: 分析需求（理解目標、搜尋相關代碼）
-       ├─ Step 2: 整理任務草稿（結構化所有欄位）
-       ├─ Step 3: Agent tool → Amelia subagent 審查 + 判斷 role
-       ├─ Step 4: 採納建議 → task-api.js create（含正確 role）
-       └─ Step 5: 輸出結果摘要
-```
-
-> Amelia 審查透過 Claude 原生 Agent tool（subagent）執行，避免 nested CLI spawn。
-
-### Dispatch 命令
-
-| 命令 | 說明 | 執行方式 |
-|------|------|---------|
-| `k-cli dispatch status <taskId>` | 查看 dispatch 狀態 | 直接讀取 |
-
-```bash
-# 查看狀態（自動搜尋 .kenaz/logs/ 或 .formation/logs/）
-k-cli dispatch status TASK_340 --tail 50
-```
-
-### Project 命令
-
-| 命令 | 說明 | 執行方式 |
-|------|------|---------|
-| `k-cli project status` | 專案總覽 | 直接讀取 |
-| `k-cli project initialize` | 初始化子專案 `.kenaz/` 結構 | 直接執行 |
-| `k-cli project install <target>` | 安裝/更新模板檔案 | 直接執行 |
-
-```bash
-# 專案總覽
-k-cli project status
-
-# 初始化新子專案（core-path 自動從 CLI 位置推導）
-k-cli project initialize --project-path /path/to/new-project
-
-# 手動指定 core-path（覆蓋自動偵測）
-k-cli project initialize --project-path /path/to/new-project --core-path /other/KenazAI
-
-# 初始化但不 git init
-k-cli project initialize --project-path /path/to/project --no-git
-
-# dry-run：顯示會建立什麼
-k-cli project initialize --project-path /path/to/project --dry-run
-```
-
-`project status` 輸出內容：
-
-| 區塊 | 來源 | 資料 |
-|------|------|------|
-| 專案設定 | `.kenaz/project.yaml` | project_name、schema_version、core_path、tasks dir、logs dir |
-| Git 狀態 | `git` | branch、最後 commit、dirty files 數量 |
-| 任務統計 | `task-api.js stats` | backlog / active / done / blocked 數量、P0/P1 高亮 |
-
-`project initialize` 建立內容：
-
-| 項目 | 說明 |
-|------|------|
-| `.kenaz/project.yaml` | 專案配置（schema_version、project_name、core_path、路徑正規化為 `/`） |
-| `.kenaz/tasks/{backlog,active,done,blocked,cancel}/` | 任務目錄 |
-| `.kenaz/logs/{unit,solo,squad,legion,misc,legacy}/` | Formation log 目錄 |
-| `.gitignore` | 標準 gitignore（預設啟用，`--no-git` 跳過） |
-| `.gitattributes` | 行尾正規化（預設啟用，`--no-git` 跳過） |
-| `k-cli.md` | 使用指南（可用 `project install k-cli` 更新） |
-| `git init --initial-branch=main` | Git 初始化 + aliases + initial commit |
-
-```bash
-# 安裝/更新模板到現有專案
-k-cli project install k-cli
-
-# dry-run
-k-cli project install k-cli --dry-run
-```
-
-### 通用命令
-
-| 命令 | 說明 |
-|------|------|
-| `k-cli ping` | 健康檢查（顯示專案名稱、模式、core_path） |
-
-## 全域選項
-
-| Flag | 說明 |
-|------|------|
-| `--dry-run` | 驗證但不執行（適用所有寫入 / 調度命令） |
-| `--json` | 輸出 JSON 格式 |
-| `--project-path <path>` | 指定子專案路徑（使用 `.kenaz/project.yaml` 中的 `project_path` 值） |
-| `--force` | 跳過品質檢查（僅 `task create`） |
-| `--no-git` | 初始化時跳過 Git（僅 `project initialize`） |
-| `--core-path <path>` | 覆蓋自動偵測的 core 路徑（僅 `project initialize`） |
-| `--help`, `-h` | 顯示幫助 |
-
-## 架構
-
-```
-k-cli/
-├── README.md              # 本文件
-├── package.json           # 依賴管理（deps: yaml）
-├── tsconfig.json          # TypeScript 配置
-├── src/                   # TypeScript 原始碼
-│   ├── index.ts           # 入口 + 命令路由 + flag 解析
-│   ├── core/              # 共用基礎設施
-│   │   ├── types.ts       # ProjectInfo、CliFlags 型別定義
-│   │   ├── project.ts     # 專案偵測（core / sub-project / unknown）
-│   │   ├── process.ts     # nodeProcess — 統一 process spawner
-│   │   ├── spawn.ts       # spawnClaude — Claude CLI 直接啟動器
-│   │   └── output.ts      # 輸出格式化（table / JSON）
-│   ├── specialist/        # Specialist 功能
-│   │   ├── list.ts        # 列出 Specialist + prompt（直接）
-│   │   └── run.ts         # 啟動 Specialist（spawnClaude）
-│   ├── task/              # 任務管理功能
-│   │   ├── list.ts        # task list（直接 task-api.js）
-│   │   ├── get.ts         # task get（直接 task-api.js）
-│   │   ├── create.ts      # task create（spawnClaude + Ansuz + Amelia）
-│   │   ├── submit.ts      # task submit（直接 task-api.js，無 Claude 依賴，TASK_2147）
-│   │   ├── update.ts      # task update（直接 task-api.js）
-│   │   └── delete.ts      # task delete（直接 task-api.js）
-│   ├── dispatch/          # Formation 調度功能
-│   │   └── status.ts      # dispatch status（直接讀 log）
-│   └── project/           # 專案管理功能
-│       ├── status.ts      # project status（含 project.yaml 詳情）
-│       ├── initialize.ts  # project initialize（建立 .kenaz/ + Git）
-│       └── install.ts     # project install（安裝/更新模板）
-├── templates/             # 可安裝的模板檔案
-│   └── k-cli.md           # k-cli 使用指南
-└── dist/                  # 編譯輸出（npm run build）
-```
-
-### 內部呼叫關係
-
-```
-k-cli
-  │
-  ├─ 直接呼叫（讀取）
-  │   ├─ specialist/list   → fs.readdir(.specialist/) + session.js
-  │   ├─ task/list, get    → .collaboration/core/task-api.js
-  │   ├─ task/delete       → 直接 rm YAML 檔案（不限狀態）
-  │   ├─ dispatch/status   → .kenaz/logs/ 或 .formation/logs/ + log-reader.js
-  │   └─ project/status    → .kenaz/project.yaml + task-api.js stats + git commands
-  │
-  ├─ spawnClaude（Ansuz 決策）
-  │   ├─ task/create       → Ansuz 分析需求
-  │   │                       → Agent tool subagent（Amelia 審查 + role）
-  │   │                       → task-api.js create（最終建立）
-  │
-  └─ spawnClaude（Specialist 直接執行）
-      └─ specialist/run    → session.js（組裝 prompt）+ spawnClaude
-```
-
-### spawnClaude 架構
-
-`core/spawn.ts` 是 k-cli 的核心，直接啟動 Claude CLI 子進程：
-
-```
-spawnClaude(opts)
-  ├─ detectClaudeCmd()      → 偵測 claude CLI 路徑（Windows: .cmd / .exe）
-  ├─ getClaudeEnv()         → 清理環境變數（刪除 CLAUDECODE 避免嵌套檢測）
-  │   └─ detectGitBash()    → Windows: 偵測 git-bash 路徑
-  └─ spawn(claude, args)    → stdin pipe prompt, stream-json 輸出
-```
-
-## Dry-Run 行為
-
-`--dry-run` 適用於所有有副作用的命令：
-
-| 命令 | dry-run 行為 |
-|------|-------------|
-| `specialist run` | 組裝 prompt → 顯示 agent + prompt 長度 → **不 spawn Claude** |
-| `task create` | 組裝 Ansuz prompt → 顯示將建立的任務資訊 → **不啟動 Ansuz** |
-| `task update` | 組裝 task-api args → 顯示將更新的內容 → **不呼叫 task-api** |
-| `task delete` | 組裝 task-api args → 顯示將刪除的任務 → **不呼叫 task-api** |
-
-## 專案偵測邏輯
-
-`resolveProject` 使用明確偵測，不猜測、不 fallback、不向上搜尋目錄：
-
-| 偵測條件 | 模式 | core_path |
-|---------|------|-----------|
-| 有 `.collaboration/tasks/` | `core` | 當前目錄 |
-| 有 `.kenaz/project.yaml`（無 `.collaboration/tasks/`） | `sub-project` | yaml 中的 `core_path` 欄位 |
-| 以上都沒有 | `unknown` | 當前目錄 |
-
-## 安裝 & 執行
-
-```bash
-# 編譯
-cd k-cli && npm install && npm run build
-
-# 執行
-node dist/index.js ping
-node dist/index.js project status
-
-# 建議建立 alias
-alias k-cli="node /path/to/KenazAI/k-cli/dist/index.js"
-```

package/core/k-cli/package.json

@@ -1,21 +0,0 @@
-{
-  "name": "k-cli",
-  "version": "0.1.0",
-  "description": "KenazAI CLI tool — Specialist, Task, Dispatch operations",
-  "main": "dist/index.js",
-  "bin": {
-    "k-cli": "dist/index.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "test": "bash test/run.sh"
-  },
-  "dependencies": {
-    "yaml": "^2.7.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.9.3"
-  }
-}

package/core/k-cli/templates/k-cli.md

@@ -1,91 +0,0 @@
-# k-cli 使用指南
-
-本專案由 KenazAI k-cli 初始化管理。
-
-## 常用命令
-
-```bash
-# 健康檢查
-k-cli ping
-
-# 專案狀態
-k-cli project status
-
-# 任務管理（讀取）
-k-cli task list
-k-cli task list --status backlog
-k-cli task get TASK_XXX
-
-# 建立任務（Ansuz 分析 → Amelia subagent 審查 role → 建立）
-k-cli task create 幫我創建 hello_world.js 輸出 Hello World
-k-cli task create 實作登入 API 支援 OAuth2
-
-# 刪除任務（直接 rm，不限狀態）
-k-cli task delete TASK_XXX
-
-# Specialist（positional args 作為 user prompt）
-k-cli specialist list
-k-cli specialist run --agent Ansuz 幫我檢查 git 狀態
-k-cli specialist run --agent Amelia 執行 TASK_XXX
-
-# Dispatch — 指定任務（讀 role → 判斷陣型 → headless.js 執行）
-k-cli dispatch run TASK_XXX
-
-# Dispatch — 自動掃描（掃 backlog → 按優先級逐個 dispatch）
-k-cli dispatch run --auto
-
-# 查看 dispatch 狀態
-k-cli dispatch status TASK_XXX --tail 50
-
-# 專案初始化（新子專案）
-k-cli project initialize
-k-cli project initialize --project-path /path/to/project --no-git
-
-# 安裝/更新模板
-k-cli project install k-cli
-```
-
-## Dispatch 流程
-
-```
-k-cli dispatch run TASK_XXX
-  └→ Ansuz 讀 role → 判斷陣型 → headless.js
-       headless.js 自動處理：
-       ├─ auto-claim（backlog → active）
-       ├─ 依賴預檢
-       ├─ agent 執行任務
-       ├─ task complete
-       └─ post-complete（archive + git branch + merge to user branch）
-```
-
-Git merge 到 main 需要用戶手動操作。
-
-## Task Create 流程
-
-```
-k-cli task create "描述"
-  ├─ k-cli 預先組裝 Ansuz + Amelia prompts
-  └→ spawnClaude(Ansuz)
-       ├─ 分析需求 + 整理任務草稿
-       ├─ Agent tool → Amelia subagent 審查 + 判斷 role
-       └─ task-api.js create（建立任務）
-```
-
-Amelia 審查透過 Claude 原生 Agent tool（subagent）執行，無需嵌套 CLI。
-
-## 全域選項
-
-| Flag | 說明 |
-|------|------|
-| `--json` | JSON 輸出 |
-| `--dry-run` | 驗證但不執行 |
-| `--auto` | 自動掃描模式（僅 dispatch run） |
-| `--force` | 跳過品質檢查（僅 task create） |
-| `--project-path <path>` | 指定專案路徑（使用 `.kenaz/project.yaml` 中的 `project_path` 值） |
-| `--help` | 顯示幫助 |
-
-## 更新此文件
-
-```bash
-k-cli project install k-cli
-```

package/core/k-cli/test/TEST_SPEC.md

@@ -1,117 +0,0 @@
-# k-cli Test Specification
-
-## 概述
-
-Build 後在 `test/sandbox/` 建立真實專案環境，跑完所有 k-cli 功能。
-每次 `npm test` 自動：清空 sandbox → 初始化 → 逐項測試 → 報告結果。
-
-## 執行方式
-
-```bash
-cd k-cli
-npm run build && npm test
-```
-
-## 前置條件
-
-- Claude CLI 可用（`task create` 會 spawnClaude）
-- `npm run build` 必須先執行
-
-## 測試環境
-
-- **Sandbox**: `test/sandbox/`（每次測試前清空重建）
-- **Core Path**: KenazAI 本體（`k-cli/../`）
-- **路徑參數**: 使用 `.kenaz/project.yaml` 中的 `project_path`（絕對路徑）
-
-## 11 個測試
-
-### Test 1: project initialize → verify → delete k-cli.md → verify → install
-- `k-cli project initialize --project-path test/sandbox/ --no-git`
-- 驗證：`.kenaz/project.yaml` 存在、`tasks/` 5 個狀態目錄存在、`logs/` 6 個陣型目錄存在、`k-cli.md` 存在
-- 刪除 `test/sandbox/k-cli.md`
-- 驗證：`k-cli.md` 不存在
-- `k-cli project install k-cli --project-path test/sandbox/`
-- 驗證：`k-cli.md` 重新出現、內容含 `k-cli`
-
-### Test 2: ping
-- `k-cli ping --project-path test/sandbox/`
-- 驗證：輸出含 `k-cli` 且含 `sub-project`
-
-### Test 3: project status
-- `k-cli project status --project-path test/sandbox/ --json`
-- 驗證：JSON 解析成功、含 `sub-project`
-
-### Test 4: specialist list
-- `k-cli specialist list --project-path test/sandbox/`
-- 驗證：輸出含 `Ansuz` 且含 `Amelia`
-
-### Test 5: task create × 3 → list → get
-建立 3 個簡單任務，驗證 Ansuz + Amelia subagent 流程：
-
-1. `k-cli task create "寫一個 Node.js 程式，console.log 輸出 Hello World" --project-path test/sandbox/`
-   - 驗證：輸出含 TASK_ID（記為 TASK_A）
-2. `k-cli task create "寫一個 Node.js 程式，計算 10+10 並輸出結果" --project-path test/sandbox/`
-   - 驗證：輸出含 TASK_ID（記為 TASK_B）
-3. `k-cli task create "寫一個 Node.js 程式，讀取當前目錄的檔案列表並印出" --project-path test/sandbox/`
-   - 驗證：輸出含 TASK_ID（記為 TASK_C）
-
-流程驗證（每個 create 都會經過）：
-- spawnClaude(Ansuz) → 分析需求 → Agent tool subagent(Amelia) 審查 + 判斷 role → task-api.js create
-
-建立後驗證：
-- `k-cli task list --project-path test/sandbox/`
-- 驗證：輸出含 TASK_A、TASK_B、TASK_C，總數 ≥ 3
-- `k-cli task get TASK_A --project-path test/sandbox/`
-- 驗證：輸出含 TASK_A 詳細資訊
-
-### Test 6-8: 已移除
-- `dispatch run` 已刪除（Formation headless 調度已退役），`dispatch status` 失去可驗證的前置動作，一併移出測試
-
-### Test 9: task delete → verify
-- 使用 Test 5 的 TASK_A
-- `k-cli task get TASK_A` → 驗證任務存在
-- `k-cli task delete TASK_A --project-path test/sandbox/`（直接 rm，不限狀態）
-- `k-cli task list --project-path test/sandbox/`
-- 驗證：TASK_A 不在列表中
-
-### Test 10: specialist run Amelia（簡單任務）
-- `k-cli specialist run --agent Amelia 列出 sandbox 專案的任務狀態 --project-path test/sandbox/`
-- 驗證：spawnClaude(Amelia) 執行成功，輸出含任務相關資訊
-
-### Test 11: --dry-run（全指令驗證）
-不實際執行，僅驗證 dry-run 輸出正確：
-
-1. `k-cli project initialize --project-path test/sandbox/ --dry-run`
-   - 驗證：輸出含 `dry-run`
-2. `k-cli task create "測試 dry-run" --project-path test/sandbox/ --dry-run`
-   - 驗證：輸出含 `dry-run`，不呼叫 spawnClaude
-3. `k-cli task delete TASK_B --project-path test/sandbox/ --dry-run`
-   - 驗證：輸出含 `dry-run`，任務仍存在
-4. `k-cli specialist run --agent Amelia 測試 --project-path test/sandbox/ --dry-run`
-   - 驗證：輸出含 `dry-run`，不呼叫 spawnClaude
-5. `k-cli project install k-cli --project-path test/sandbox/ --dry-run`
-   - 驗證：輸出含 `dry-run`
-
-## 結果格式
-
-```
-k-cli Test Suite
-════════════════════════════════
-[ 1/11] project init+install   ✅ PASS
-[ 2/11] ping                  ✅ PASS
-[ 3/11] project status        ✅ PASS
-[ 4/11] specialist list       ✅ PASS
-[ 5/11] task create × 3       ✅ PASS
-[ 9/11] task delete             ✅ PASS
-[10/11] specialist run Amelia  ✅ PASS
-[11/11] --dry-run              ✅ PASS
-
-Result: 11/11 passed
-```
-
-失敗時顯示：
-```
-[ 5/11] task create × 3       ❌ FAIL
-  Expected output to contain "TASK_"
-  Got: "Error: ..."
-```