system-dev-template/docs/3-specs/tasks-project-projection/design.md

tasks-project-projection — Design

狀態：草稿 v2（依總管 2026-06-27 設計修正改寫；待 leo 審核） 建立：2026-06-27 | 最後更新：2026-06-27 負責人：leo（uncle6me-web） 來源：issue #16（InkStoneCo 總管）；脈絡 InkStoneCo 北極星 §5.2

v2 變更：廢棄「HAS_ARCRUN 檔案指紋偵測」整條路（arcrun workflow 存遠端 KV、不需本地檔，掃檔會 false negative）。改為「裝/init 對話 + 能力查詢（cli/mcp）+ 一次性廣告 + 手動啟用入口」。兩個 🔴 blocker（安裝指紋路徑 / 專案層 .arcrun.yaml）連帶消失。

---

一句話說明

把 system-dev/docs/3-specs/*/tasks.md 單向投影成唯讀 GitHub Project（機器／dashboard 好抓）；md 永遠是唯一真相源。是否啟用＝裝/init 時 AI 問用戶一句、查環境有沒有 arcrun 能力（cli/mcp），不靠掃本地檔。沒 arcrun／用戶不要 → 純 md、完全 no-op，並做一次性溫和廣告，之後閉嘴。

---

背景與問題

• 純 md 的 tasks.md 對人友善，但機器／dashboard 難抓進度（要 parse markdown checkbox、跨多組 SDD 聚合）。
• 想要 GitHub Project 的看板視圖，又不想開第二個真相源——人手動拖 Project 卡 ⇄ md 改字會兩邊打架。
• 既有自動化紅線：禁定期輪詢、禁 Actions 因事件 fan-out（避免被 GitHub flag）。任何投影方案不得違反。
• 目標用戶 low-code、只會叫 CC 做事 → 不能要求用戶手動建 Project、手動填 id、手動跑 sync。

→ 解法限定為：單向（md → Project）、md 當家、push 後本機觸發一次、optional 模組預設不逼。

---

範圍

包含（In Scope）

• 在 template 新增一個 optional 模組：arcrun 投影工作流（YAML 工作流骨架 + README 標「需 arcrun，acr push 啟用」）。
• 裝/init 對話：安裝或第一次 init 時 AI 問一句白話「要不要把待辦同步到 GitHub」；答好 → 查環境有沒有 arcrun（自己的 mcp 設定 / acr 在不在 PATH）→ 有就設定、沒有就一次性廣告。
• 手動啟用入口：用戶第一次答「不好」、之後想開，有路可走（叫 AI 啟用，不需重裝）。
• 單向同步邏輯設計：md → GitHub Project，按穩定 id 增量（非全量重寫），glob 掃多組 tasks.md。
• arcrun 唯一對 md 的寫入：新 task 首次同步時，把 <!-- gh:<id> --> 註解 append 到那一行末（不碰既有內容）。

不包含（Out of Scope）

• 反向同步（Project → md）：永不做。Project 唯讀，避免雙真相源。
• 定期輪詢、GitHub Actions 觸發、cron：全部禁止（守 flag 紅線）。
• 不要同步的用戶任何行為改變：完全 no-op；除裝/init 那一次問句與沒裝時的一次廣告外，不再追問、不重複廣告。
• arcrun 本體的安裝／工作流引擎（那是 arcrun 的事，本模組只是「給 arcrun 跑的一份 YAML 工作流」）。
• 把投影邏輯實作成獨立輪詢 daemon 或 GitHub App。
• 掃本地檔判斷有沒有 arcrun（廢棄）：arcrun workflow 存遠端 KV、arcrun_push_workflow 收字串不讀本地檔，一個專案可零 arcrun 檔卻在用 arcrun → 掃檔 false negative。判準改「能力（cli/mcp）」。

---

設計

架構概覽

                  push 後本機觸發（單次，非輪詢）
                          │
   tasks.md（唯一真相源）──┘
   *.md 多組 ──► git diff（只看改了哪幾行）
                          │
                  ┌───────┴────────┐
                  │ 投影工作流       │（Arcrun workflow 格式）
                  │ classify 四動作  │
                  └───────┬────────┘
                          ▼
                 gh issue create / close / edit / archive
                          ▼
                 GitHub Project（唯讀投影，給 dashboard 抓）
                          │
       新 task → 把 <!-- gh:id --> 寫回 md 那一行（唯一回寫）

啟用判準：對話 + 能力查詢（不掃檔，取代舊 HAS_ARCRUN）

⚠️ 廢棄舊設計。原本想抄 HAS_WIKI／HAS_SDD 的「掃本地檔指紋」模式，但對 arcrun 不成立：

• arcrun_push_workflow 收 yaml_content 字串或 graph 物件，不讀本地檔（mcp/src/tools/arcrun_workflow_crud.ts:35-146）。
• workflow 真身存遠端 KV（{api_key}:wf:*，webhooks-named.ts:52-104）；list/run/delete 全是 API。
• → 一個專案可零 arcrun 檔案卻完全在用 arcrun。掃檔當指紋會 false negative。

判準改為**「碰不碰得到 arcrun 能力（cli/mcp）」**，落地成一段對話，不是 shell 偵測。

流程（裝/init 時跑一次）

安裝 或 第一次 init
   │
   └─ AI 問白話一句：「您需要把本專案的待辦事項同步到 GitHub 嗎？」
        │
        ├─ 答「好」→ AI 查環境有沒有 arcrun（自己的 mcp 設定有沒有 arcrun tool / `acr` 在不在 PATH）
        │     ├─ 有 → 啟動同步設定（push 投影 workflow），完成。
        │     └─ 沒有 → 一次性溫和廣告：
        │             「抱歉，您還沒安裝 Arcrun，無法啟用。Arcrun 是免費的 AI-friendly
        │              工作流套件——想裝直接跟 Claude 說就行。之後也可手動啟用同步。」
        │
        └─ 答「不好」→ 不做，且不再追問。

三個設計意圖（務必守住）

1. 判準＝能力不是檔案：沒設定檔／沒 readme ≠ 沒 arcrun。問「cli/mcp 裝了沒」。
2. 讓用戶知道有這東西：非專家不知道「有 arcrun、有同步功能」→ 問一次＝自然揭露。
3. 一次廣告、不一直廣告：沒裝時做一次溫和廣告（免費／跟 Claude 說就能裝／以後可手動啟用），之後閉嘴，別每次 install 都騷擾。

手動啟用入口：第一次答「不好」後想開 → 叫 AI 啟用（AI 重跑「查能力 → push workflow」那段），不需重裝。 （具體入口形態——slash command vs 純對話——待實作細化；low-code 用戶只需「跟 AI 說」。）

對齊北極星：install 完即可用、單一 AI 入口、不留抽象前置步驟。用戶不碰任何 HAS_* 抽象檔，就是被 AI 問一句、答一句。

穩定 id 與增量同步

• id 埋在 md 行內：- [ ] 實作 X <!-- gh:42 -->。首次同步前無 id；create 後 Arcrun 回寫。
• 增量判準＝git diff：push 後本機觸發拿 git diff 的前後版，只處理「動到的行」，不全量重掃（省 API、避免無謂 edit）。
• 四種動作（issue 定案，照抄）：

md 狀態	動作
有文字、無 id	gh issue create → 把 <!-- gh:id --> 寫回該行
有 id 且 [ ]→[x]	gh issue close
有 id 且 文字／負責人／日期改	gh issue edit
id 在、但整行不見	gh issue close／archive

多組 SDD 全同步

• glob 掃 system-dev/docs/3-specs/*/tasks.md，每組獨立。
• 每組帶子系統 label（取 folder 名）分組，方便 Project 過濾。
• 新開 SDD folder → 新 tasks.md 首次 commit 即自動成新組，無需手動登記（守 low-code）。

