kenaz 0.0.0-stage → 0.3.2

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

@@ -0,0 +1,600 @@
+# Formation Post-Complete - 任務完成後自動化
+
+> **專案位置**: `.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