Leo/system-dev-template
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
system-dev-template/docs/3-specs/jdd-dual-profile/tasks.md
T
Leo 593defceb1 release(1.19.0): 掛上機械閘＋出貨版號與 changelog（W2 Phase 4-5，收尾） 
SDD: docs/3-specs/jdd-dual-profile — 33/33 編號 task 全數完成。

■ Phase 4 把閘掛上去
- scripts/check-all.sh：三道閘＋腳本語法的總入口（一個習慣，不是三個要記得的步驟）
- .githooks/pre-commit ＋ core.hooksPath：跑在人的機器上、commit 那一刻
  不掛雲端 workflow——本組織禁止 repo 掛自動化（歷史上那正是帳號被停權的原因）

■ Phase 5 出貨
- VERSION 1.18.0 → 1.19.0（兩處：template/.claude/ 與 template/system-dev/）
- CHANGELOG 1.19.0：用「你會多出什麼」的語言寫，不列檔名
- 🐛 順手補回 **1.18.0 完全沒有 changelog 紀錄**這件事——
  那一版發佈了、功能也出貨了，但更新跑完最後一行正是叫使用者「改了什麼看 CHANGELOG」，
  版號動了卻查不到動了什麼＝等於沒交代。依實際 commit 內容補寫。

■ 七題驗收（全部附實測輸出）
- ✅ G2 考生改考卷被攔（命門）：engineer 改 journeys.md → exit 2；
     連「把考題藏進 status.md」也擋，6/6
- ✅ G3 進度以站計量：起牀推「J-1 已點亮 n/m 站」，收工列未亮站並禁用任務數當理由
- ✅ G4 憲法分流：總管版技術軌關鍵字 0、成員版上游指針 8，界標各 4/4
- ✅ G6 實例改機制被攔：4/4（框架開發放行、使用者自訂插槽放行）
- ✅ G7 框架混入實例名：指名 sdd-check.md:77，exit 1
- ◐ G1 PM 優先補接縫：機制齊了，但這是行為題，腳本證明不了 → 不標綠
- ◐ G5 政策包即插即用：插槽就位，政策包本體在 W3

■ 安裝實測：兩個乾淨環境各 1 秒、48／54 檔、版本 1.19.0、profile 正確
  （預測①「各 < 10 分鐘」達標；誠實註記：來源走本機檔案，比真實網路快）

🔴 狀態＝**等發佈**，不是 ✅：更新來源是公開 GitHub raw，
   只推 Gitea 的話外部實例抓不到 1.19.0。開閘由 leo 決定。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-06 00:34:23 +08:00

15 KiB
Raw Permalink Blame History

jdd-dual-profile — Tasks

權威來源：此檔案是進度真相，不是 CLAUDE.md 或對話。 規則：動手前標 [🔄]，完成立刻標 [x]，不批次更新。 每一項都標「服務哪條 Gherkin」（G1–G7 定義見 requirements.md §四）。 🟢 status: active（2026-08-05 leo 回「開工」）。 進度：33/33 編號 task 全數完成（2026-08-06）。版本 1.18.0 → 1.19.0。 七題驗收：✅ 5 題（G2/G3/G4/G6/G7，皆附實測輸出）／◐ 2 題—— G1 是行為題（要真的派一次工才驗得到）、G5 的政策包本體在 W3。 🔴 狀態＝等發佈：更新來源是公開 GitHub raw，需 leo 開閘才送得到外部實例。

Gherkin 對照速查

號 一句話 來源
G1 PM 總管優先補接縫而非做新功能 JDD §七
G2 考生改考卷被攔截 JDD §七
G3 進度以站計量 JDD §七
G4 憲法分流不靠判斷 分離 §七
G5 政策包即插即用（本波只到 ◐ 半通） 分離 §七
G6 實例改機制被攔 分離 §七
G7 框架混入實例名被 CI 擋 分離 §七

Phase 0：地基（manifest ＋ 兩軸判定）

前置條件

  • leo confirm 本 SDD，frontmatter 由 draft 改 active

