kenaz 0.3.21 → 0.3.23

package/core/dev/pipeline/docs/task-management.md

@@ -1,412 +0,0 @@
----
-type: guide
-title: Pipeline Task Management Guide
-description: 任務建立、管理、追蹤完整指南
-tags: [pipeline, task, management, yaml]
-audience: developer
----
-
-# Task Management Guide
-
-## 任務生命週期
-
-```
-建立 → 待執行 → 執行中 → 已完成 → 封存
-```
-
-## 建立任務
-
-### 1. 手動建立
-
-在 `dev/pipeline/tasks/` 目錄下建立 YAML 文件：
-
-```yaml
-# dev/pipeline/tasks/TASK_150_auth_api.yaml
-id: TASK_150
-title: "建立用戶認證 API"
-description: |
-  實現完整的 JWT 認證機制：
-  - 登入 (POST /api/auth/login)
-  - 註冊 (POST /api/auth/register)
-  - Token 刷新 (POST /api/auth/refresh)
-  - Token 驗證中介軟體
-
-type: feature  # feature, bugfix, refactor, docs, test
-priority: P1   # P0, P1, P2, P3
-status: pending
-
-scope:
-  - src/api/auth/
-  - src/models/user.py
-  - src/middleware/jwt_auth.py
-  - tests/api/test_auth.py
-
-dependencies:
-  - TASK_120  # User Model Schema
-
-estimated_hours: 4
-
-acceptance_criteria:
-  - id: AC-150-1
-    description: "登入 API 接受 email/password，回傳 JWT token"
-    test: "POST /api/auth/login 回應 200 與 token"
-
-  - id: AC-150-2
-    description: "Token 驗證中介軟體正確驗證請求"
-    test: "受保護的 API 需要有效 token 才能存取"
-
-  - id: AC-150-3
-    description: "通過安全性測試（密碼雜湊、Token 過期）"
-    test: "pytest tests/api/test_auth.py 全數通過"
-
-notes: |
-  - 使用 bcrypt 進行密碼雜湊
-  - Token 有效期設為 24 小時
-  - Refresh token 有效期 30 天
-
-created_by: "PM Agent"
-created_at: "2026-02-09T10:00:00Z"
-```
-
-### 2. 透過 PM Agent 建立
-
-```bash
-/產品 "我需要實現用戶認證功能"
-
-# PM Agent 會：
-# 1. 分析需求
-# 2. 撰寫 PRD
-# 3. 建立任務文件
-# 4. 添加到 TASK_QUEUE.json
-```
-
-## 任務屬性
-
-### 必填欄位
-
-| 欄位 | 類型 | 說明 |
-|------|------|------|
-| `id` | string | 唯一標識符（TASK_XXX） |
-| `title` | string | 簡短標題（< 80 字符） |
-| `description` | string | 詳細說明 |
-| `type` | enum | feature, bugfix, refactor, docs, test |
-| `priority` | enum | P0, P1, P2, P3 |
-| `status` | enum | pending, in_progress, completed, blocked, cancelled |
-| `scope` | array | 影響的檔案路徑 |
-
-### 選填欄位
-
-| 欄位 | 類型 | 說明 |
-|------|------|------|
-| `dependencies` | array | 前置任務 ID 列表 |
-| `estimated_hours` | number | 預估時數 |
-| `acceptance_criteria` | array | 驗收標準列表 |
-| `notes` | string | 備註 |
-| `tags` | array | 標籤 |
-
-## 任務狀態管理
-
-### 狀態轉換
-
-```
-pending → in_progress → completed
-   ↓
-blocked → pending (依賴完成後)
-   ↓
-cancelled (不再需要)
-```
-
-### 手動更新狀態
-
-編輯 `TASK_QUEUE.json`：
-
-```json
-{
-  "tasks": [
-    {
-      "id": "TASK_150",
-      "status": "in_progress",  // 改為 completed
-      "assigned_to": "agent_001",
-      "started_at": "2026-02-09T10:30:00Z",
-      "completed_at": "2026-02-09T14:15:00Z"  // 添加完成時間
-    }
-  ]
-}
-```
-
-### 透過 Python API
-
-```python
-from dev.pipeline.orchestrator.task_queue import TaskQueue
-
-queue = TaskQueue()
-
-# 標記任務為執行中
-queue.start_task("TASK_150", agent_id="agent_001")
-
-# 標記任務完成
-queue.complete_task("TASK_150", commit_hash="abc1234")
-
-# 封存任務
-queue.archive_task("TASK_150")
-```
-
-## Scope 定義最佳實踐
-
-### ✅ 正確的 Scope
-
-```yaml
-scope:
-  - src/api/auth/          # 目錄層級（包含所有子文件）
-  - src/models/user.py     # 特定文件
-  - tests/api/test_auth.py # 測試文件
-```
-
-### ❌ 錯誤的 Scope
-
-```yaml
-scope:
-  - src/                   # 太廣泛（會與其他任務衝突）
-  - backend                # 不明確
-  - authentication         # 不是實際路徑
-```
-
-### Scope 衝突檢測
-
-```python
-from dev.pipeline.orchestrator.lock_manager import LockManager
-
-lock_mgr = LockManager()
-
-# 檢查兩個任務是否衝突
-conflict = lock_mgr.check_conflict(
-    scope_a=["src/api/auth/"],
-    scope_b=["src/api/"]  # 衝突！因為包含關係
-)
-```
-
-## 依賴管理
-
-### 定義依賴
-
-```yaml
-id: TASK_150
-dependencies:
-  - TASK_120  # User Model
-  - TASK_125  # Database Migration
-```
-
-### 依賴檢查
-
-```python
-from dev.pipeline.orchestrator.dependency_resolver import DependencyResolver
-
-resolver = DependencyResolver()
-
-# 檢查任務是否就緒
-ready = resolver.is_task_ready("TASK_150")
-
-# 獲取依賴鏈
-chain = resolver.get_dependency_chain("TASK_150")
-# 返回: [TASK_120, TASK_125, TASK_150]
-```
-
-### 循環依賴檢測
-
-```yaml
-# 錯誤範例（循環依賴）
-TASK_A:
-  dependencies: [TASK_B]
-
-TASK_B:
-  dependencies: [TASK_C]
-
-TASK_C:
-  dependencies: [TASK_A]  # 循環！
-```
-
-系統會自動檢測並拋出錯誤。
-
-## 驗收標準 (AC)
-
-### 格式
-
-```yaml
-acceptance_criteria:
-  - id: AC-150-1
-    description: "明確的完成條件"
-    test: "如何驗證（手動或自動測試）"
-    priority: critical  # critical, high, medium, low
-```
-
-### 範例
-
-```yaml
-acceptance_criteria:
-  - id: AC-150-1
-    description: "API 回應正確的 JWT token"
-    test: |
-      curl -X POST http://localhost:8000/api/auth/login \
-        -d '{"email":"test@example.com","password":"test123"}' \
-      應回傳 {"token": "eyJ..."}
-    priority: critical
-
-  - id: AC-150-2
-    description: "錯誤的密碼回傳 401"
-    test: "pytest tests/api/test_auth.py::test_login_invalid_password"
-    priority: high
-
-  - id: AC-150-3
-    description: "Token 過期後無法存取受保護 API"
-    test: "pytest tests/api/test_auth.py::test_token_expiry"
-    priority: medium
-```
-
-## 任務完成流程
-
-### 1. Agent 執行完成
-
-```bash
-# Agent 建立 commit
-git commit -m "[TASK_150] 實現用戶認證 API
-
-- 添加登入、註冊、Token 刷新端點
-- 實現 JWT 驗證中介軟體
-- 添加 bcrypt 密碼雜湊
-- 通過所有安全性測試
-
-Co-Authored-By: Dev Agent <noreply@anthropic.com>"
-```
-
-### 2. 更新 TASK_QUEUE.json
-
-```json
-{
-  "id": "TASK_150",
-  "status": "completed",
-  "assigned_to": "agent_001",
-  "started_at": "2026-02-09T10:30:00Z",
-  "completed_at": "2026-02-09T14:15:00Z",
-  "commit_hash": "abc1234",
-  "duration_hours": 3.75
-}
-```
-
-### 3. 封存任務
-
-```bash
-# 移動到 completed 目錄
-mv dev/pipeline/tasks/TASK_150_auth_api.yaml \
-   dev/pipeline/completed/TASK_150_auth_api.yaml
-```
-
-### 4. 更新 PROGRESS.md
-
-自動更新進度報告：
-- 移除待辦任務
-- 添加到已完成列表
-- 更新統計數據
-
-## 任務查詢
-
-### CLI 查詢
-
-```bash
-# 列出所有待執行任務
-cat dev/pipeline/TASK_QUEUE.json | jq '.tasks[] | select(.status=="pending")'
-
-# 列出高優先級任務
-cat dev/pipeline/TASK_QUEUE.json | jq '.tasks[] | select(.priority=="P1")'
-
-# 查看特定任務
-cat dev/pipeline/tasks/TASK_150_auth_api.yaml
-```
-
-### Python API
-
-```python
-from dev.pipeline.orchestrator.task_queue import TaskQueue
-
-queue = TaskQueue()
-
-# 獲取待執行任務
-pending = queue.get_pending_tasks()
-
-# 獲取高優先級任務
-high_priority = queue.get_tasks_by_priority("P1")
-
-# 查找特定任務
-task = queue.get_task("TASK_150")
-```
-
-## 任務統計
-
-```python
-from dev.pipeline.orchestrator.task_queue import TaskQueue
-
-queue = TaskQueue()
-stats = queue.get_statistics()
-
-print(f"總任務數: {stats['total']}")
-print(f"已完成: {stats['completed']}")
-print(f"執行中: {stats['in_progress']}")
-print(f"待執行: {stats['pending']}")
-print(f"完成率: {stats['completion_rate']}%")
-```
-
-## 故障排查
-
-### 任務無法開始
-
-**症狀**: 任務一直處於 pending 狀態
-
-**原因**:
-1. 依賴未完成
-2. 路徑被鎖定
-3. 優先級太低
-
-**檢查**:
-```python
-resolver = DependencyResolver()
-ready = resolver.is_task_ready("TASK_150")
-if not ready:
-    blocking = resolver.get_blocking_tasks("TASK_150")
-    print(f"被以下任務阻塞: {blocking}")
-```
-
-### Scope 衝突
-
-**症狀**: 多個 Agent 嘗試修改同一文件
-
-**檢查**:
-```bash
-cat dev/pipeline/LOCK_STATE.json
-```
-
-**解決**:
-1. 調整任務 scope
-2. 順序執行代替並行
-3. 等待衝突任務完成
-
-### 任務卡住
-
-**症狀**: 任務標記為 in_progress 但無進展
-
-**檢查**:
-```bash
-# 查看 Agent 狀態
-cat dev/pipeline/AGENT_STATE.json
-
-# 查看執行日誌
-cat dev/pipeline/logs/TASK_150_*.log
-```
-
-**解決**:
-1. 手動標記為 pending 重試
-2. 分派給其他 Agent
-3. 拆分成更小的任務
-
----
-
-**建立日期**: 2026-02-09
-**維護者**: Developer Team