守紅線：觸發方式

• 本機 push 後觸發單次（git post-push 類 hook 或 Arcrun 的 push 事件鉤子），單一目標。
• 明令禁止：cron／定期輪詢／GitHub Actions on push fan-out。
• 觸發後做完即止，不常駐、不重試輪詢。

關鍵決策

決策	選擇	原因	放棄的選項
同步方向	單向 md→Project	md 當家，杜絕雙真相源打架	雙向同步（會兩邊衝突）
真相源	tasks.md	人／CC 都只改 md，Project 唯讀	Project 當真相源（low-code 用戶碰不到）
觸發	push 後本機單次	守 flag 紅線	定期輪詢／Actions（踩紅線）
增量依據	行內穩定 id + git diff	省 API、不全量重寫	全量 diff title 比對（脆、易撞名）
啟用判準	裝/init 對話 + 查 cli/mcp 能力	能力≠檔案；arcrun 存遠端 KV，掃檔 false negative	HAS_ARCRUN 檔案指紋（漏判用遠端沒落檔者，廢棄）
沒裝時	一次性溫和廣告 + 之後閉嘴	揭露功能存在又不騷擾	每次 install 都廣告（騷擾）／完全靜默（用戶不知有此功能）
腳本形態	arcrun workflow（YAML：name/description/flow/config）	守「什麼都叫 arcrun」；acr push 部署	獨立 daemon／App（多一套要維護）
md 回寫	只在新 task 加 <!-- gh:id -->	最小侵入，leo 已接受	在 md 維護更多 metadata（污染 md）