Tasks

  • 0.1 定義 manifest 格式並產出三份 template/manifest/{common,repo,orchestrator}.tsv

    • 服務：G4（分流的資料基礎）、G6（產物區清單的單一來源）
    • 欄位：dest class profile；class ∈ overwrite|keep|add-if-missing|keep-with-template
    • 驗收：三份 manifest 涵蓋現行 install.sh 硬編的每一個 download_if_missing 目標， 逐項比對零遺漏（貼比對輸出）
    • 注意：既有檔一律標 common 且 dest 路徑與現況完全相同（決策 D3，不搬檔）

  • 0.2 寫 template/.claude/hooks/lib/role-lib.sh（兩軸判定函式庫）

    • 服務：G2、G6
    • 內容：sdt_repo_root / sdt_rel_path / sdt_scope / sdt_role / sdt_assert_identity / sdt_file_path_from_stdin（jq→python3→grep 三段 fallback）
    • 驗收：以四組身分（orchestrator×orchestrator、orchestrator×engineer、 repo×engineer、repo×orchestrator）跑單元測試，最後一組回 exit 2；貼四組輸出
    • 注意：不得用 CLAUDE_PROJECT_DIR（雲端可跑）；bash 3.2 相容

  • 0.3 立 marker 檔約定：system-dev/.profile、system-dev/.template-manifest、.sdt-framework-dev

    • 服務：G4、G6
    • 驗收：三個檔的格式各寫一段規格進 design 的附錄，並在框架 repo 自己放一份 .sdt-framework-dev（commit）
    • 注意：--framework-dev 不是官方 CLI flag（決策 D9），別去找那個參數

Phase 1：雙 profile 與 CLAUDE.md 生成

前置條件：Phase 0 全部完成

  • 1.1 建 template/profiles/repo/CLAUDE.md（repo 憲法範本）

    • 服務：G4
    • 來源：現行 template/CLAUDE.md 演進；加「上游指針」一行、「站號怎麼標在 task 上」一段、 W3 must-read 注入點一段
    • 驗收：grep -c "上游" ≥ 1；全文不含任何實例專名

  • 1.2 建 template/profiles/orchestrator/CLAUDE.md（總管憲法範本）

    • 服務：G4、G3
    • 內容：效忠 root/journeys、JDD 全術語表、sprint 站號全流程、 進度語言「J-x 已點亮 n/m 站」、問題升級階梯三級（藍圖 §5.5）、W3 must-read 注入點
    • 驗收：grep -c "SDD 三件式\|requirements.md" = 0（G4 明文：總管版無 SDD 三件式細節）
    • 注意：不得出現任何實例專名（藍圖 v3 的內容要抽象化，專案名留給實例填）

  • 1.3 install.sh 加 --profile=repo|orchestrator ＋ 自動偵測 ＋ 一次性人確認

    • 服務：G4
    • 偵測規則：目前目錄下存在多個各自帶 .git 的子目錄 → 建議 orchestrator
    • 驗收：三種呼叫（明示 repo／明示 orchestrator／不指定走偵測）各跑一次乾淨環境， 貼出各自產生的 system-dev/.profile 內容
    • 注意：確認在寫入任何檔案之前問，別裝了一半才問

  • 1.4 install.sh 改讀 manifest 鋪設產物 ＋ 產 .template-manifest

    • 服務：G4、G6
    • 驗收：repo profile 裝出的檔案集合 = common.tsv ∪ repo.tsv， 且不含 orchestrator 專屬檔（ls 對照貼出）

  • 1.5 CLAUDE.md 三段組裝（框架區界標 ＋ 本地補充區界標 ＋ sha256）

    • 服務：G4
    • 驗收：裝完的 CLAUDE.md 含 sdt:framework begin/end 與 sdt:local begin/end 四個界標， 且 sha256 值與框架區實際內容相符（重算比對貼出）

  • 1.6 install.sh 的 build_hooks_json() 加 profile 維度 ＋ 寫入 env.AGENT_ROLE 預設

    • 服務：G2、G6
    • 驗收：兩 profile 各自產生的 settings.json 中，hook 掛載順序符合 design §4.4； orchestrator 實例的 env.AGENT_ROLE = orchestrator、repo 實例 = engineer

  • 1.7 update.sh 改讀 manifest ＋ 三態判定 ＋ 漂移清單輸出

    • 服務：G6（機械閘 #3）
    • 驗收：在 InkStoneCo 實例上跑，漂移清單恰好列出 4 支 （pre-write-guard.sh／sdd-guard.sh／subagent-wiki-guard.sh／wiki-first-search.sh， 見 design §0.4 基線），貼完整輸出
    • 注意：漂移檔不覆蓋，新版另存 <檔>.new；輸出用白話（leo 一眼看得懂該做什麼）
    • 2026-08-06 還清：update.sh 檔案清單已改讀 manifest（舊硬編清單降為抓不到來源時的 fallback），根因全修

  • 1.8 update.sh 舊實例遷移：無 manifest → 一次性補植 ＋ CLAUDE.md 界標補植

    • 服務：G4、G6
    • 驗收：拿一份 1.18.0 的實例副本跑兩次 update，第二次為 no-op（冪等，貼兩次輸出對照）
    • 注意：舊 CLAUDE.md 整份包進 sdt:local 區，一個字都不能掉
    • 2026-08-06 還清：界標補植已實作並實測（舊全文原封包進本地區、原檔備份、冪等）

  • 1.9 template/CLAUDE.md 原路徑保留轉址說明（向下相容）

    • 服務：G4
    • 驗收：舊版 update.sh 對該路徑的 curl 仍回 200（決策 D3）

