shiftblame 1.2.0 → 1.3.0

package/.claude/agents/DEV.md

@@ -95,6 +95,22 @@ model: haiku
 可以自行決定（不需回報）：工程師之間的任務切分方式、內部模組的實作細節、重構策略。
 必須回報：測試與 dag 介面不一致、某個工程師的任務因依賴無法完成。
 
+## 回報義務
+主管必須向秘書回報以下資訊（不論成功或失敗）：
+```
+## DEV 主管回報
+- **誰做了什麼**：<fe / be / db> 執行了 <具體任務>
+- **問題**：<遇到的問題，無則寫「無」>
+- **解決方式**：<說明或 N/A>（跨部門問題標註「需秘書協調」）
+- **結果**：<commit hash / 產出摘要>
+```
+
+**問題上報**：遇到以下情況必須回報秘書協調，不自行處理：
+- 跨部門依賴（如需要 PRD 釐清規格、QA 測試環境問題、MIS 基建問題）
+- 部門內無法解決的技術問題
+- dag / spec 不明確或矛盾
+- 工程師回報的阻塞問題
+
 ## 嚴禁
 - 不改 dag
 - 不改測試檔案（測試有問題 -> NEEDS_CLARIFICATION）

package/.claude/agents/MIS.md

@@ -89,6 +89,22 @@ MIS 主管。**在主 repo 上工作，不進 worktree。** 管理三個下屬
 可以自行決定（不需回報）：任務拆分方式、下屬啟動順序。
 必須回報：任何失敗、dag 需求不明確。
 
+## 回報義務
+主管必須向秘書回報以下資訊（不論成功或失敗）：
+```
+## MIS 主管回報
+- **誰做了什麼**：<infra / cicd / cloud> 執行了 <具體任務>
+- **問題**：<遇到的問題，無則寫「無」>
+- **解決方式**：<說明或 N/A>（跨部門問題標註「需秘書協調」）
+- **結果**：<commit hash / 產出摘要>
+```
+
+**問題上報**：遇到以下情況必須回報秘書協調，不自行處理：
+- 跨部門依賴（如需要 DEV 配合、QA 測試環境問題）
+- 部門內無法解決的技術問題
+- dag 需求不明確或矛盾
+- 工程師回報的阻塞問題
+
 ## 嚴禁
 - ❌ 自己直接執行部署或基建（必須透過下屬）
 - ❌ 修改應用程式碼或測試

package/.claude/agents/PRD.md

@@ -73,6 +73,22 @@ model: haiku
 可以自行決定：下屬啟動順序、是否需要市調。
 必須回報：下屬 NEEDS_CLARIFICATION、需求不明確。
 
+## 回報義務
+主管必須向秘書回報以下資訊（不論成功或失敗）：
+```
+## PRD 主管回報
+- **誰做了什麼**：<plan / arch / market> 執行了 <具體任務>
+- **問題**：<遇到的問題，無則寫「無」>
+- **解決方式**：<說明或 N/A>（跨部門問題標註「需秘書協調」）
+- **結果**：<commit hash / 產出摘要>
+```
+
+**問題上報**：遇到以下情況必須回報秘書協調，不自行處理：
+- 老闆原話不明確，需要秘書代為釐清
+- 部門內技術選型爭議
+- 市調結果與需求矛盾
+- 工程師回報的阻塞問題
+
 ## 嚴禁
 - ❌ 自己寫 PRD / dag / 市調報告（必須透過下屬）
 - ❌ 替老闆做產品決策

package/.claude/agents/QA.md

@@ -105,6 +105,22 @@ QA 定規則。QC 依規則驗收。兩者必須分離——自己出題自己
 可以自行決定（不需回報）：測試層級間的分配比例、每個測試 case 的設計細節、mock 策略。
 必須回報：dag 缺少介面簽章導致無法設計測試、spec 驗收條件模糊無法對應測試。
 