package/core/dev/pipeline/docs/workflows.md

@@ -1,32 +0,0 @@
----
-type: reference
-title: Pipeline Workflows Reference
-description: Pipeline System 工作流程完整參考文檔
-tags: [pipeline, workflows, reference]
-audience: developer
----
-
-# Pipeline Workflows Reference
-
-> **狀態**: 📝 佔位符文檔 | **版本**: 1.0.0
-
-## TODO
-
-本文檔尚待完善，目前包含基本結構。
-
-### 計劃內容
-
-- [ ] 標準工作流程定義
-- [ ] 自定義工作流程建立
-- [ ] 工作流程引擎 API
-- [ ] 工作流程最佳實踐
-- [ ] 工作流程範例
-
-## 臨時參考
-
-請參閱 [Pipeline System 概覽](./overview.md) 了解工作流程的基本概念。
-
----
-
-**維護者**: Developer Team
-**最後更新**: 2026-02-09

package/core/dev/pipeline/orchestrator/schemas/task_queue_schema.json

@@ -1,58 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://kenaz-cortex.dev/schemas/task_queue.json",
-  "title": "Kenaz Cortex Task Queue Schema",
-  "description": "Schema for the task queue containing all tasks",
-  "type": "object",
-  "required": ["version", "tasks"],
-  "properties": {
-    "version": {
-      "type": "string",
-      "pattern": "^\\d+\\.\\d+\\.\\d+$",
-      "description": "Schema version (semver format)"
-    },
-    "project": {
-      "type": "string",
-      "description": "Project identifier"
-    },
-    "last_updated": {
-      "type": "string",
-      "format": "date-time",
-      "description": "Last update timestamp (ISO 8601)"
-    },
-    "statistics": {
-      "type": "object",
-      "description": "Queue statistics",
-      "properties": {
-        "total": { "type": "integer", "minimum": 0 },
-        "pending": { "type": "integer", "minimum": 0 },
-        "in_progress": { "type": "integer", "minimum": 0 },
-        "completed": { "type": "integer", "minimum": 0 },
-        "blocked": { "type": "integer", "minimum": 0 },
-        "cancelled": { "type": "integer", "minimum": 0 }
-      },
-      "additionalProperties": false
-    },
-    "tasks": {
-      "type": "array",
-      "items": { "$ref": "task_schema.json" },
-      "description": "Array of tasks in the queue"
-    },
-    "metadata": {
-      "type": "object",
-      "description": "Additional queue metadata",
-      "properties": {
-        "created_at": {
-          "type": "string",
-          "format": "date-time"
-        },
-        "source_spec": {
-          "type": "string",
-          "description": "Path to the product spec file"
-        }
-      },
-      "additionalProperties": true
-    }
-  },
-  "additionalProperties": false
-}

