Leo
2a8c259d08
🔴 修的病：這個框架 repo 自己的 5 份 SDD 全部被 .gitignore 擋在版控之外， 只活在一台硬碟上——clone 不到、雲端 CC 讀不到、沒備份。SDD 是進度真相源， 「框架 repo 沒吃自己的狗糧」。 依據 D22（已翻案）：Gitea private 除機敏值外全 push，雲端工人靠 clone，docs 缺＝斷糧； 只有 GitHub mirror 才嚴篩，而 docs 整包已在 github-publish-exclude.txt。 .gitignore 改法：整條擋 → 只擋子項（/*）+ 逐個放行真 SDD。 與 template/ 底下逐位元組相同的自裝副本（TEMPLATE-sdd/、SDD-LIFECYCLE.md）續擋。 新增 docs/3-specs/jdd-dual-profile/（status: draft，等 leo confirm 才升 active）： JDD（PM 軌 root/journeys/角色權限/站號 sprint）與雙 profile 合成一卷， 33 條 task／6 phase，每條掛服務哪條 Gherkin（G1–G7）。 新增 hook 6 支、改既有 hook 1 支。**0 行實作**。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
176 lines
11 KiB
Markdown
176 lines
11 KiB
Markdown
# 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）。
|