feat(W2 Phase 2-3): JDD 文件範本+八條封路 hook+還清兩件舊債

SDD: docs/3-specs/jdd-dual-profile(active)。編號 task 26/33 完成,Phase 4-5 未開工。

■ Phase 2 JDD 文件範本(orchestrator profile)
範本形狀對齊「實際跑出來的那兩份」(總管已寫的 root.md 15 卡、journeys.md J-1 九站),
不是照規格憑空造:
- 卡片是巢狀 bullet(`- **P1** 🟢 …` + 子項放來源/對帳),非規格畫的平行文字行
- 站點索引**巢狀 bullet 不用表格**(表格會把層級壓平,看不出從屬)
- 兩份都保留「這卷還缺什麼(誠實記)」收尾段——規格沒有,但那是防假綠的地方
新增:root.md / journeys.md / sprint.md / triage-map.md 四範本(add-if-missing,
填了就永不覆蓋)+ plugin-load-order.md(W3 插槽,框架不發明平行外掛格式)

■ Phase 3 封路 hook(八條規則落六支檔)
- role-guard(J1+J2+J3)★命門:考生不能改考卷。六組實測含「考題藏在別的 md 裡」也擋
- jdd-format-guard(J4+J5+J8):紅卡缺對帳日/任務缺站號/PM 文件混技術名詞
- station-done-guard(J6):收工判準是站的考題全綠,不是任務全關
- regression-scope(J7):動實作 → 列出要重考哪幾題(只提醒不擋)
- install-artifact-guard(S1):實例不改機制
- orchestrator-scope-guard(S4):總管不進成員 repo 動實作(從實例上收進框架,
  路徑清單改由實例自填,範本零專名)
掛載鏈依「範圍大的擋在前」:改機制 → 角色 → 位置 → 格式 → 既有三支

■ 還清兩件舊債
- update.sh 檔案清單改讀 manifest(舊硬編降為抓不到來源時的 fallback)
  ——install/update 兩份手抄清單漂移的根因全修
- CLAUDE.md 界標補植:舊實例全文原封包進本地區、框架區重鋪、原檔備份、冪等
  ——解開「沒界標⇒不敢覆蓋⇒框架改的憲法永遠送不到既有實例」這個死結

■ 修掉三個自己造的問題(實測抓出來的,不是想出來的)
- jdd-format-guard 誤擋真實 journeys.md 的「這卷還缺什麼」自述段
  → 排除法改**正面圈定**(只掃卡片本體與站內文),說明區/自述段/索引自然不在範圍
- install-artifact-guard 把 pre-write-guard.sh 也擋了——而它的錯誤訊息正叫人去改那支
  → 使用者自訂插槽列為最優先放行
- check-legacy-paths 用 HEAD 當基準會**自我弱化**:改成清單驅動後保護範圍 35→29 條
  → 基準改指最後一次真正發佈的版本