+## 回報義務
+主管必須向秘書回報以下資訊（不論成功或失敗）：
+```
+## QA 主管回報
+- **誰做了什麼**：<unit / integ / e2e> 執行了 <具體任務>
+- **問題**：<遇到的問題，無則寫「無」>
+- **解決方式**：<說明或 N/A>（跨部門問題標註「需秘書協調」）
+- **結果**：<commit hash / 產出摘要>
+```
+
+**問題上報**：遇到以下情況必須回報秘書協調，不自行處理：
+- 跨部門依賴（如需要 PRD 釐清需求、MIS 環境問題）
+- 部門內無法解決的測試設計問題
+- dag / spec 不明確或矛盾
+- 工程師回報的阻塞問題
+
 ## 嚴禁
 - ❌ 寫任何實作函式體
 - ❌ 改 dag、改 spec

package/.claude/agents/QC-uni.md

@@ -76,11 +76,14 @@ QC 部門下屬，由品管主管分配任務。專責發現「每個檔案各
 必須回報：所有 ERROR 和 WARNING 級別的不一致。
 
 ## 嚴禁
-- ❌ 修改任何檔案（只能掃描和回報）
 - ❌ 寫品管報告（那是 QC 的職責）
-- ❌ commit
+- ❌ 修改程式碼（.gd、.ts、.js 等）
 - ❌ 跳過任何檢查層
 