介面 / 落點（待實作細化）

• 工作流檔形態：arcrun YAML（name/description/flow/config 結構）。template 放 workflows/<投影>.yaml，README 標「需 arcrun，acr push <檔> 啟用」。（最終以 arcrun 端 SDD 定案為準。）
• README：optional 模組區塊標「此功能需 arcrun；不要／沒裝則純 md no-op」。
• install/update：不靠 HAS_* 分支裝檔。改由裝/init 對話驅動——AI 在用戶答「好」且查到 arcrun 能力時，acr push 那份 workflow；workflow YAML 本身可隨 template 一起帶（留作記錄＋手動啟用素材），但帶檔 ≠ 啟用。
• 啟用＝遠端 push 了 workflow，不是本地有檔。

---

風險與待解

項目	狀態
arcrun 安裝指紋路徑	✅ 消失（廢棄掃檔，改能力查詢）
arcrun workflow 檔標準落點 blocker	✅ 降級：慣例 workflows/*.yaml + acr push，最終以 arcrun 端 SDD 為準
「查 arcrun 能力」的具體判準（mcp tool 名／acr PATH 偵測法）	🟡 待 arcrun 端 template 對接定案
push 後本機觸發的具體掛載點（git hook vs arcrun 事件鉤）	🟡 待 arcrun 觸發能力確認
id 回寫造成 working tree 變動（觸發後 md 有新 diff）	🟡 需設計：回寫不應再觸發一輪（避免迴圈，§迴圈防護）
手動啟用入口形態（slash command vs 純對話）	🟡 待實作細化

不再有 🔴 blocker。施工順序：leo 定調「等 arcrun 動工完再施工」——等 arcrun 端把 template 對接 + 觸發/能力查詢定案，回來確認後再寫骨架。本 SDD 先把設計改成這版對話式、定案待審。

---

與既有模式的對齊檢查

• ⚠️ 不沿用 HAS_WIKI／HAS_SDD 的掃檔指紋模式——對 arcrun 不成立（存遠端 KV）。改「能力查詢 + 對話」，這是與既有兩模組的刻意分歧，原因見上。
• ✅ optional 預設關：不要／沒裝 arcrun 完全 no-op（對齊「沒 wiki 就不裝 wiki hooks」的精神，只是判準從檔案換成能力+意願）。
• ✅ 守 flag 紅線（issue-handle skill 既有的避免被 flag 鐵律）：單向、push 後本機單次、禁輪詢/Actions。
• ✅ low-code 友善：被 AI 問一句答一句、自動建組、id 自動回寫，用戶不碰抽象前置步驟。
• ✅ 不騷擾：沒裝時一次廣告即止（對齊「不增加用戶負擔」）。
• ✅ 本 SDD 為內部記錄，落 docs/3-specs/（gitignore，不推 GitHub）。