docs: add paperclip dev review notes

docs/INDEX.md

@@ -10,6 +10,7 @@
 | [pipelines.md](pipelines.md) | 量化 Pipeline 流程、排程定義（8 routines）、每日/每週時間軸、審批機制、模型分級、成本控制、停損信號 |
 | [schemas.md](schemas.md) | 所有 Agent 輸出的 JSON Schema 定義（含信心指數、恐慌指數、進出場建議） |
 | [paperclip_org_plans.md](paperclip_org_plans.md) | Paperclip 導向的組織與人員配置規劃方案，含 3 種落地選項、推薦方案、修改範圍與 review 驗收標準 |
+| [paperclip_dev_review_2026-04-11.md](paperclip_dev_review_2026-04-11.md) | `origin/dev` 第一版 Paperclip package 的審查備忘錄，列出必修問題、建議修法與驗收標準 |
 
 ---
 

docs/paperclip_dev_review_2026-04-11.md

@@ -0,0 +1,240 @@
+# KingClawArmy - Paperclip Package Review（dev）
+
+> 日期：2026-04-11
+> 審查對象：`origin/dev`
+> 審查 commit：`43c1770`
+> 用途：提供另一個 agent 依此修正 Paperclip package；本文件聚焦在匯入後行為與規格一致性
+
+---
+
+## 1. 結論摘要
+
+`dev` branch 已經完成第一版 Paperclip package 骨架，且可通過：
+
+```bash
+paperclipai company import <repo> --dry-run --json
+```
+
+這代表以下基礎能力已具備：
+
+1. repo root 已有 `COMPANY.md`
+2. 已有 `.paperclip.yaml`
+3. 已有 `agents/`、`teams/`、`projects/`、`tasks/`、`skills/` 基本結構
+4. importer 可以成功解析 package
+
+但目前仍有幾個會影響「匯入後是否符合設計意圖」的問題，需要先修再進下一步。
+
+---
+
+## 2. 必修問題
+
+### P1. 07:30 主排程沒有綁到真正的 recurring task
+
+**現況**
+
+- `.paperclip.yaml` 的 routine key：`daily-quant-pipeline`
+- recurring task slug：`daily-quant-run`
+
+參考：
+
+- `origin/dev:.paperclip.yaml` 第 85-91 行
+- `origin/dev:projects/daily-quant-pipeline/tasks/daily-quant-run/TASK.md`
+
+**影響**
+
+`paperclipai company import --dry-run --json` 的結果顯示：
+
+- `daily-quant-run` 的 `routine` 是 `null`
+
+也就是說，這個每日量化啟動任務匯入後不會自動被排程觸發。
+
+**建議修法**
+
+二選一，選一種即可：
+
+1. 把 routine key 改成 `daily-quant-run`
+2. 把 task slug 改成 `daily-quant-pipeline`
+
+**建議採用：**
+
+保留 task 檔案語義，將 `.paperclip.yaml` 的 routine key 改成 `daily-quant-run`，與 `TASK.md` slug 對齊。
+
+---
+
+### P2. `quant-strategist` 權限過大
+
+**現況**
+
+在 `.paperclip.yaml` 中：
+
+```yaml
+agents:
+  quant-strategist:
+    permissions:
+      canCreateAgents: true
+```
+
+**影響**
+
+在 Paperclip 中，`canCreateAgents` 比「可分派工作」更高，是接近 agent creator / manager 級別的權限。
+
+目前設計目標只是讓策略師主導量化 pipeline，不是讓他具備建立 agent 的高權限。
+
+**建議修法**
+
+1. 若只是要策略師能主導任務分配，先移除 `canCreateAgents: true`
+2. 若未來真的需要額外委派能力，再由 Paperclip 的顯式 permission / grant 機制處理
+
+**建議採用：**
+
+先移除 `quant-strategist.permissions.canCreateAgents`
+
+---
+
+### P3. `PROJECT.md` 的 owner / status 意圖沒有被保留下來
+
+**現況**
+
+兩個 project 使用了：
+
+```yaml
+leadAgentSlug: ...
+status: active
+```
+
+參考：
+
+- `origin/dev:projects/daily-quant-pipeline/PROJECT.md`
+- `origin/dev:projects/board-ops/PROJECT.md`
+
+**影響**
+
+實際 dry-run 匯入結果顯示：
+
+- `leadAgentSlug: null`
+- `status: null`
+
+也就是說，這兩個欄位現在雖然寫在檔案裡，但 importer 沒有保留成有效 project metadata。
+
+**建議修法**
+
+1. 先把 `PROJECT.md` 保持為 vendor-neutral、最小可攜欄位
+2. 若需要 Paperclip 專屬 fidelity，改放到 `.paperclip.yaml` 或 `metadata.paperclip`
+3. project owner 可優先改成 base spec 較接近的欄位，例如 `owner`
+
+**建議採用：**
+
+- `PROJECT.md` 只保留：`name`、`description`、`slug`
+- project owner / runtime 狀態改放進 `.paperclip.yaml`
+
+---
+
+### P4. `daily-secretary-digest` 放在錯的 project 資料夾底下
+
+**現況**
+
+檔案位置：
+
+```text
+projects/daily-quant-pipeline/tasks/daily-secretary-digest/TASK.md
+```
+
+但 frontmatter 內容是：
+
+```yaml
+project: board-ops
+```
+
+**影響**
+
+雖然 importer 目前會依 frontmatter 匯入成功，但這違反 package 本身的資料夾慣例，之後非常容易造成：
+
+1. 維護時誤判任務歸屬
+2. reviewer 看目錄就被誤導
+3. 後續 agent 做批次修改時把任務放錯地方
+
+**建議修法**
+
+將該檔案移到：
+
+```text
+projects/board-ops/tasks/daily-secretary-digest/TASK.md
+```
+
+同時保持：
+
+```yaml
+project: board-ops
+```
+
+---
+
+## 3. 建議但非阻塞問題
+
+### S1. 第一版 package 已經不是方案 A，而是接近量化完整版
+
+目前 `dev` branch 實際包含：
+
+1. 管理團隊 3 位
+2. 量化團隊 7 位
+3. `xiao-an` 1 位 paused
+
+也就是：
+
+- 10 active
+- 1 paused
+
+這已經比原規劃文件的方案 A 更接近「完整量化版」。
+
+**建議**
+
+1. 更新 `docs/INDEX.md` 與相關說明，明確寫成「第一版 package = 管理 + 完整量化團隊」
+2. 不要再沿用「精實版 8 active」的敘述，避免文檔口徑不一致
+
+---
+
+### S2. 可以補一份簡短的 import 驗收說明
+
+建議在 `docs/` 追加一段簡單說明，讓之後的人知道該怎麼驗：
+
+```bash
+paperclipai company import . --dry-run --json
+```
+
+最低驗收應包含：
+
+1. 沒有 `missing COMPANY.md`
+2. 所有 recurring task 都有對應 routine
+3. projects 與 tasks 的目錄與 frontmatter 一致
+4. `.paperclip.yaml` 沒有秘密值與機器相依路徑
+
+---
+
+## 4. 建議修改順序
+
+另一個 agent 建議依照這個順序修：
+
+1. 修 P1：對齊 routine key 與 recurring task slug
+2. 修 P4：把 `daily-secretary-digest` 移到正確目錄
+3. 修 P2：收斂 `quant-strategist` 權限
+4. 修 P3：整理 `PROJECT.md` 與 `.paperclip.yaml` 的 project metadata 分工
+5. 跑一次 `paperclipai company import --dry-run --json`
+6. 更新 `docs/INDEX.md` 或其他說明文件，讓口徑一致
+
+---
+
+## 5. 修正後的驗收標準
+
+修完後，至少要確認：
+
+1. `daily-quant-run` 在 dry-run 結果中不再是 `routine: null`
+2. `daily-secretary-digest` 檔案實體位於 `projects/board-ops/tasks/`
+3. `quant-strategist` 不再持有不必要的高權限
+4. `PROJECT.md` 中不再放 importer 會直接吃掉卻不保留的欄位，或已明確改為 `.paperclip.yaml` 承載
+5. 文件敘述與 package 實際內容一致
+
+---
+
+## 6. 給下一位 Agent 的一句話任務說明
+
+請修正 `origin/dev` 的 Paperclip package，使 recurring routines 能正確綁定到任務、project 與 task 的目錄/metadata 一致、並移除不必要的高權限設定；修完後用 `paperclipai company import --dry-run --json` 驗證。