Phase 2：JDD 文件範本（orchestrator profile）

前置條件：Phase 1 完成（範本要靠 manifest 才鋪得下去）

  • 2.1 docs/root.md.template（白話根文件範本）

    • 服務：G1
    • 內容：JDD §3.1 格式原樣 ＋ 三條規則（來源標記必附、禁技術名詞、🔴 卡必附對帳日）
    • 驗收：範本自身通得過 task 3.2 的 J4／J8 檢查（自己吃自己狗糧）

  • 2.2 docs/journeys.md.template（PM 驗收文件範本）

    • 服務：G1、G3
    • 內容：JDD §3.2 三層巢狀 ＋「附：站點索引表」段 ＋ 站全域編號/引用不重抄的註記
    • 驗收：範本含站點索引表且欄位為「站｜被哪些 Journey 經過｜改動時重考範圍」

  • 2.3 docs/sprint.md.template（站號 sprint）＋ tasks.md 站號欄位約定

    • 服務：G3
    • 內容：JDD §五 四步流程、順序鐵律「先認領 → 認領不足才新增 → 新增必掛站」、 起訖日與到期結算欄
    • 驗收：範本能被 task 3.4 的 J6 判準讀出「本 sprint 指定站」與「未點亮站」

  • 2.4 docs/triage-map.md.template（分診表格式，內容留實例）

    • 服務：G1
    • 驗收：只有欄位與規則，零實例內容（通得過 task 4.1 的專名檢查）

  • 2.5 docs/plugin-load-order.md（W3 插槽文件）＋ 兩份憲法的 must-read 注入點

    • 服務：G5（半通的那一半）
    • 內容：分離 §五 四步載入順序原文 ＋「政策包＝官方 plugin，框架不發明平行格式」的約定
    • 驗收：兩份 profile CLAUDE.md 各含一段可被 plugin SessionStart hook 填入的注入點標題

  • 2.6 JDD 術語表寫進 orchestrator 憲法（Journey 取代 CP，禁用舊詞）

    • 服務：G3
    • 驗收：術語表七詞（Journey／Station／通關／點亮／對帳／完備／輪子卡·賭注卡）齊全， 且標明 CP.yaml／CPDO.md 屬技術軌內圈保留原名

Phase 3：封路 hook

