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,76 @@
# root.md — 我們到底在做什麼(需求根文件)
> 這是**兩軌共享的唯一錨點**PM 軌([journeys.md](journeys.md))和技術軌(各專案自己的規格)都從這裡長出來。
> **規矩**:一張卡一句白話 + 來源標記 + 紅綠燈。**禁止出現任何技術名詞**——技術是手段,寫進各專案自己的規格,不寫進根。
> **紅綠怎麼判**:能指著市場上活得好好的先例說「照這個做」=🟢;不能、解法是猜的=🔴。**紅卡必附對帳判準與對帳日。**
> **誰能寫**:只有總管。**誰來勾**:出資/決策的那個人——卡片真偽是他的第一道閘,這份文件的價值全在他點頭或搖頭。
>
> 立卷 [YYYY-MM-DD]。素材=[列出你是從哪些文件/對話讀出這些卡的]。
---
## 一、[分節標題:例如「關於我怎麼工作」]
> 分節是為了讓人一眼看出「這幾張是同一類的事」。沒把握就先不分,卡多了再分。
- **P1** 🟢 [一句白話。不懂技術的人讀了能點頭或搖頭。]
- ——(你說的:[出處]
- **P2** 🔴 [一句白話。]
- 【要驗證:[一句話判準,要能用真實世界的數字或事實判真假] | 對帳日 [YYYY-MM-DD]】
- **P3** 🟢 [一句白話。]
- ——(你舉的例子:[出處]
## 二、[分節標題:例如「關於我在賣什麼」]
- **P4** 🔴 [一句白話。]
- 【要驗證:[判準] 對帳日 [YYYY-MM-DD]】
- **P5** 🟢 [一句白話。]
- ——(從你的抱怨反推:[出處])
## 三、[分節標題:例如「關於產品要給誰」]
- **P6** 🟢 [一句白話。]
- ——(我猜的,請確認)
- 這張卡就是 [journeys.md](journeys.md) 的 **J-1**。 ← 卡片對應到某條旅程時這樣標
---
## 這份文件現在的狀態
> 這一段不是客套,是**交接資訊**。刪掉它,讀的人就不知道這份文件可信到什麼程度。
- **全部 N 張卡都還沒被勾過**(或:已勾 N/M)。紅綠燈是總管依「有沒有市場先例」判的,來源標記寫的是從哪裡讀到的。
- **請你做的只有一件事**:掃過去,看有沒有哪張卡「不是我的意思」或「這根本不重要」。搖頭的拿掉,你補的加上。
- ⚠️ 標明有沒有「我猜的」卡。凡是 PM/AI 推測補完、而非本人明示的內容,**必須帶「請確認」類標記**,不得混充原意。
- 紅卡的對帳日到了,會拿真實數據來對帳:**承諾成立,或換一個承諾**。賭錯不丟臉,賭了不認才是。
---
<!-- ════════ 寫這份文件的規矩(給總管看,不是內容的一部分)════════
【卡片格式】
- **P<編號>** <🟢或🔴> <一句白話>。
- ——(來源標記) ← 🟢 卡用這行
- 【要驗證:<判準> 對帳日 <日期>】 ← 🔴 卡改用這行,**缺了就是格式錯誤,會被擋**
【來源標記怎麼寫】
常見形式:(你說的)(你舉的例子:X)(從你的抱怨反推:X)(我猜的,請確認)
形式不限於此,可依實際來源自由描述。
唯一鐵律:**凡是推測補完、而非本人明示的內容,必須帶「請確認」類標記。**
【禁止技術名詞】
不准出現:API、DB、資料庫、WASM、MCP、endpoint、schema、SDK、CLI…
技術是達成手段,寫進各專案自己的規格,不寫進根。
⚠️ 自檢只掃**卡片本體**(`- **P...` 開頭那些行及其子項),
不掃這段說明區與 <!-- --> 註解——否則你在解釋規矩時提到的詞會被自己抓到。
【紅綠怎麼判】
能指著市場上活得好好的先例說「照這個做」=🟢(輪子卡,考過即關)
不能、解法是猜的=🔴(賭注卡,考過轉「對帳中」,等對帳日拿真實數據判決)
【誰能寫】
只有 orchestrator。engineersubagent 寫這個檔會被 hook 擋下——考生不能改考卷。
════════════════════════════════════════════════════════ -->