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
@@ -0,0 +1,128 @@
# journeys.md — PM 軌驗收([專案/組織名])
> **根**[root.md](root.md)J-1 對應根卡 **P?**)。本文件**只從人的角度寫**,禁止出現系統/模組名詞。
> **誰能寫**:只有總管(orchestrator)。engineersubagent **禁改本檔與任何考題**——考生不能改考卷。
> **標記**:🟢 考過即關 / 🔴 考過轉「對帳中」(站上附真實世界判準與對帳日)
> **站全域編號**,跨 Journey 共享;同一站在別條旅程重複出現只寫引用,不重抄。
> **考題(Gherkin)的 Then 只准寫「使用者看得到/感覺到什麼」**——「回傳 200」「部署成功」一律不准入題。
>
> 立卷 [YYYY-MM-DD]。取代「數任務完成幾條」當進度語言:
> 從今天起回報形式是「**J-x 已點亮 n/m 站**」。
---
## A1 [角色名]
- 一句話描述:**[這個角色是誰、他想幹嘛。用他自己會講的話寫,不要用你的話。]**
- 他不想知道我們內部長什麼樣。判準:
- 每一站都要再問一次——「**用戶需不需要為了過這關,去理解一個屬於我們內部的概念?**」
- 需要 ⇒ 這站沒過。就算對象是工程師也一樣。
### J-1 [旅程名:用第一人稱寫這個角色的一條情境]
- 這條旅程的頭尾:**[起點] → [中間] → [終點]**。
- **驗收只認頭尾**。中間任何一環「做完了」都不算通關。
#### S1 [站名:用戶拿到什麼] 🟢
- [一句話解釋這站在幹嘛。]
- **G-1.1**
- Given [我是誰/什麼狀況]
- When [我做了什麼]
- Then [我看到/感覺到什麼]
#### S2 [站名] 🟢
- [一句解釋。]
- **G-2.1**
- Given [...]
- When [...]
- Then [...]
- **G-2.2**
- Given [邊界情況——想一個「安靜地什麼都沒發生」的可能]
- When [...]
- Then [...]——**不准安靜地什麼都沒發生**
#### S3 [站名] 🔴
- 【對帳:**[真實世界的判準,要能用數字或事實判真假]**——[低於多少就代表這個設計錯了,要改成什麼]|對帳日 [YYYY-MM-DD]】
- **G-3.1**
- Given [...]
- When [...]
- Then [...]
### J-2 [第二條旅程]
> 站全域共享:同一站重複出現只寫引用,不重抄。
#### S1 →(引用,見 J-1
#### S7 [這條旅程才有的新站] 🟢
- **G-7.1**
- Given [...]
- When [...]
- Then [...]
---
## 附:站點索引(回歸考觸發表)
> 用途:某一站相關的東西被改動時,查這裡就知道**要重考哪些題**。
> ⚠️ 用巢狀 bullet,**不要用表格**——表格會把層級壓平,讀的人看不出「站 → 被誰經過 → 重考什麼」的從屬關係。
- **S1** [站名]
- 被經過:J-1
- 改動時重考:G-1.1
- **S2** [站名]
- 被經過:J-1、J-2
- 改動時重考:G-2.1、G-2.2
- **S3** [站名]
- 被經過:J-1
- 改動時重考:G-3.1 + 下游 S4~S9(這站變了,後面全部要重考)
---
## 這卷還缺什麼(誠實記,別假裝完備)
> 這一段是**防假綠的裝置**,不是免責聲明。刪掉它,這卷看起來就會比實際完整。
- **每一站現在點亮了沒有,刻意留白**。理由:站的狀態要靠實測填,
不是靠對著舊文件推測——那正是「假綠」的來源。第一次點亮由 sprint 收尾時實考填入。
- **目前只有 J-1**。第二條旅程等 J-1 通關再立——規矩是「**需要新站才提案新站**」,
不是先把表格畫滿。
- [其他你知道還缺、但這一版先不做的東西。寫出來,別讓下一個人以為這卷是完整的。]
---
<!-- ════════ 寫這份文件的規矩(給總管看,不是內容的一部分)════════
【三層結構】角色(A)→ 旅程(J)→ 站(S)→ 考題(G)
與技術軌的 Epic → Story → EARS 對稱,但**切法正交**:
技術軌沿系統結構切(保證每個零件是對的),
PM 軌沿人的經歷切(保證零件之間沒有人掉進縫裡)。
【站的編號是全域的】
S 不隸屬於某條 J。同一個能力被兩條旅程經過,就是同一個 S、同一組考題。
重複出現只寫「S1 →(引用,見 J-1)」,**不重抄**——抄第二份就會有兩份不同步的考題。
【Gherkin 的 Then 只能寫使用者感受得到的事】
✅ 「我在信箱收到一組號碼」「我看得到它是從我哪個檔案來的」
❌ 「回傳 200」「部署成功」「資料寫入成功」
這條就是「HTTP 200 不算驗過」的正式化——技術上通了但使用者沒感覺到,等於沒通。
【紅站的對帳行寫在站上,不寫進考題】
法條(Gherkin)管「做到沒」,對帳管「賭對沒」,物理分離。
🔴 站缺對帳行 格式錯誤。
【定 Journey 之前】
先寫一篇該角色的**敘事故事**給人讀一次,驗「完整性」(讀完找不找得到斷裂)。
驗完歸檔到 docs/archive/stories/,不進日常維護。
【誰能寫】
只有 orchestrator。engineersubagent 寫這個檔會被 hook 擋下——考生不能改考卷。
考題不過就去把東西做對,不是去改考題。
════════════════════════════════════════════════════════ -->