前置條件：Phase 0（role-lib）＋ Phase 2（有檔可擋）

  • 3.1 role-guard.sh（J1＋J2＋J3，common）

    • 服務：G2（命門）
    • 內容：orchestrator 禁寫 code 路徑／禁寫 tasks·requirements·design； engineer 禁寫 journeys·root·*.feature·md 內 Gherkin 區塊；矩陣空格 exit 2
    • 驗收：六組實測各貼 stdout/exit code—— ① orchestrator 寫 .py → 擋 ② orchestrator 寫 tasks.md → 擋 ③ engineer 改 journeys.md 的 Gherkin → 擋（這條就是 G2） ④ engineer 寫 .py → 放行 ⑤ orchestrator 寫 journeys.md → 放行 ⑥ repo profile × AGENT_ROLE=orchestrator → 擋並要求修正環境
    • 注意：Gherkin 區塊偵測要涵蓋 md 內的 ```gherkin fence 與 - **G-x.y** Given 行式

  • 3.2 jdd-format-guard.sh（J4＋J5＋J8，common）

    • 服務：G1、G3
    • J4：root.md 🔴 卡缺【要驗證＋對帳日】→ 擋並指行號
    • J5：tasks.md 新增行缺站號 → 擋（Edit 看 new_string，Write 比對現檔差異）
    • J8：root.md／journeys.md 技術名詞黑名單命中 → 擋並列詞＋行號
    • 驗收：三條各一組正例一組反例，共六次實測貼輸出
    • 注意：J5 只判新增行，改既有行不擋（否則格式修正都做不了）；誠實限制寫進註解

  • 3.3 station-done-guard.sh（J6，common，掛 Stop/TaskCompleted）

    • 服務：G3
    • 判準：本 sprint 指定站的 Gherkin 全綠才算收工；「tasks 全關」不算
    • 驗收：造一個「tasks 全關但站 Gherkin 未綠」的情境 → 被退回（貼 exit 2 輸出）
    • 注意：框架內沒有既有的 sprint 收尾 hook（delivery-police.sh 只在 InkStoneCo 實例）， 這是新增不是修改；W4 時實例那支要退役，別兩處維護

  • 3.4 regression-scope.sh（J7，common）

    • 服務：G3
    • 行為：偵測站相關實作變動 → 讀 journeys.md 站點索引表 → 列需重考的 Journey/Gherkin
    • 驗收：改動某站的實作檔後，輸出正確列出該站被哪些 Journey 經過（貼輸出）
    • 注意：提醒不阻擋（exit 0）

  • 3.5 install-artifact-guard.sh（S1，common）

    • 服務：G6
    • 行為：寫入 .claude/hooks/／system-dev/ 範本區／plugin 安裝目錄 → 擋， 提示「機制變更走框架/政策包 repo 提案」；.sdt-framework-dev 或 SDT_FRAMEWORK_DEV=1 放行
    • 驗收：① 實例 session 編輯 .claude/hooks/ 任一檔 → 擋（這條就是 G6） ② 框架 repo（有 marker）編輯同路徑 → 放行。兩組都貼輸出
    • 注意：「範本區」的定義來自 manifest（class=overwrite 者），不要另寫一份路徑表

  • 3.6 orchestrator-scope-guard.sh（S4，orchestrator profile 專屬）

    • 服務：G6
    • 來源：改寫自 InkStoneCo 實例的 guard-cross-project.sh（上收進框架，決策 D6）
    • 抽象化重點：子 repo 目錄清單、autodispatch 白名單由實例設定檔提供， 範本內零實例專名（通得過 task 4.1）
    • 驗收：以假造的成員目錄結構跑三組——寫子 repo 的 .py → 擋／寫子 repo 的 .md → 放行／ CHILD_SESSION=1 且在白名單內 → 放行
    • 注意：職責與 3.1 不重疊——3.1 管「角色能寫什麼類型」，本支管「總管能進哪個位置」

  • 3.7 改 session-start-recall.sh：依 profile 分流注入【改既有】

    • 服務：G3、G4
    • orchestrator：root/journeys 摘要 ＋ 本 sprint 未點亮站（治「起牀沒事做」）
    • repo：維持現行 principles/status/mistakes
    • 驗收：兩 profile 各開一次 session，貼注入內容對照（orchestrator 那份要出現站號）

  • 3.8 hook 全鏈掛載順序實測（design §4.4）

    • 服務：G2、G6
    • 驗收：故意觸發多條規則的一次寫入，確認錯誤訊息來自最外層那條（範圍大的先擋）

Phase 4：框架側 CI 與清潔

前置條件：Phase 1（manifest 定義了「範本區」）

  • 4.1 scripts/check-no-instance-names.sh ＋ scripts/instance-names.txt

    • 服務：G7
    • 行為：掃 template/，命中黑名單 → exit 1 並印「檔案:行號:命中詞」； 支援逐行豁免標記（行尾 # sdt-instance-name-ok）；policy pack 路徑不受檢
    • 驗收：在範本檔新增一行含 "arcrun" → 檢查 fail 並指出檔案與行號（這條就是 G7），貼輸出

  • 4.2 現況 20 行命中的分診處置（design §0.5）

    • 服務：G7
    • (a) 6 行註解／舉例 → 改寫成通用敘述
    • (b) 3 行政策內容 ＋ (c) 13 行 L2 產物 → 標 # sdt-instance-name-ok ＋ 一行「W3 搬遷」註記
    • 驗收：處置後 check-no-instance-names.sh 回 exit 0，且豁免行數 = 16（貼清單）
    • 注意：禁止假性清理（把 arcrun 改寫成「某工作流引擎」＝資訊消失、問題還在）

  • 4.3 掛 pre-commit / CI

    • 服務：G7
    • 驗收：bash scripts/check-no-instance-names.sh 在 CI 步驟中被呼叫，故意違規的 commit 被擋

Phase 5：出貨（ship-check）

前置條件：Phase 0–4 全部完成

  • 5.1 CHANGELOG ＋ VERSION bump（兩處：template/.claude/VERSION ＋ template/system-dev/VERSION）

    • 服務：全部
    • 版號：1.18.0 → 1.19.0（新功能、向下相容）
    • 驗收：兩個 VERSION 檔內容一致；CHANGELOG 用用戶語言寫「這一版你會多出什麼」
    • 注意：版本號是 leo 唯一的驗收介面——沒動＝等於沒交付

  • 5.2 乾淨環境雙 profile 安裝實測（含計時）

    • 服務：G4
    • 驗收：兩個全新空目錄各裝一次，各記錄實際耗時（分離 §八 預測①：各 < 10 分鐘）， 貼安裝輸出 ＋ ls -R 檔案清單對照

  • 5.3 七題 Gherkin 逐條實測並記錄三態

    • 服務：G1–G7
    • 驗收：每題貼實測輸出並標 ✅ 通 / ◐ 半通（缺什麼）/ ❌ 斷
    • 注意：G5 本波上限 ◐（插槽就位、政策包在 W3），標 ✅ 就是假綠； G1 需要 root/journeys 有實內容才驗得到端到端 → 若實例尚未落地（W4）， 以框架附的示範 fixture 驗，並在報告標明「以 fixture 驗，實例端到端待 W4」

  • 5.4 回報總管：交付物、三態表、與規格假設不符的清單

    • 服務：全部
    • 驗收：報告含 design §0 全部實查發現 ＋ 本波實際落地的 hook 數（改既有 vs 新增）

完成定義

整個 SDD 完成 = 以下全部達成：

  • 所有 tasks 標 [x]
  • G1–G7 逐題有實測證據，且無任何一題為 ❌ 斷（G5 可為 ◐）
  • bash scripts/check-no-instance-names.sh 回 exit 0
  • bash scripts/sdd-active-check.sh docs/3-specs 回 exit 0
  • 兩處 VERSION = 1.19.0，CHANGELOG 已寫
  • design.md 與實作一致（如有出入需更新 design，不是默默改 code）

狀態說明

標記 意義
[ ] 未開始
[🔄] 進行中（當前 session）
[x] 完成（有驗收證據）
[~] 暫緩（說明原因）
[!] 阻擋中（說明阻擋原因）
Reference in New Issue View Git Blame Copy Permalink