kenaz 0.3.18 → 0.3.20

package/core/.system/formation/POST_COMPLETE.md

@@ -1,602 +0,0 @@
-# Formation Post-Complete - 任務完成後自動化
-
-> **[RETIRED CALLERS 2026-10, TASK_2401/2402/2403]** 文中的 legacy-scheduler.js / headless.js 呼叫端已移除，僅留作歷史參考；post-complete.js 本身仍存在。現行派工：`node .formation/tools/dispatch.js --skill=do --task=TASK_XXX --dispatch-mode=subagent`。
-
-> **專案位置**: `.formation/tools/post-complete.js`
-> **系統類型**: Formation Lead 專用工具
-> **適用場景**: 任務完成後的自動 Archive + Git 分支管理
-
----
-
-## 📋 系統概述
-
-**Post-Complete** 是 Formation Legacy Scheduler 的核心模組，負責**任務完成後的所有自動化處理**。它是 **Formation Lead 獨享的職責**，subagent 禁止執行 git 操作（Rule 5），確保 git 歷史乾淨、統一管理。
-
-### 核心理念
-
-**「Formation Lead = Scheduler + Post-Complete」**
-
-```
-Subagent 職責: 完成任務內容（檔案修改、程式碼實作）
-             ↓
-             task-api.js complete {task_id}
-             ↓
-Lead 職責:   post-complete.js --task={task_id}
-             ↓
-             Archive（清理舊任務）+ Git（分支管理）
-```
-
-**Rule 5（HEADLESS_PREFIX）**：
-```
-禁止執行任何 git 操作（commit、branch、merge、push）。
-Git 由 Formation Lead 統一管理。
-```
-
-這條規則確保：
-- ❌ Subagent 不會建立混亂的 commit 歷史
-- ✅ 所有 commit 由 Lead 統一格式化（Co-Authored-By: Claude）
-- ✅ 分支管理統一、可預測
-
----
-
-## 🎯 兩大核心職責
-
-### 1. Archive 清理（雙系統）
-
-**問題**：已完成任務積累過多，影響 Dashboard 效能、task-api 掃描速度
-
-**解決方案**：超過 `N` 個已完成任務時，自動將最舊的移到 `archived/` 目錄
-
-**雙系統支援**：
-- **新系統**：`.collaboration/tasks/done/` → `.collaboration/tasks/archived/`
-- **舊系統**：`dev/pipeline/completed/` → `dev/pipeline/archived/`
-
-**規則**：
-- 預設保留最新 **10 個**任務（可配置）
-- 超過數量時，將最舊的（TASK_ID 最小）移到 `archived/`
-- `archived/` 目錄**不被 task-api 和 Dashboard 掃描**（完全隱藏）
-
----
-
-### 2. Git 分支管理
-
-**問題**：統一 git 工作流程，避免 subagent 各自建立 commit 導致混亂
-
-**解決方案**：由 Formation Lead 統一執行以下流程：
-
-```
-1. 建立 task/task_xxx branch  ← 從當前分支分岔
-2. Stage + commit 所有變更    ← Co-Authored-By: Claude
-3. 切換/建立用戶分支（git user name，如 {git_user}）
-4. Merge task branch 到用戶分支（--no-ff）
-5. 留在用戶分支              ← 用戶手動 merge 到 main
-```
-
-**Git Flow 圖示**：
-```
-                    ┌─ task/task_205 (commit here)
-                    │
-main ─── commits ───┴─ {git_user} (merge here) ─── ...
-                                ↑
-                           Lead 停在這裡
-                                ↓
-                   用戶手動 merge 到 main
-```
-
-**為什麼不直接 merge 到 main？**
-- 保留用戶對 main 的控制權（可在 merge 前 review）
-- 避免自動化工具污染 main 分支
-- 用戶分支作為緩衝層，可隨時回退
-
----
-
-## ⚙️ 配置參數
-
-```javascript
-const CONFIG = {
-  // 新系統 (.collaboration)
-  COLLAB_DONE_DIR: '.collaboration/tasks/done',
-  COLLAB_ARCHIVED_DIR: '.collaboration/tasks/archived',
-
-  // 舊系統 (dev/pipeline)
-  LEGACY_COMPLETED_DIR: 'dev/pipeline/completed',
-  LEGACY_ARCHIVED_DIR: 'dev/pipeline/archived',
-
-  // Archive 保留數量
-  DEFAULT_KEEP: 10,
-};
-```
-
-**可在 CLI 覆蓋**：
-```bash
-node .formation/tools/post-complete.js --task=TASK_XXX --keep=15
-```
-
----
-
-## 🔧 核心功能
-
-### 1. Archive 清理
-
-#### archiveDir(doneDir, archivedDir, keep, dryRun)
-
-**流程**：
-1. 掃描 `doneDir`，找出所有 `TASK_*.yaml` 檔案
-2. 按 TASK_ID 數字排序（TASK_134 < TASK_135 < ...）
-3. 保留最新 `keep` 個，其餘移到 `archivedDir`
-4. 返回統計資訊：`{ archived: [], kept: [], total }`
-
-**範例**：
-```javascript
-// done/ 目錄有 15 個任務，keep=10
-const result = archiveDir('.collaboration/tasks/done', '.collaboration/tasks/archived', 10, false);
-
-// result = {
-//   archived: ['TASK_134.yaml', 'TASK_135.yaml', ..., 'TASK_138.yaml'], // 5 個舊任務
-//   kept: ['TASK_139.yaml', ..., 'TASK_148.yaml'], // 10 個新任務
-//   total: 15
-// }
-```
-
-#### archiveCheck({ keep, dryRun })
-
-**雙系統統一介面**：
-```javascript
-const result = archiveCheck({ keep: 10, dryRun: false });
-
-// result = {
-//   collab: { archived: [...], kept: [...], total: 8 },
-//   legacy: { archived: [...], kept: [...], total: 12 }
-// }
-```
-
-**輸出範例**：
-```
-── Archive Check ──
-   ✅ [新系統] done: 8/10 — no archive needed
-   📦 [舊系統] Archived 2 tasks (12 → 10):
-      → TASK_134_api_refactor.yaml
-      → TASK_135_ui_update.yaml
-```
-
----
-
-### 2. Git 分支管理
-
-#### gitBranchAndMerge({ taskId, message, dryRun })
-
-**完整流程**：
-
-```javascript
-const result = gitBranchAndMerge({
-  taskId: 'TASK_205',
-  message: '[TASK_205] Custom commit message', // 可選
-  dryRun: false
-});
-
-// result = {
-//   taskBranch: 'task/task_205',
-//   userBranch: '{git_user}',
-//   originalBranch: '{git_user}',
-//   committed: true,
-//   merged: true
-// }
-```
-
-**詳細步驟**：
-
-#### Step 0: 檢查是否有變更
-
-```javascript
-if (!hasChanges()) {
-  console.log('⚠️ No changes to commit');
-  return result;
-}
-```
-
-如果 `git status --porcelain` 是空的，直接返回（避免建立空 commit）。
-
-#### Step 0.5: Stash 未追蹤的髒檔案
-
-**問題**：某些檔案（如 `.cortex/db/chroma.sqlite3`）可能被 `.gitignore` 排除，但尚未提交，會阻止 `git checkout`。
-
-**解決方案**：
-```javascript
-const stashed = git('stash push -u -m "post-complete: auto-stash before checkout"', { throws: false });
-const didStash = stashed !== null && !stashed.includes('No local changes');
-```
-
-稍後在新分支上 `git stash pop` 恢復。
-
-#### Step 1: 建立 task branch
-
-```javascript
-const taskBranch = `task/${taskId.toLowerCase()}`; // e.g. "task/task_205"
-
-if (branchExists(taskBranch)) {
-  git(`checkout ${taskBranch}`);
-} else {
-  git(`checkout -b ${taskBranch}`);
-}
-```
-
-如果 branch 已存在（如重新執行），直接切換；否則建立新分支。
-
-#### Step 1.5: 恢復 Stash
-
-```javascript
-if (didStash) {
-  git('stash pop', { throws: false });
-}
-```
-
-#### Step 2: Stage + Commit（安全模式）
-
-**呼叫 `gitAddSafe()`**：
-
-```javascript
-gitAddSafe();  // 處理 Windows 保留檔名 + 重試機制
-execSync(`git commit -m "${commitMsg}\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"`);
-```
-
-**Commit Message 格式**：
-```
-[TASK_205] task completed
-
-Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
-```
-
-如果 commit 失敗（如沒有實際變更），回到原分支並返回。
-
-#### Step 3: 切換/建立用戶分支
-
-```javascript
-const gitUser = getGitUser();  // 從 git config user.email 取得（如 "{git_user}@example.com" → "{git_user}"）
-const userBranch = gitUser;
-
-if (branchExists(userBranch)) {
-  git(`checkout ${userBranch}`);
-} else {
-  // 從 main 建立用戶分支
-  const baseBranch = branchExists('main') ? 'main' : originalBranch;
-  git(`checkout -b ${userBranch} ${baseBranch}`);
-}
-```
-
-用戶分支命名規則：**git user.email 的 @ 前部分**（如 `{git_user}`）
-
-#### Step 4: Merge task branch 到用戶分支
-
-```javascript
-git(`merge ${taskBranch} --no-ff -m "Merge ${taskBranch} into ${userBranch}"`);
-```
-
-使用 `--no-ff`（no fast-forward）確保產生 merge commit，保留分支歷史。
-
-**如果有 merge conflict**：
-```javascript
-catch (e) {
-  git('merge --abort', { throws: false });
-  git(`checkout ${originalBranch}`, { throws: false });
-  return result; // merged: false
-}
-```
-
-自動 abort merge，回到原分支，通知用戶手動解決。
-
-#### Step 5: 留在用戶分支
-
-```javascript
-console.log(`📌 Now on branch: ${userBranch}`);
-console.log(`👉 Review changes, then: git checkout main && git merge ${userBranch}`);
-```
-
-**不自動 merge 到 main**，讓用戶保留控制權。
-
----
-
-### 3. Git 安全工具：gitAddSafe()
-
-**問題 1：Windows 保留檔名**
-- Windows 禁止建立檔名為 `nul`, `con`, `prn`, `aux`, `com1`~`com9`, `lpt1`~`lpt9` 的檔案
-- 但某些工具可能意外產生這些空檔（如 `nul.txt`），導致 `git add` 失敗
-
-**解決方案**：
-```javascript
-const WINDOWS_RESERVED = new Set([
-  'nul', 'con', 'prn', 'aux',
-  ...Array.from({ length: 9 }, (_, i) => `com${i + 1}`),
-  ...Array.from({ length: 9 }, (_, i) => `lpt${i + 1}`),
-]);
-
-// 掃描專案根目錄
-const entries = fs.readdirSync(ROOT);
-for (const entry of entries) {
-  const base = entry.toLowerCase().replace(/\.[^.]*$/, ''); // 移除副檔名
-  if (WINDOWS_RESERVED.has(base)) {
-    fs.unlinkSync(fullPath); // 直接刪除
-  }
-}
-```
-
-**問題 2：SQLite journal 暫存檔**
-- Chromadb 使用 SQLite，會產生 `chroma.sqlite3-journal` 暫存檔
-- 這些檔案在 `git add` 時可能**被 SQLite 刪除**，導致 `fatal: pathspec 'xxx-journal' did not match any files`
-
-**解決方案**：重試機制
-```javascript
-const MAX_RETRIES = 3;
-for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
-  const result = git('add -A', { throws: false });
-  if (result !== null) return; // success
-
-  // 失敗，等 500ms 讓暫存檔消失
-  const wait = Date.now() + 500;
-  while (Date.now() < wait) { /* busy wait */ }
-}
-
-// 最後一次用 throws: true
-git('add -A');
-```
-
----
-
-## 🚀 使用方式
-
-### 1. CLI 手動呼叫
-
-```bash
-# 完整流程（archive + git）
-node .formation/tools/post-complete.js --task=TASK_205
-
-# 自訂 commit message
-node .formation/tools/post-complete.js --task=TASK_205 --message "[TASK_205] Custom message"
-
-# 調整保留數量
-node .formation/tools/post-complete.js --task=TASK_205 --keep=15
-
-# 只做 archive（跳過 git）
-node .formation/tools/post-complete.js --skip-git
-
-# 只做 git（跳過 archive）
-node .formation/tools/post-complete.js --task=TASK_205 --skip-archive
-
-# Dry run（模擬執行，不修改檔案/git）
-node .formation/tools/post-complete.js --task=TASK_205 --dry-run
-```
-
-### 2. JavaScript API（由 Scheduler 自動呼叫）
-
-```javascript
-const { postComplete } = require('./.formation/tools/post-complete');
-
-// 由 legacy-scheduler.js 自動呼叫
-postComplete({ taskId: 'TASK_205' });
-
-// 自訂參數
-postComplete({
-  taskId: 'TASK_205',
-  keep: 15,
-  skipArchive: false,
-  skipGit: false,
-  message: '[TASK_205] Custom commit message'
-});
-```
-
----
-
-## 🔁 與 Legacy Scheduler 整合
-
-### Scheduler 工作流程
-
-```javascript
-// legacy-scheduler.js 的 runDevAgent 函數
-
-if (task.agentType === 'lead') {
-  // Lead-only 任務：Scheduler 自己處理
-  postComplete({ taskId: task.taskId, message: task.commitMessage });
-  execSync(`node .collaboration/core/task-api.js complete ${task.taskId}`);
-} else {
-  // 一般任務：派給 subagent
-  // 1. 調度 Formation Legacy Skill subagent
-  runWithFormation(task, skillName, config, logger);
-
-  // 2. Subagent 完成任務移動（task-api.js complete）
-  // （由 subagent 自行執行）
-
-  // 3. Scheduler 執行 post-complete
-  postComplete({ taskId: task.taskId });
-}
-```
-
-### 觸發時機
-
-**自動觸發**（Scheduler）：
-- 每個任務完成後（subagent 執行 `task-api.js complete` 後）
-- Scheduler 自動呼叫 `postComplete({ taskId })`
-
-**手動觸發**（CLI）：
-- 用戶手動執行 `node .formation/tools/post-complete.js --task=TASK_XXX`
-- 適用於補救（如 subagent 完成但 post-complete 失敗）
-
----
-
-## 📊 輸出範例
-
-### 成功執行（Archive + Git）
-
-```
-⚔️  Post-Complete: TASK_205
-   Keep: 10 | Archive: true | Git: true | DryRun: false
-
-── Archive Check ──
-   ✅ [新系統] done: 8/10 — no archive needed
-   📦 [舊系統] Archived 2 tasks (12 → 10):
-      → TASK_134_api_refactor.yaml
-      → TASK_135_ui_update.yaml
-
-── Git Branch & Merge ──
-   ✅ Committed on task/task_205
-   ✅ Merged task/task_205 → {git_user}
-   📌 Now on branch: {git_user}
-   👉 Review changes, then: git checkout main && git merge {git_user}
-
-── Summary ──
-   Archive [新]: 0 archived, 8 kept
-   Archive [舊]: 2 archived, 10 kept
-   Git: branch=task/task_205 committed=true merged=true
-   👉 On branch: {git_user} — merge to main when ready
-```
-
-### Dry Run（模擬執行）
-
-```
-⚔️  Post-Complete: TASK_205
-   Keep: 10 | Archive: true | Git: true | DryRun: true
-
-── Archive Check ──
-   [DRY RUN] Would archive 2 tasks from legacy/completed/
-
-── Git Branch & Merge ──
-   [DRY RUN] Would create branch: task/task_205
-   [DRY RUN] Would commit: [TASK_205] task completed
-   [DRY RUN] Would merge to: {git_user}
-
-── Summary ──
-   (Dry run - no changes made)
-```
-
-### 無變更（Nothing to commit）
-
-```
-⚔️  Post-Complete: TASK_205
-   Keep: 10 | Archive: true | Git: true | DryRun: false
-
-── Archive Check ──
-   ✅ [新系統] done: 8/10 — no archive needed
-   ✅ [舊系統] completed: 10/10 — no archive needed
-
-── Git Branch & Merge ──
-   ⚠️  No changes to commit
-
-── Summary ──
-   Archive [新]: 0 archived, 8 kept
-   Archive [舊]: 0 archived, 10 kept
-   Git: branch=task/task_205 committed=false merged=false
-```
-
-### Merge Conflict（衝突）
-
-```
-⚔️  Post-Complete: TASK_205
-   Keep: 10 | Archive: true | Git: true | DryRun: false
-
-── Archive Check ──
-   ✅ [新系統] done: 8/10 — no archive needed
-   ✅ [舊系統] completed: 10/10 — no archive needed
-
-── Git Branch & Merge ──
-   ✅ Committed on task/task_205
-   ❌ Merge conflict! Resolve manually.
-
-── Summary ──
-   Archive [新]: 0 archived, 8 kept
-   Archive [舊]: 0 archived, 10 kept
-   Git: branch=task/task_205 committed=true merged=false
-   👉 Resolve conflict manually, then retry
-```
-
----
-
-## 🛡️ 安全性與錯誤處理
-
-### 1. Git Stash（防止 checkout 失敗）
-
-**問題**：`.gitignore` 排除的髒檔案（如 `.cortex/db/chroma.sqlite3`）會阻止 `git checkout`。
-
-**解決方案**：
-```javascript
-// 0.5. Stash untracked dirty files
-git('stash push -u -m "post-complete: auto-stash before checkout"');
-// ... checkout to task branch ...
-git('stash pop'); // 恢復
-```
-
-### 2. Windows 保留檔名清理
-
-**問題**：`nul`, `con`, `prn` 等檔案會導致 `git add` 失敗。
-
-**解決方案**：掃描並刪除（`gitAddSafe()`）
-
-### 3. SQLite Journal 重試機制
-
-**問題**：暫存檔在 `git add` 時消失，導致 `fatal: pathspec 'xxx-journal' did not match any files`。
-
-**解決方案**：最多重試 3 次，每次間隔 500ms
-
-### 4. Merge Conflict 自動 Abort
-
-**問題**：自動 merge 可能產生衝突。
-
-**解決方案**：自動 `git merge --abort`，回到原分支，通知用戶手動解決
-
----
-
-## 🔧 Lead-only 任務
-
-**特殊任務類型**：role 為 `lead` 的任務，由 Scheduler 自己處理（不派給 subagent）
-
-**範例任務定義**（`TASK_XXX.yaml`）：
-```yaml
-id: TASK_999
-title: "Archive 舊任務到 .memory/"
-role: lead              # ← 關鍵：role: lead
-status: pending
-priority: P2
-dependencies: []
-scope_paths: [".collaboration/tasks/done/"]
-requirements:
-  - "將 done/ 中超過 20 個的舊任務移到 archived/"
-acceptance_criteria:
-  - "done/ 目錄保留最新 10 個任務"
-commit_message: "[TASK_999] Archive 舊任務"
-```
-
-**Scheduler 執行流程**：
-```javascript
-if (task.agentType === 'lead') {
-  // Lead-only 任務：Scheduler 自己處理
-  postComplete({ taskId: task.taskId, message: task.commitMessage });
-  execSync(`node .collaboration/core/task-api.js complete ${task.taskId}`);
-}
-```
-
-**適用場景**：
-- Archive 清理（單獨執行，不需要 subagent）
-- Git branch/merge 操作（Scheduler 專屬）
-- 系統維護任務（如清理 log、備份等）
-
----
-
-## 🔗 相關文檔
-
-| 文檔 | 路徑 | 說明 |
-|------|------|------|
-| **Formation 系統概述** | `.system/formation/README.md` | 陣型選擇指南 |
-| **Legacy Scheduler** | `.formation/tools/legacy-scheduler.js` | Scheduler 實作 |
-| **Legacy Skills** | `.system/formation/LEGACY_SKILLS.md` | 全角色定義 |
-| **Headless Runner** | `.formation/tools/headless.js` | 無頭啟動器 |
-| **Task API** | `.collaboration/core/task-api.js` | 任務管理 API |
-
----
-
-## 📝 版本歷史
-
-- **v1.0** (2026-02-18): 初始版本，支援雙系統 Archive + Git 分支管理
-- **v1.1** (2026-02-19): 新增 gitAddSafe（Windows 保留檔名 + SQLite journal 重試）
-- **v1.2** (2026-02-20): 新增 Git Stash 機制（防止 checkout 失敗）
-
----
-
-**維護者**: Developer Team
-**相關任務**: TASK_218