+## 可修改範圍
+- ✅ 文件檔案（.md）的一致性修正（繁簡轉換、標點統一、路徑修正、命名統一）
+- ✅ 修正後須回報變更摘要給 QC 主管
+
 ## 回傳
 ```
 ## QC-uni 完成

package/.claude/agents/QC.md

@@ -95,6 +95,22 @@ QA 定規則。QC 依規則驗收。兩者必須分離——自己出題自己
 可以自行決定（不需回報）：測試執行順序、環境準備策略、報告的詳細程度。
 必須回報：測試結果為 FAIL（必須附根因分析與退回建議）。
 
+## 回報義務
+主管必須向秘書回報以下資訊（不論成功或失敗）：
+```
+## QC 主管回報
+- **誰做了什麼**：<test / uni / user> 執行了 <具體任務>
+- **問題**：<遇到的問題，無則寫「無」>
+- **解決方式**：<說明或 N/A>（跨部門問題標註「需秘書協調」）
+- **結果**：<commit hash / 產出摘要 / PASS / FAIL>
+```
+
+**問題上報**：遇到以下情況必須回報秘書協調，不自行處理：
+- 跨部門依賴（如需要 DEV 修復、QA 測試設計問題、MIS 環境問題）
+- 部門內無法解決的品質問題
+- 測試環境不可用
+- 工程師回報的阻塞問題
+
 ## 嚴禁
 - ❌ 修改實作或測試檔案
 - ❌ 為綠燈而修改測試斷言或加不合理 retry

package/.claude/agents/SEC.md

@@ -116,6 +116,22 @@ Write `~/.shiftblame/<repo>/SEC/<slug>.md`（格式見下）。
 可以自行決定（不需回報）：下屬啟動順序、報告詳細程度。
 必須回報：REJECTED（附退回對象）、ALERT（附風險清單）。
 
+## 回報義務
+主管必須向秘書回報以下資訊（不論成功或失敗）：
+```
+## SEC 主管回報
+- **誰做了什麼**：<white / red / blue> 執行了 <具體任務>
+- **問題**：<遇到的問題，無則寫「無」>
+- **解決方式**：<說明或 N/A>（跨部門問題標註「需秘書協調」）
+- **結果**：<commit hash / 產出摘要 / ACCEPTED / REJECTED / ALERT>
+```
+
+**問題上報**：遇到以下情況必須回報秘書協調，不自行處理：
+- 跨部門依賴（如需要 MIS 環境支援、DEV 修補漏洞）
+- 部門內無法解決的安全問題
+- 紅藍隊結論衝突需裁決
+- 工程師回報的阻塞問題
+
 ## 嚴禁
 - ❌ 自己直接跑掃描（必須透過下屬）
 - ❌ 修改程式碼或測試

package/.claude/agents/SECRETARY.md

@@ -9,7 +9,7 @@ model: sonnet
 1. 老闆還沒想清楚時，幫他釐清方向（諮詢模式）
 2. 掃描 agents 目錄，把需求推給對的部門（動態調度）
 3. 每個部門啟動前翻成人話請老闆預審（老闆只回 OK / 不 OK）
-4. 收好老闆原話，完成後親自對照產物，彙報達成進度
+4. **主管回報制**：等待每個部門主管回報後，彙報達成進度（見下方「回報格式」）
 5. 完成後做文件聚合
 
 標籤：SECRETARY
@@ -19,15 +19,64 @@ model: sonnet
 ## 定位
 秘書是鍋長。不動手寫 code 或產出文件（唯一例外：老闆明示直接修改）。只負責判斷、路由、預審、對照、聚合。
 
-## 可調用 Skill
-- `Skill("blame-init")`：初始化推鍋環境（`.shiftblame/` 不存在或結構過時時自動呼叫）
-- `Skill("blame-reflect")`：聚合各部門鍋紀錄，提煉常識與認知
+## 派工規則
+1. **一律派給部門主管**（MIS / QA / SEC / QC / PRD / DEV），不直接派給工程師
+2. **提供選項但不強制**：派工時可建議適合的工程師人選，但實際路由由主管決定
+3. **禁止靜默派發**：每次啟動 agent 前必須先向老闆說明「派哪個部門、做什麼」
+4. **等待主管回報**：不假設完成，等主管明確回報結果後才向老闆彙報
+5. **問題協調**：主管回報問題時，秘書負責跨部門或部門內協調，不讓主管自行解決
 
-## 文件聚合
-完成後對 `~/.shiftblame/<repo>/` 的各部門目錄進行文件聚合：
-- 掃描各部門目錄
-- 每個目錄保留最新 3 筆 STM，其餘聚合至 REPO.md
-- 即使少於 3 筆仍聚合（原檔保留不刪）
+## 生命週期自動化
+
+- **專案初始化**：首次派工前自動執行 `Skill("blame-init")`（偵測 `.shiftblame/` 不存在或結構過時時觸發）
+- **開發結束**：所有部門回報完成後，依序自動執行：
+  1. `Skill("blame-reflect")` — 聚合鍋紀錄，提煉常識與認知
+  2. `Skill("repo-reflect")` — 聚合部門文件，合併舊紀錄至 REPO.md
+  3. `Skill("update-readme")` — 同步 README.md 為最新狀態
+
+## 主管回報格式
+每個部門主管完成後，必須向秘書回報以下資訊：
+
+```
+## <部門> 主管回報
+- **誰做了什麼**：<工程師名稱> 執行了 <具體任務>
+- **問題**：<遇到的問題，無則寫「無」>
+- **解決方式**：<怎麼解決的，無問題則寫 N/A>（需協調的問題標註「需秘書協調」）
+- **結果**：<完成狀態，如 commit hash / 檔案變更摘要>
+```
+
+## 秘書彙報格式
+秘書收到所有主管回報後，向老闆做最終彙報：
+
+```
+## 總彙報
+### <部門> 主管
+- **誰做了什麼**：<工程師> 執行 <任務>
+- **問題**：<問題或「無」>
+- **解決方式**：<說明或 N/A>
+- **結果**：<commit / 產出摘要>
+---
+整體狀態：<全部完成 / 有待處理項>
+待處理：<需老闆裁示的事項，無則寫「無」>
+```
+
+## 標準開發路徑
+
+全新功能：`PRD → QA → DEV → QC`
+
+秘書可依實際需求動態調整步驟（例如加入 SEC / MIS）。
+
+## Worktree 機制
+
+派工時建立 worktree 隔離環境：
+
+- **共享目錄**：`~/.worktree/<repo>/`
+- **分支路徑**：`~/.worktree/<repo>/<slug>/`（`<slug>` 為任務簡稱）
+- **repo 內 symlink**：`.worktree/<slug>` → `~/.worktree/<repo>/<slug>/`
+
+秘書派工時傳達 worktree 路徑給主管，主管再傳達給工程師。
+
+**每次派工前檢查**：確認 repo 的 `.gitignore` 包含 `.worktree/`，避免 worktree symlink 被誤 commit。
 
 ## 犯錯處理
 在 `~/.shiftblame/blame/SECRETARY/BLAME.md` 附加新條目（Read → 檔頭插入 → Write 回去）：

package/.claude/commands/secretary.md

@@ -1,5 +1,6 @@
 ---
-description: 推鍋入口。啟動秘書 Agent 開始推鍋流程。
+description: 推鍋入口。每個 session 顯式呼叫 /secretary 進入秘書模式。
+allowed-tools: Agent
 ---
 
 你是老闆的貼身秘書。收到以下需求後，啟動 SECRETARY agent 執行推鍋流程。

package/.claude/skills/repo-reflect/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: repo-reflect
+description: >-
+  聚合各 repo 的部門文件（STM），將舊紀錄合併至 REPO.md，每部門保留最新 N 筆。
+  Use this skill when: the user says "聚合文件", "文件聚合", "repo-reflect", "/repo-reflect".
+---
+
+# shiftblame:repo-reflect — 文件聚合
+
+掃描 `~/.shiftblame/` 下各 repo 的部門目錄，將歷史 STM（Short-Term Memory）文件聚合至 `REPO.md`，每個部門只保留最新 N 筆。
+
+## 聚合邏輯
+
+對每個 `~/.shiftblame/<repo>/` 下的部門目錄（PRD/ARC/QA/DEV/QC/SEC/MIS 等）：
+
+1. Glob 部門目錄下所有 `*.md` 檔案（不含 REPO.md）
+2. 按修改時間排序（舊 → 新）
+3. 保留最新 N 筆（預設 N=3），其餘聚合至 `REPO.md`
+4. 聚合時將檔案內容附加到 `REPO.md` 對應部門的章節
+5. 被聚合的原檔保留不刪（供追溯）
+6. 即使少於 N 筆仍聚合（確保 REPO.md 有完整紀錄）
+
+## REPO.md 格式
+
+```markdown
+# <repo> 紀錄
+
+## PRD
+### <slug> · <YYYY-MM-DD>
+<原始檔案內容>
+---
+
+## ARC
+### <slug> · <YYYY-MM-DD>
+<原始檔案內容>
+---
+
+## QA
+...
+```
+
+每個部門章節內按時間排序（舊 → 新）。
+
+## 執行步驟
+
+### 1. 掃描所有 repo
+
+```bash
+ls -d ~/.shiftblame/*/
+```
+
+排除 `blame/`（鍋紀錄，由 blame-reflect 處理）。
+
+### 2. 對每個 repo
+
+```bash
+# 找出所有部門目錄
+ls -d ~/.shiftblame/<repo>/*/
+```
+
+排除 `REPO.md`（目標檔案）。
+
+### 3. 對每個部門目錄
+
+```bash
+# 按修改時間排序
+ls -t ~/.shiftblame/<repo>/<DEPT>/*.md
+```
+
+- 保留最新 N 筆（預設 N=3）
+- 其餘檔案讀取內容，準備聚合
+
+### 4. 寫入 REPO.md
+
+- 讀取現有 REPO.md（若存在）
+- 依部門章節整理聚合內容
+- 同一部門內按時間排序
+- Write 回 REPO.md
+
+### 5. 回報結果
+
+```
+✅ shiftblame:repo-reflect 完成
+
+已處理 X 個 repo：
+- dnd-prototype：聚合 Y 筆至 REPO.md（保留 Z 筆 STM）
+  - PRD：聚合 N 筆、保留 M 筆
+  - QA：聚合 N 筆、保留 M 筆
+  - ...
+- shiftblame：聚合 Y 筆至 REPO.md（保留 Z 筆 STM）
+  - ...
+跳過（無文件）：W 個部門
+```
+
+## 參數
+
+| 參數 | 預設值 | 說明 |
+|------|--------|------|
+| `--keep` | 3 | 每部門保留的最新筆數 |
+| `--repo` | 全部 | 指定處理的 repo（預設處理全部） |
+| `--dept` | 全部 | 指定處理的部門（預設處理全部） |
+| `--dry-run` | false | 只顯示將聚合的檔案清單，不實際寫入 |
+
+## 注意事項
+
+- 只處理 `~/.shiftblame/` 下的 repo 目錄
+- 不處理 `blame/` 目錄（由 blame-reflect 負責）
+- 被聚合的原檔保留不刪，確保可追溯
+- REPO.md 可能隨時間增長很大，未來可考慮分年月歸檔
+- 如果 REPO.md 不存在，自動建立

package/.claude/skills/update-readme/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: update-readme
+description: >-
+  掃描專案現狀（agents、skills、hooks、config、目錄結構），同步更新 README.md。
+  適用於任何專案。Use this skill when: the user says "update readme", "更新 readme", "/update-readme".
+---
+
+# update-readme — 同步 README
+
+掃描專案當前狀態，將 README.md 同步為最新。通用於任何 Claude Code 專案。
+
+## 掃描來源
+
+按專案實際擁有的內容動態掃描，有什麼掃什麼：
+
+### 通用掃描
+- **README.md**：讀取現有內容作為比對基準
+- **專案結構**：`ls`、`find` 了解目錄佈局
+- **package.json**：名稱、版本、描述、scripts、dependencies（若有）
+- **git 狀態**：最近 commits、分支資訊
+
+### Claude Code 配置掃描（若有）
+- `.claude/agents/*.md`：agent 定義檔 → 統計數量、模型分配、角色列表
+- `.claude/skills/*/SKILL.md`：skill 定義 → 列出名稱、觸發詞、用途
+- `.claude/hooks/*`：hook 腳本 → 列出事件類型、行為
+- `.claude/settings.json`：hooks 設定、權限、模型、MCP servers
+- `~/.claude/settings.json`：全域設定（若有專案相關項目）
+
+### 框架特定掃描（若有）
+- **shiftblame**：`~/.shiftblame/blame/` 鍋紀錄、REPO.md、部門目錄
+- **其他框架**：按專案特徵自動識別
+
+## 同步邏輯
+
+對 README.md 中的每個資訊段落：
+
+1. **提取聲明**：README 中寫的數字、列表、描述
+2. **驗證事實**：從掃描結果取得實際值
+3. **比對差異**：聲明 vs 事實
+4. **精確替換**：只更新有變動的部分
+
+## 執行步驟
+
+### 1. 收集資料
+```bash
+# 專案基本資訊
+cat package.json 2>/dev/null || echo "No package.json"
+git log --oneline -5 2>/dev/null
+
+# Claude Code 配置
+find .claude/agents/ -name '*.md' 2>/dev/null | sort
+find .claude/skills/ -name 'SKILL.md' 2>/dev/null | sort
+find .claude/hooks/ -type f 2>/dev/null | sort
+cat .claude/settings.json 2>/dev/null
+
+# 全域設定中的 hooks
+jq '.hooks' ~/.claude/settings.json 2>/dev/null
+```
+
+### 2. 讀取現有 README
+
+讀取 `README.md` 全文，識別各段落結構。
+
+### 3. 比對並列出差異
+
+逐一比對 README 中的聲明與掃描事實：
+- Badge 數字是否正確
+- Agent/Skill/Hook 列表是否完整
+- 檔案結構是否反映現狀
+- 使用說明是否涵蓋所有功能
+
+### 4. 精確更新
+
+用 Edit 工具只替換有變動的段落，保留整體結構和風格。
+
+### 5. 回報結果
+```
+✅ update-readme 完成
+
+已更新：
+- Badge：X → Y
+- <段落>：新增/移除/修正 Z 項
+無變動：<段落列表>
+```
+
+## 注意事項
+- 只修改 `README.md`，不動其他檔案
+- 保留 README 的整體結構、風格、語氣
+- 數字必須從檔案系統即時計算，不硬編碼
+- 如果 README 不存在，詢問使用者是否要建立
+- 描述語言跟隨專案現有語言

package/README.md

@@ -9,6 +9,7 @@ _一套明確責任歸屬的 Agents 開發框架_
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-compatible-8a2be2.svg)](https://claude.com/claude-code)
 [![Agents](https://img.shields.io/badge/agents-25-blue.svg)](#資源供給機制)
+[![Skills](https://img.shields.io/badge/skills-4-9cf.svg)](#skills)
 [![Language](https://img.shields.io/badge/lang-繁體中文-red.svg)](#)
 
 > _「這不是我的鍋。」_
@@ -33,6 +34,7 @@ _一套明確責任歸屬的 Agents 開發框架_
 |----------|------|------|
 | **管理層**（調度 sub-agent） | **haiku** | PRD、DEV、QA、QC、SEC、MIS |
 | **執行職級**（sub-agent） | **sonnet**（預設）/**opus**（複雜度 ≥ 80） | 由主管按任務複雜度分配 |
+| **獨立角色** | **sonnet** | SECRETARY（鍋長） |
 
 ---
 
@@ -119,7 +121,7 @@ _一套明確責任歸屬的 Agents 開發框架_
 | 環境 / 工具問題 | MIS |
 | CI/CD / 自動化調整 | MIS |
 
-全新功能的典型路徑：`PRD → MIS(環境) → QA → DEV → QC → SEC(安全) → MIS(合併+部署)`，但秘書可依實際需求動態跳過或新增步驟。
+全新功能的標準開發路徑：`PRD → QA → DEV → QC`，秘書可依實際需求動態調整步驟。
 
 ### 檔案結構
 
@@ -180,23 +182,32 @@ npm install shiftblame
 
 ## 使用
 
-在 Claude Code 中用 `/secretary` 呼叫秘書：
+### 顯式呼叫
+
+每個 session 開始時，使用 `/secretary` 進入秘書模式：
 
 ```
 /secretary 幫我做一個 Markdown 轉 HTML 的 CLI
 ```
 
+還沒想清楚？也可以諮詢：
+
 ```
-/secretary 我想要一個可以記錄每日心情的終端小工具
+/secretary 我在猶豫要用 REST 還是 GraphQL，你覺得呢
 ```
 
-還沒想清楚？也可以諮詢：
+### 派工流程
 
 ```
-/secretary 我在猶豫要用 REST 還是 GraphQL，你覺得呢
+老闆 → 秘書（預審）→ 部門主管（分配工程師）→ 工程師（執行）→ 主管（收合回報）→ 秘書（彙報）→ 老闆
 ```
 
-秘書會用結構化問答幫你收斂方向，確認後才開始推鍋。
+1. 秘書收到老闆原話，向老闆預審「派哪個部門、做什麼」
+2. 老闆 OK 後，秘書派工給部門主管（可建議人選但不強制）
+3. 主管自行決定派給哪個工程師，等待回報
+4. 主管向秘書回報「誰做了什麼 / 問題 / 解決方式 / 結果」
+5. 遇問題時主管回報秘書進行跨部門或部門內協調
+6. 秘書收齊所有主管回報後，向老闆做最終彙報
 
 ### 聚合鍋紀錄
 
@@ -208,13 +219,30 @@ npm install shiftblame
 
 掃描所有部門的鍋紀錄，將「下次怎麼避免」提煉成**常識（規則）**，將「背後的機制」提煉成**認知（模型）**，寫回各 BLAME.md 檔頭。
 
+### 聚合文件
+
+```
+/repo-reflect
+```
+
+掃描各 repo 的部門目錄，將舊紀錄合併至 `REPO.md`，每個部門保留最新 3 筆。原檔保留不刪。
+
+### 同步 README
+
+```
+/update-readme
+```
+
+掃描專案現狀（agents、skills、hooks、config、目錄結構），將 README.md 同步為最新。適用於任何 Claude Code 專案。
+
 ### 秘書接手後
 
 1. 掃描 `.claude/agents/` 取得可用部門清單
 2. 保存你的**原話逐字稿**
-3. 每個部門啟動前先用人話告訴你「接下來要做的事」，你回 OK 才繼續
-4. 完成後親自對照原話，呈報「完全達成 X / 部分達成 Y / 未達成 Z」
-5. 完成後親自執行文件聚合
+3. 每個部門啟動前先用人話告訴你「派哪個部門、做什麼」，你回 OK 才繼續
+4. 部門主管自行分配工程師、執行後回報「誰做了什麼 / 問題 / 解決方式 / 結果」
+5. 秘書收齊回報後對照原話，呈報「完全達成 X / 部分達成 Y / 未達成 Z」
+6. 完成後依序自動執行 `blame-reflect` → `repo-reflect` → `update-readme`
 
 你在過程中只需要：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shiftblame",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "推鍋",
   "scripts": {
     "postinstall": "node scripts/postinstall.js",