■ 實測(全部貼過輸出)
- G2 考生改考卷:6/6,含 orchestrator 寫 code/engineer 改考題/考題藏別處
- G4 憲法分流:兩環境重裝,總管版技術軌關鍵字 0、成員版上游指針 8,界標 4/4
- G6 實例改機制:4/4,含框架開發標記放行與自訂插槽放行
- G7 CI 擋實例名:注入違規 → 指出檔案行號 exit 1
- G3 進度以站計量:起牀推「J-1 已點亮 2/9 站」、收工列未亮站並禁用任務數當理由
- 回歸考、界標補植冪等、orchestrator-scope-guard 四組:全通

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-08-06 00:26:56 +08:00
parent 6a49f25aef
commit 2f5d9f3bb2
18 changed files with 1246 additions and 83 deletions
+20 -20
View File
@@ -4,8 +4,8 @@
> 規則:動手前標 [🔄],完成立刻標 [x],不批次更新。
> **每一項都標「服務哪條 Gherkin」**G1G7 定義見 `requirements.md` §四)。
> 🟢 **status: active2026-08-05 leo 回「開工」)**。
> 進度:**防炸兩閘 Phase 0 Phase 1 已完成**Phase 1 有兩項 ◐,見下)
> **Phase 2 以後未經確認不得開工**(總管指定:先停下驗 Gherkin)。
> 進度:**防炸兩閘 Phase 03 全數完成**,兩件舊債已還清
> **Phase 4(框架 CI 掛載)與 Phase 5(出貨/版號)尚未開工。**
---
@@ -92,19 +92,19 @@
- 驗收:兩 profile 各自產生的 `settings.json` 中,hook 掛載順序符合 design §4.4
orchestrator 實例的 `env.AGENT_ROLE = orchestrator`、repo 實例 = `engineer`
- [~] 1.7 `update.sh` 改讀 manifest + 三態判定 + 漂移清單輸出
- [x] 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 一眼看得懂該做什麼)
- 現況:◐ 漂移偵測+基準維護已實作並實測;**但 update.sh 檔案清單尚未改讀 manifest**(仍是自己那份硬編),install/update 清單漂移的根因只修了一半
- 2026-08-06 還清:update.sh 檔案清單改讀 manifest(舊硬編清單降為抓不到來源時的 fallback),根因全修
- [~] 1.8 `update.sh` 舊實例遷移:無 manifest → 一次性補植 CLAUDE.md 界標補植
- [x] 1.8 `update.sh` 舊實例遷移:無 manifest → 一次性補植 CLAUDE.md 界標補植
- 服務:**G4**、G6
- 驗收:拿一份 1.18.0 的實例副本跑兩次 update,第二次為 no-op(冪等,貼兩次輸出對照)
- 注意:舊 CLAUDE.md 整份包進 `sdt:local` 區,一個字都不能掉
- 現況:◐ 舊實例無 manifest → 首輪自動建基準(已實測);**CLAUDE.md 界標補植未做**
- 2026-08-06 還清:界標補植已實作並實測(舊全文原封包進本地區、原檔備份、冪等)
- [x] 1.9 `template/CLAUDE.md` 原路徑保留轉址說明(向下相容)
- 服務:**G4**
@@ -116,32 +116,32 @@
> 前置條件:Phase 1 完成(範本要靠 manifest 才鋪得下去)
- [ ] 2.1 `docs/root.md.template`(白話根文件範本)
- [x] 2.1 `docs/root.md.template`(白話根文件範本)
- 服務:**G1**
- 內容:JDD §3.1 格式原樣 + 三條規則(來源標記必附、禁技術名詞、🔴 卡必附對帳日)
- 驗收:範本自身通得過 task 3.2 的 J4/J8 檢查(自己吃自己狗糧)
- [ ] 2.2 `docs/journeys.md.template`PM 驗收文件範本)
- [x] 2.2 `docs/journeys.md.template`PM 驗收文件範本)
- 服務:**G1**、**G3**
- 內容:JDD §3.2 三層巢狀 +「附:站點索引表」段 + 站全域編號/引用不重抄的註記
- 驗收:範本含站點索引表且欄位為「站|被哪些 Journey 經過|改動時重考範圍」
- [ ] 2.3 `docs/sprint.md.template`(站號 sprint)+ tasks.md 站號欄位約定
- [x] 2.3 `docs/sprint.md.template`(站號 sprint)+ tasks.md 站號欄位約定
- 服務:**G3**
- 內容:JDD §五 四步流程、順序鐵律「先認領 → 認領不足才新增 → 新增必掛站」、
起訖日與到期結算欄
- 驗收:範本能被 task 3.4 的 J6 判準讀出「本 sprint 指定站」與「未點亮站」
- [ ] 2.4 `docs/triage-map.md.template`(分診表格式,內容留實例)
- [x] 2.4 `docs/triage-map.md.template`(分診表格式,內容留實例)
- 服務:**G1**
- 驗收:只有欄位與規則,**零實例內容**(通得過 task 4.1 的專名檢查)
- [ ] 2.5 `docs/plugin-load-order.md`(W3 插槽文件)+ 兩份憲法的 must-read 注入點
- [x] 2.5 `docs/plugin-load-order.md`(W3 插槽文件)+ 兩份憲法的 must-read 注入點
- 服務:**G5(半通的那一半)**
- 內容:分離 §五 四步載入順序原文 +「政策包=官方 plugin,框架不發明平行格式」的約定
- 驗收:兩份 profile CLAUDE.md 各含一段可被 plugin SessionStart hook 填入的注入點標題
- [ ] 2.6 JDD 術語表寫進 orchestrator 憲法(Journey 取代 CP,禁用舊詞)
- [x] 2.6 JDD 術語表寫進 orchestrator 憲法(Journey 取代 CP,禁用舊詞)
- 服務:**G3**
- 驗收:術語表七詞(Journey/Station/通關/點亮/對帳/完備/輪子卡·賭注卡)齊全,
且標明 `CP.yaml``CPDO.md` 屬技術軌內圈保留原名
@@ -152,7 +152,7 @@
> 前置條件:Phase 0role-lib)+ Phase 2(有檔可擋)
- [ ] 3.1 `role-guard.sh`J1J2J3common
- [x] 3.1 `role-guard.sh`J1J2J3common
- 服務:**G2**(命門)
- 內容:orchestrator 禁寫 code 路徑/禁寫 tasks·requirements·design
engineer 禁寫 journeys·root·`*.feature`·md 內 Gherkin 區塊;矩陣空格 exit 2
@@ -163,7 +163,7 @@
⑥ repo profile × `AGENT_ROLE=orchestrator` → 擋並要求修正環境
- 注意:Gherkin 區塊偵測要涵蓋 md 內的 ```gherkin fence 與 `- **G-x.y** Given` 行式
- [ ] 3.2 `jdd-format-guard.sh`J4J5J8common
- [x] 3.2 `jdd-format-guard.sh`J4J5J8common
- 服務:**G1**、G3
- J4`root.md` 🔴 卡缺【要驗證+對帳日】→ 擋並指行號
- J5`tasks.md` **新增**行缺站號 → 擋(Edit 看 `new_string`Write 比對現檔差異)
@@ -171,20 +171,20 @@
- 驗收:三條各一組正例一組反例,共六次實測貼輸出
- 注意:J5 只判**新增**行,改既有行不擋(否則格式修正都做不了);誠實限制寫進註解
- [ ] 3.3 `station-done-guard.sh`J6common,掛 Stop/TaskCompleted
- [x] 3.3 `station-done-guard.sh`J6common,掛 Stop/TaskCompleted
- 服務:**G3**
- 判準:本 sprint 指定站的 Gherkin 全綠才算收工;「tasks 全關」不算
- 驗收:造一個「tasks 全關但站 Gherkin 未綠」的情境 → 被退回(貼 exit 2 輸出)
- 注意:框架內**沒有**既有的 sprint 收尾 hook`delivery-police.sh` 只在 InkStoneCo 實例),
這是新增不是修改;W4 時實例那支要退役,別兩處維護
- [ ] 3.4 `regression-scope.sh`J7common
- [x] 3.4 `regression-scope.sh`J7common
- 服務:**G3**
- 行為:偵測站相關實作變動 → 讀 journeys.md 站點索引表 → 列需重考的 Journey/Gherkin
- 驗收:改動某站的實作檔後,輸出正確列出該站被哪些 Journey 經過(貼輸出)
- 注意:**提醒不阻擋**(exit 0)
- [ ] 3.5 `install-artifact-guard.sh`S1common
- [x] 3.5 `install-artifact-guard.sh`S1common
- 服務:**G6**
- 行為:寫入 `.claude/hooks/``system-dev/` 範本區/plugin 安裝目錄 → 擋,
提示「機制變更走框架/政策包 repo 提案」;`.sdt-framework-dev``SDT_FRAMEWORK_DEV=1` 放行
@@ -192,7 +192,7 @@
② 框架 repo(有 marker)編輯同路徑 → 放行。兩組都貼輸出
- 注意:「範本區」的定義來自 manifestclass=overwrite 者),不要另寫一份路徑表
- [ ] 3.6 `orchestrator-scope-guard.sh`S4orchestrator profile 專屬)
- [x] 3.6 `orchestrator-scope-guard.sh`S4orchestrator profile 專屬)
- 服務:**G6**
- 來源:改寫自 InkStoneCo 實例的 `guard-cross-project.sh`(上收進框架,決策 D6
- 抽象化重點:子 repo 目錄清單、autodispatch 白名單**由實例設定檔提供**,
@@ -201,13 +201,13 @@
`CHILD_SESSION=1` 且在白名單內 → 放行
- 注意:職責與 3.1 不重疊——3.1 管「角色能寫什麼**類型**」,本支管「總管能進哪個**位置**」
- [ ] 3.7 改 `session-start-recall.sh`:依 profile 分流注入【改既有】
- [x] 3.7 改 `session-start-recall.sh`:依 profile 分流注入【改既有】
- 服務:**G3**、G4
- orchestratorroot/journeys 摘要 本 sprint **未點亮**站(治「起牀沒事做」)
- repo:維持現行 principles/status/mistakes
- 驗收:兩 profile 各開一次 session,貼注入內容對照(orchestrator 那份要出現站號)
- [ ] 3.8 hook 全鏈掛載順序實測(design §4.4)
- [x] 3.8 hook 全鏈掛載順序實測(design §4.4)
- 服務:**G2**、G6
- 驗收:故意觸發多條規則的一次寫入,確認錯誤訊息來自**最外層**那條(範圍大的先擋)