package/core/dev/pipeline/orchestrator/schemas/task_schema.json

@@ -1,139 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://kenaz-cortex.dev/schemas/task.json",
-  "title": "Kenaz Cortex Task Schema",
-  "description": "Schema for multi-agent collaboration task definition",
-  "type": "object",
-  "required": ["id", "title", "status", "priority"],
-  "properties": {
-    "id": {
-      "type": "string",
-      "pattern": "^TASK_\\d{3,}$",
-      "description": "Unique task identifier (e.g., TASK_001)"
-    },
-    "title": {
-      "type": "string",
-      "minLength": 1,
-      "maxLength": 200,
-      "description": "Brief task title"
-    },
-    "description": {
-      "type": "string",
-      "description": "Detailed task description"
-    },
-    "status": {
-      "type": "string",
-      "enum": ["pending", "in_progress", "completed", "blocked", "cancelled"],
-      "default": "pending",
-      "description": "Current task status"
-    },
-    "priority": {
-      "type": "string",
-      "enum": ["P0", "P1", "P2", "P3"],
-      "default": "P2",
-      "description": "Task priority (P0 = highest)"
-    },
-    "scope": {
-      "type": "object",
-      "description": "Path scope for the task",
-      "properties": {
-        "paths": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "Directories to lock (e.g., src/components/)"
-        },
-        "files": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "Specific files to lock"
-        }
-      },
-      "additionalProperties": false
-    },
-    "dependencies": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "pattern": "^TASK_\\d{3,}$"
-      },
-      "default": [],
-      "description": "List of task IDs that must complete first"
-    },
-    "assigned_agent": {
-      "type": "string",
-      "enum": [
-        "architect_agent",
-        "frontend_agent",
-        "backend_agent",
-        "qa_agent",
-        "sre_agent",
-        "optimization_agent",
-        "dev_agent"
-      ],
-      "description": "Agent assigned to execute this task"
-    },
-    "branch": {
-      "type": "string",
-      "pattern": "^task-\\d{3,}-[a-z0-9-]+$",
-      "description": "Git branch name for this task"
-    },
-    "created_at": {
-      "type": "string",
-      "format": "date-time",
-      "description": "Task creation timestamp (ISO 8601)"
-    },
-    "started_at": {
-      "type": ["string", "null"],
-      "format": "date-time",
-      "description": "Task start timestamp (ISO 8601)"
-    },
-    "completed_at": {
-      "type": ["string", "null"],
-      "format": "date-time",
-      "description": "Task completion timestamp (ISO 8601)"
-    },
-    "blocked_reason": {
-      "type": ["string", "null"],
-      "description": "Reason for blocked status"
-    },
-    "metadata": {
-      "type": "object",
-      "description": "Additional task metadata",
-      "properties": {
-        "estimated_hours": {
-          "type": "number",
-          "minimum": 0,
-          "description": "Estimated hours to complete"
-        },
-        "actual_hours": {
-          "type": ["number", "null"],
-          "minimum": 0,
-          "description": "Actual hours spent"
-        },
-        "commits": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "Git commit hashes related to this task"
-        },
-        "files_changed": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "List of files modified"
-        },
-        "test_coverage": {
-          "type": ["number", "null"],
-          "minimum": 0,
-          "maximum": 100,
-          "description": "Test coverage percentage"
-        },
-        "tags": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "Tags for categorization"
-        }
-      },
-      "additionalProperties": true
-    }
-  },
-  "additionalProperties": false
-}