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:
@@ -4,8 +4,8 @@
|
||||
> 規則：動手前標 [🔄]，完成立刻標 [x]，不批次更新。
|
||||
> **每一項都標「服務哪條 Gherkin」**（G1–G7 定義見 `requirements.md` §四）。
|
||||
> 🟢 **status: active（2026-08-05 leo 回「開工」）**。
|
||||
> 進度：**防炸兩閘 ＋ Phase 0 ＋ Phase 1 已完成**（Phase 1 有兩項 ◐，見下）。
|
||||
> **Phase 2 以後未經確認不得開工**（總管指定：先停下驗 Gherkin）。
|
||||
> 進度：**防炸兩閘 ＋ Phase 0～3 全數完成**，兩件舊債已還清。
|
||||
> **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 0（role-lib）＋ Phase 2（有檔可擋）
|
||||
|
||||
- [ ] 3.1 `role-guard.sh`（J1＋J2＋J3，common）
|
||||
- [x] 3.1 `role-guard.sh`（J1＋J2＋J3，common）
|
||||
- 服務：**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`（J4＋J5＋J8，common）
|
||||
- [x] 3.2 `jdd-format-guard.sh`（J4＋J5＋J8，common）
|
||||
- 服務：**G1**、G3
|
||||
- J4：`root.md` 🔴 卡缺【要驗證＋對帳日】→ 擋並指行號
|
||||
- J5：`tasks.md` **新增**行缺站號 → 擋（Edit 看 `new_string`，Write 比對現檔差異）
|
||||
@@ -171,20 +171,20 @@
|
||||
- 驗收：三條各一組正例一組反例，共六次實測貼輸出
|
||||
- 注意：J5 只判**新增**行，改既有行不擋（否則格式修正都做不了）；誠實限制寫進註解
|
||||
|
||||
- [ ] 3.3 `station-done-guard.sh`（J6，common，掛 Stop/TaskCompleted）
|
||||
- [x] 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）
|
||||
- [x] 3.4 `regression-scope.sh`（J7，common）
|
||||
- 服務：**G3**
|
||||
- 行為：偵測站相關實作變動 → 讀 journeys.md 站點索引表 → 列需重考的 Journey/Gherkin
|
||||
- 驗收：改動某站的實作檔後，輸出正確列出該站被哪些 Journey 經過（貼輸出）
|
||||
- 注意：**提醒不阻擋**（exit 0）
|
||||
|
||||
- [ ] 3.5 `install-artifact-guard.sh`（S1，common）
|
||||
- [x] 3.5 `install-artifact-guard.sh`（S1，common）
|
||||
- 服務：**G6**
|
||||
- 行為：寫入 `.claude/hooks/`／`system-dev/` 範本區／plugin 安裝目錄 → 擋，
|
||||
提示「機制變更走框架/政策包 repo 提案」；`.sdt-framework-dev` 或 `SDT_FRAMEWORK_DEV=1` 放行
|
||||
@@ -192,7 +192,7 @@
|
||||
② 框架 repo（有 marker）編輯同路徑 → 放行。兩組都貼輸出
|
||||
- 注意：「範本區」的定義來自 manifest（class=overwrite 者），不要另寫一份路徑表
|
||||
|
||||
- [ ] 3.6 `orchestrator-scope-guard.sh`（S4，orchestrator profile 專屬）
|
||||
- [x] 3.6 `orchestrator-scope-guard.sh`（S4，orchestrator 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
|
||||
- orchestrator：root/journeys 摘要 ＋ 本 sprint **未點亮**站（治「起牀沒事做」）
|
||||
- repo：維持現行 principles/status/mistakes
|
||||
- 驗收：兩 profile 各開一次 session，貼注入內容對照（orchestrator 那份要出現站號）
|
||||
|
||||
- [ ] 3.8 hook 全鏈掛載順序實測（design §4.4）
|
||||
- [x] 3.8 hook 全鏈掛載順序實測（design §4.4）
|
||||
- 服務：**G2**、G6
|
||||
- 驗收：故意觸發多條規則的一次寫入，確認錯誤訊息來自**最外層**那條（範圍大的先擋）
|
||||
|
||||
|
||||
@@ -30,7 +30,14 @@ set -euo pipefail
|
||||
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
cd "$REPO_ROOT"
|
||||
|
||||
BASE="${BASE:-HEAD}"
|
||||
# ⚠️ 基準**不能**用 HEAD——這是實測踩到的：
|
||||
# 把 install.sh 改成清單驅動之後，HEAD 裡的硬編路徑從 35 條掉到 29 條，
|
||||
# **閘保護的範圍就跟著縮水 6 條**——而那 6 條正是還沒更新的舊實例仍然會去抓的。
|
||||
# 用 HEAD 當基準，閘會隨著每次提交自我弱化，最後變成「只保護今天的自己」。
|
||||
# ⇒ 基準必須是「**外面實際在跑的那一版**」＝最後一次真的發佈出去的 commit。
|
||||
# 發新版、且確認真的送出去之後，才把下面這行往前挪。
|
||||
LAST_RELEASED_DEFAULT="dc4fe67" # 1.18.0
|
||||
BASE="${BASE:-$LAST_RELEASED_DEFAULT}"
|
||||
|
||||
# ── 取出基準版本的兩支腳本 ────────────────────────────
|
||||
TMP="$(mktemp -d)"
|
||||
|
||||
+15
-2
@@ -414,9 +414,18 @@ build_hooks_json() {
|
||||
fi
|
||||
|
||||
# PreToolUse 依模組疊加。
|
||||
# 順序原則：**範圍大的擋在前**——這樣錯誤訊息會指向最根本的那條規則，
|
||||
# 順序原則：**範圍大的擋在前**——錯誤訊息才會指向最根本的那條規則，
|
||||
# 而不是讓人先修一個表層問題、修完才發現底下還有一條。
|
||||
# ① 改機制 這個檔你根本不該動（最外層）
|
||||
# ② 角色 你這個身分不該寫這種檔
|
||||
# ③ 位置 總管不該進成員 repo 動實作（僅總管實例）
|
||||
# ④ 格式 檔可以寫，但寫進去的內容格式不對
|
||||
# ⑤ 既有的 SDD／自訂禁令／機敏掃描
|
||||
local pt=()
|
||||
pt+=('{ "type": "command", "command": ".claude/hooks/install-artifact-guard.sh" }')
|
||||
pt+=('{ "type": "command", "command": ".claude/hooks/role-guard.sh" }')
|
||||
[ "$PROFILE" = "orchestrator" ] && pt+=('{ "type": "command", "command": ".claude/hooks/orchestrator-scope-guard.sh" }')
|
||||
pt+=('{ "type": "command", "command": ".claude/hooks/jdd-format-guard.sh" }')
|
||||
$WANT_SDD && pt+=('{ "type": "command", "command": ".claude/hooks/sdd-guard.sh" }')
|
||||
pt+=('{ "type": "command", "command": ".claude/hooks/pre-write-guard.sh" }')
|
||||
$WANT_WIKI && pt+=('{ "type": "command", "command": ".claude/hooks/wiki-secret-scan.sh" }')
|
||||
@@ -435,7 +444,11 @@ build_hooks_json() {
|
||||
if [ -n "$session_hooks" ]; then
|
||||
printf ' "SessionStart": [\n { "matcher": "startup|resume|clear",\n "hooks": [ %s ] }\n ],\n' "$session_hooks"
|
||||
fi
|
||||
printf ' "PreToolUse": [\n { "matcher": "Write|Edit",\n "hooks": [ %s ] }\n ]\n' "$pretool_hooks"
|
||||
printf ' "PreToolUse": [\n { "matcher": "Write|Edit|MultiEdit",\n "hooks": [ %s ] }\n ],\n' "$pretool_hooks"
|
||||
# 回歸考：動了實作之後才有意義 → PostToolUse（只提醒不擋）
|
||||
printf ' "PostToolUse": [\n { "matcher": "Write|Edit|MultiEdit",\n "hooks": [ { "type": "command", "command": ".claude/hooks/regression-scope.sh" } ] }\n ],\n'
|
||||
# 收工判準：站的考題全綠才算收，不是任務全關 → Stop
|
||||
printf ' "Stop": [\n { "hooks": [ { "type": "command", "command": ".claude/hooks/station-done-guard.sh" } ] }\n ]\n'
|
||||
printf ' }\n}\n'
|
||||
}
|
||||
|
||||
|
||||
+177
-56
@@ -298,67 +298,148 @@ echo ""
|
||||
# 改為：保留原檔不動，新版範本另存 pre-write-guard.template.sh，由使用者自行 diff 採納。
|
||||
keep_with_template ".claude/hooks/pre-write-guard.sh" "$TEMPLATE_URL/.claude/hooks/pre-write-guard.sh"
|
||||
|
||||
# ── 舊版硬編清單（僅在抓不到 manifest 時使用的退路）──────────
|
||||
# 保留它的唯一理由：來源不可達時，更新不該整個停擺。
|
||||
# ⚠️ 新增產物請改 template/manifest/*.tsv，**不要**再往這裡加——
|
||||
# 這份清單就是當初漂移的來源。
|
||||
legacy_update_list() {
|
||||
# ── 模板/邏輯檔：覆蓋更新 ──────────────────────────
|
||||
# 共用 hook 與指引
|
||||
update_file ".claude/commands/issue-handle.md" "$TEMPLATE_URL/.claude/commands/issue-handle.md"
|
||||
update_file "system-dev/VERSION" "$TEMPLATE_URL/system-dev/VERSION"
|
||||
update_file ".claude/commands/issue-handle.md" "$TEMPLATE_URL/.claude/commands/issue-handle.md"
|
||||
update_file "system-dev/VERSION" "$TEMPLATE_URL/system-dev/VERSION"
|
||||
|
||||
# Logseq 任務 marker 解析（單一真相源）：vault 萃取（/wiki-extract）與 tasks→Project
|
||||
# 投影共用同一套；任一模組在用就補/更新（邏輯檔，可覆蓋）。
|
||||
if $HAS_WIKI || $HAS_SDD; then
|
||||
update_file "system-dev/docs/4-guides/logseq-markers.md" "$TEMPLATE_URL/system-dev/docs/4-guides/logseq-markers.md"
|
||||
if $HAS_WIKI || $HAS_SDD; then
|
||||
update_file "system-dev/docs/4-guides/logseq-markers.md" "$TEMPLATE_URL/system-dev/docs/4-guides/logseq-markers.md"
|
||||
fi
|
||||
|
||||
if $HAS_WIKI; then
|
||||
# wiki 的「邏輯檔」：導航與 hooks，可覆蓋。wiki 資料在 system-dev/，hooks/commands 留 .claude/。
|
||||
update_file "system-dev/wiki/INDEX.md" "$TEMPLATE_URL/system-dev/wiki/INDEX.md"
|
||||
update_file ".claude/hooks/session-start-recall.sh" "$TEMPLATE_URL/.claude/hooks/session-start-recall.sh"
|
||||
update_file ".claude/hooks/wiki-secret-scan.sh" "$TEMPLATE_URL/.claude/hooks/wiki-secret-scan.sh"
|
||||
# 1.16.0：讓 wiki 真的被讀到的兩支（開場 push 全文解決不了「只讀開頭」，見 CHANGELOG）
|
||||
update_file ".claude/hooks/wiki-first-search.sh" "$TEMPLATE_URL/.claude/hooks/wiki-first-search.sh"
|
||||
update_file ".claude/hooks/subagent-wiki-guard.sh" "$TEMPLATE_URL/.claude/hooks/subagent-wiki-guard.sh"
|
||||
# 1.18.0：公開 mirror 落後偵測（手動同步的靜默失敗只有外部用戶會撞到）
|
||||
update_file ".claude/hooks/publish-lag-check.sh" "$TEMPLATE_URL/.claude/hooks/publish-lag-check.sh"
|
||||
update_file ".claude/commands/wiki-init.md" "$TEMPLATE_URL/.claude/commands/wiki-init.md"
|
||||
update_file ".claude/commands/wiki-capture.md" "$TEMPLATE_URL/.claude/commands/wiki-capture.md"
|
||||
update_file ".claude/commands/wiki-update.md" "$TEMPLATE_URL/.claude/commands/wiki-update.md"
|
||||
update_file ".claude/commands/wiki-recall.md" "$TEMPLATE_URL/.claude/commands/wiki-recall.md"
|
||||
# vault 增量萃取（Logseq/Obsidian → system-dev/wiki，冪等）：邏輯檔，可覆蓋。舊版沒有 → 當新檔補。
|
||||
update_file ".claude/commands/wiki-extract.md" "$TEMPLATE_URL/.claude/commands/wiki-extract.md"
|
||||
# Cowork（claude.ai）的 wiki 整理 skill：規則檔，可覆蓋
|
||||
update_file "system-dev/docs/SKILL.md" "$TEMPLATE_URL/system-dev/docs/SKILL.md"
|
||||
|
||||
# wiki 的「使用者資料」：絕不碰
|
||||
keep_file "system-dev/wiki/status.md"
|
||||
keep_file "system-dev/wiki/mistakes.md"
|
||||
# principles.md（1.10）：舊版沒有 → 補範本；已有 → 當用戶資料保留
|
||||
add_if_missing "system-dev/wiki/principles.md" "$TEMPLATE_URL/system-dev/wiki/principles.md"
|
||||
keep_file "system-dev/wiki/decisions-summary.md"
|
||||
keep_file "system-dev/wiki/TAXONOMY.md"
|
||||
keep_file "system-dev/wiki/.wikiignore"
|
||||
fi
|
||||
|
||||
if $HAS_SDD; then
|
||||
# SDD 範本與 hook：可覆蓋
|
||||
update_file "system-dev/docs/3-specs/TEMPLATE-sdd/design.md" "$TEMPLATE_URL/system-dev/docs/3-specs/TEMPLATE-sdd/design.md"
|
||||
update_file "system-dev/docs/3-specs/TEMPLATE-sdd/tasks.md" "$TEMPLATE_URL/system-dev/docs/3-specs/TEMPLATE-sdd/tasks.md"
|
||||
update_file "system-dev/docs/2-architecture/decisions/TEMPLATE-adr.md" "$TEMPLATE_URL/system-dev/docs/2-architecture/decisions/TEMPLATE-adr.md"
|
||||
update_file ".claude/commands/sdd-check.md" "$TEMPLATE_URL/.claude/commands/sdd-check.md"
|
||||
update_file ".claude/hooks/sdd-guard.sh" "$TEMPLATE_URL/.claude/hooks/sdd-guard.sh"
|
||||
|
||||
# SDD 生命週期鐵律（1.14，issue #6）：規則檔＋獨立檢查腳本＝邏輯檔可覆蓋；
|
||||
# pending-changes.md 裝著用戶的 proposal＝用戶資料，只補不覆蓋。
|
||||
# （issue #13 教訓：update 不補新檔會造成結構斷層，新檔必須在這裡鋪。）
|
||||
update_file "system-dev/docs/3-specs/SDD-LIFECYCLE.md" "$TEMPLATE_URL/system-dev/docs/3-specs/SDD-LIFECYCLE.md"
|
||||
add_if_missing "system-dev/docs/3-specs/pending-changes.md" "$TEMPLATE_URL/system-dev/docs/3-specs/pending-changes.md"
|
||||
update_file "system-dev/scripts/sdd-active-check.sh" "$TEMPLATE_URL/scripts/sdd-active-check.sh"
|
||||
|
||||
# tasks⇄Project 投影（issue #16）：邏輯檔，可覆蓋。舊版沒有 → add_if_missing 補。
|
||||
# 啟用狀態存遠端（acr push），不在這些檔裡，覆蓋不會關掉誰的同步。
|
||||
add_if_missing "system-dev/workflows/tasks-project-sync.yaml" "$TEMPLATE_URL/system-dev/workflows/tasks-project-sync.yaml"
|
||||
add_if_missing "system-dev/workflows/tasks-project-sync.local.sh" "$TEMPLATE_URL/system-dev/workflows/tasks-project-sync.local.sh"
|
||||
fi
|
||||
|
||||
}
|
||||
|
||||
# ── Manifest 驅動的更新（1.19.0：兩支腳本讀同一份清單）────────
|
||||
# 在這之前，這裡是一份**手抄的**檔案清單，install.sh 另有一份。兩份手抄必然漂移，
|
||||
# 而且已經漂了：wiki-first-search / subagent-wiki-guard / publish-lag-check /
|
||||
# decisions-summary 這四個，update 會處理但 install 從來不裝
|
||||
# ⇒ 乾淨安裝的人反而拿不到最新三版的招牌功能。
|
||||
# 現在兩支都讀 template/manifest/*.tsv，這類漂移在結構上不可能再發生。
|
||||
#
|
||||
# 讀不到 manifest（來源太舊／網路問題）→ 退回舊的硬編清單（見下方 legacy_update_list），
|
||||
# 不讓更新整個停擺。
|
||||
|
||||
MANIFEST_DIR="system-dev/.template-manifest.d"
|
||||
mkdir -p "$MANIFEST_DIR"
|
||||
|
||||
SDT_PROFILE="repo"
|
||||
[ -f "system-dev/.profile" ] && SDT_PROFILE="$(tr -d '[:space:]' < system-dev/.profile 2>/dev/null || echo repo)"
|
||||
|
||||
fetch_manifest() { # $1=名稱
|
||||
local out="$MANIFEST_DIR/$1.tsv"
|
||||
if curl -sSL "$TEMPLATE_URL/manifest/$1.tsv" -o "$out" 2>/dev/null \
|
||||
&& [ -s "$out" ] && ! looks_like_error_page "$out"; then
|
||||
return 0
|
||||
fi
|
||||
rm -f "$out"; return 1
|
||||
}
|
||||
|
||||
resolve_src() {
|
||||
case "$1" in
|
||||
T:*) printf '%s/%s' "$TEMPLATE_URL" "${1#T:}" ;;
|
||||
S:*) printf '%s/%s' "$REPO_RAW/scripts" "${1#S:}" ;;
|
||||
*) printf '' ;;
|
||||
esac
|
||||
}
|
||||
|
||||
want_module() {
|
||||
case "$1" in
|
||||
core) return 0 ;;
|
||||
wiki) $HAS_WIKI && return 0 || return 1 ;;
|
||||
sdd) $HAS_SDD && return 0 || return 1 ;;
|
||||
*) return 1 ;;
|
||||
esac
|
||||
}
|
||||
|
||||
apply_manifest() { # $1=manifest 檔
|
||||
local f="$1" src dest class module profile url
|
||||
[ -f "$f" ] || return 0
|
||||
while IFS=$'\t' read -r src dest class module profile; do
|
||||
case "$src" in ''|'#'*) continue ;; esac
|
||||
[ -z "${dest:-}" ] && continue
|
||||
want_module "$module" || continue
|
||||
url="$(resolve_src "$src")"
|
||||
case "$class" in
|
||||
dir) mkdir -p "$dest" 2>/dev/null || true ;;
|
||||
overwrite) [ -n "$url" ] && update_file "$dest" "$url" ;;
|
||||
add-if-missing) [ -n "$url" ] && add_if_missing "$dest" "$url" ;;
|
||||
keep-with-template) [ -n "$url" ] && keep_with_template "$dest" "$url" ;;
|
||||
keep) keep_file "$dest" ;;
|
||||
claude-md) CLAUDE_MD_SRC="$url" ;; # 憲法走界標補植，見下方專段
|
||||
*) : ;;
|
||||
esac
|
||||
done < "$f"
|
||||
}
|
||||
|
||||
CLAUDE_MD_SRC=""
|
||||
USED_MANIFEST=false
|
||||
if fetch_manifest common; then
|
||||
USED_MANIFEST=true
|
||||
fetch_manifest "$SDT_PROFILE" || true
|
||||
apply_manifest "$MANIFEST_DIR/common.tsv"
|
||||
apply_manifest "$MANIFEST_DIR/$SDT_PROFILE.tsv"
|
||||
else
|
||||
t "⚠️ 抓不到安裝清單，退回舊版硬編清單（功能較少但不會壞）" \
|
||||
"⚠️ Manifest unavailable; falling back to the legacy hardcoded list"
|
||||
legacy_update_list
|
||||
fi
|
||||
|
||||
if $HAS_WIKI; then
|
||||
# wiki 的「邏輯檔」：導航與 hooks，可覆蓋。wiki 資料在 system-dev/，hooks/commands 留 .claude/。
|
||||
update_file "system-dev/wiki/INDEX.md" "$TEMPLATE_URL/system-dev/wiki/INDEX.md"
|
||||
update_file ".claude/hooks/session-start-recall.sh" "$TEMPLATE_URL/.claude/hooks/session-start-recall.sh"
|
||||
update_file ".claude/hooks/wiki-secret-scan.sh" "$TEMPLATE_URL/.claude/hooks/wiki-secret-scan.sh"
|
||||
# 1.16.0：讓 wiki 真的被讀到的兩支（開場 push 全文解決不了「只讀開頭」，見 CHANGELOG）
|
||||
update_file ".claude/hooks/wiki-first-search.sh" "$TEMPLATE_URL/.claude/hooks/wiki-first-search.sh"
|
||||
update_file ".claude/hooks/subagent-wiki-guard.sh" "$TEMPLATE_URL/.claude/hooks/subagent-wiki-guard.sh"
|
||||
# 1.18.0：公開 mirror 落後偵測（手動同步的靜默失敗只有外部用戶會撞到）
|
||||
update_file ".claude/hooks/publish-lag-check.sh" "$TEMPLATE_URL/.claude/hooks/publish-lag-check.sh"
|
||||
update_file ".claude/commands/wiki-init.md" "$TEMPLATE_URL/.claude/commands/wiki-init.md"
|
||||
update_file ".claude/commands/wiki-capture.md" "$TEMPLATE_URL/.claude/commands/wiki-capture.md"
|
||||
update_file ".claude/commands/wiki-update.md" "$TEMPLATE_URL/.claude/commands/wiki-update.md"
|
||||
update_file ".claude/commands/wiki-recall.md" "$TEMPLATE_URL/.claude/commands/wiki-recall.md"
|
||||
# vault 增量萃取（Logseq/Obsidian → system-dev/wiki，冪等）：邏輯檔，可覆蓋。舊版沒有 → 當新檔補。
|
||||
update_file ".claude/commands/wiki-extract.md" "$TEMPLATE_URL/.claude/commands/wiki-extract.md"
|
||||
# Cowork（claude.ai）的 wiki 整理 skill：規則檔，可覆蓋
|
||||
update_file "system-dev/docs/SKILL.md" "$TEMPLATE_URL/system-dev/docs/SKILL.md"
|
||||
|
||||
# wiki 的「使用者資料」：絕不碰
|
||||
keep_file "system-dev/wiki/status.md"
|
||||
keep_file "system-dev/wiki/mistakes.md"
|
||||
# principles.md（1.10）：舊版沒有 → 補範本；已有 → 當用戶資料保留
|
||||
add_if_missing "system-dev/wiki/principles.md" "$TEMPLATE_URL/system-dev/wiki/principles.md"
|
||||
keep_file "system-dev/wiki/decisions-summary.md"
|
||||
keep_file "system-dev/wiki/TAXONOMY.md"
|
||||
keep_file "system-dev/wiki/.wikiignore"
|
||||
fi
|
||||
|
||||
if $HAS_SDD; then
|
||||
# SDD 範本與 hook：可覆蓋
|
||||
update_file "system-dev/docs/3-specs/TEMPLATE-sdd/design.md" "$TEMPLATE_URL/system-dev/docs/3-specs/TEMPLATE-sdd/design.md"
|
||||
update_file "system-dev/docs/3-specs/TEMPLATE-sdd/tasks.md" "$TEMPLATE_URL/system-dev/docs/3-specs/TEMPLATE-sdd/tasks.md"
|
||||
update_file "system-dev/docs/2-architecture/decisions/TEMPLATE-adr.md" "$TEMPLATE_URL/system-dev/docs/2-architecture/decisions/TEMPLATE-adr.md"
|
||||
update_file ".claude/commands/sdd-check.md" "$TEMPLATE_URL/.claude/commands/sdd-check.md"
|
||||
update_file ".claude/hooks/sdd-guard.sh" "$TEMPLATE_URL/.claude/hooks/sdd-guard.sh"
|
||||
|
||||
# SDD 生命週期鐵律（1.14，issue #6）：規則檔＋獨立檢查腳本＝邏輯檔可覆蓋；
|
||||
# pending-changes.md 裝著用戶的 proposal＝用戶資料，只補不覆蓋。
|
||||
# （issue #13 教訓：update 不補新檔會造成結構斷層，新檔必須在這裡鋪。）
|
||||
update_file "system-dev/docs/3-specs/SDD-LIFECYCLE.md" "$TEMPLATE_URL/system-dev/docs/3-specs/SDD-LIFECYCLE.md"
|
||||
add_if_missing "system-dev/docs/3-specs/pending-changes.md" "$TEMPLATE_URL/system-dev/docs/3-specs/pending-changes.md"
|
||||
update_file "system-dev/scripts/sdd-active-check.sh" "$TEMPLATE_URL/scripts/sdd-active-check.sh"
|
||||
|
||||
# tasks⇄Project 投影（issue #16）：邏輯檔，可覆蓋。舊版沒有 → add_if_missing 補。
|
||||
# 啟用狀態存遠端（acr push），不在這些檔裡，覆蓋不會關掉誰的同步。
|
||||
add_if_missing "system-dev/workflows/tasks-project-sync.yaml" "$TEMPLATE_URL/system-dev/workflows/tasks-project-sync.yaml"
|
||||
add_if_missing "system-dev/workflows/tasks-project-sync.local.sh" "$TEMPLATE_URL/system-dev/workflows/tasks-project-sync.local.sh"
|
||||
fi
|
||||
|
||||
# ── 自我更新：把最新的 update.sh / install.sh 抓到 system-dev/scripts/ ──
|
||||
# 這兩支在 main/scripts/ 下（不在 template/）；落地位置新版收進 system-dev/scripts/。
|
||||
update_file "system-dev/scripts/update.sh" "$REPO_RAW/scripts/update.sh"
|
||||
@@ -368,7 +449,47 @@ chmod +x .claude/hooks/*.sh system-dev/scripts/*.sh system-dev/workflows/*.sh 2>
|
||||
|
||||
# ── 使用者資料檔：絕不碰，但提醒「設定可能有新欄位要手動補」──
|
||||
keep_file ".claude/settings.json"
|
||||
keep_file "CLAUDE.md"
|
||||
|
||||
# ── CLAUDE.md 界標補植（1.19.0）────────────────────────
|
||||
# 1.18.x 以前的 CLAUDE.md 是「整份下載 ＋ 往後 append」，**沒有任何區段界標**。
|
||||
# 沒界標 ⇒ update 分不出「哪段是框架的、哪段是你寫的」⇒ 只能永遠不敢碰
|
||||
# ⇒ 框架後來改的憲法**永遠送不到既有實例**。這一段就是來解這個死結。
|
||||
#
|
||||
# 保守到底，寧可什麼都不做也不弄丟一個字：
|
||||
# · 已有界標 → 什麼都不做（冪等）
|
||||
# · 沒有界標 → 現有全文**原封不動**包進本地補充區，框架區重鋪在它上面
|
||||
# · 抓不到憲法範本 → 放棄補植、保留原檔（不留半殘的檔）
|
||||
# 最壞情況是同一段內容在兩區各一份，由人自己刪——我們不代刪。
|
||||
if [ -f "CLAUDE.md" ]; then
|
||||
if grep -q 'sdt:framework begin' CLAUDE.md 2>/dev/null; then
|
||||
keep_file "CLAUDE.md"
|
||||
elif [ -n "${CLAUDE_MD_SRC:-}" ]; then
|
||||
FW_TMP="$(mktemp)"
|
||||
if curl -sSL "$CLAUDE_MD_SRC" -o "$FW_TMP" 2>/dev/null && ! looks_like_error_page "$FW_TMP"; then
|
||||
cp CLAUDE.md "CLAUDE.md.before-markers"
|
||||
{
|
||||
printf '<!-- sdt:framework begin profile=%s version=%s sha256=%s -->\n' \
|
||||
"$SDT_PROFILE" "$REMOTE_VER" "$(sdt_sha256 "$FW_TMP" | cut -c1-12)"
|
||||
cat "$FW_TMP"
|
||||
printf '<!-- sdt:framework end -->\n\n'
|
||||
printf '<!-- sdt:local begin — 這一區是你的，update 永遠不會動它 -->\n'
|
||||
printf '\n<!-- ⬇️ 以下是你原本的 CLAUDE.md，一字未動地搬進來。\n'
|
||||
printf ' 上面的框架區從現在起由 template 維護；兩邊若有重複的段落，\n'
|
||||
printf ' 請自己刪掉這裡的舊版本（我們不敢代你刪）。\n'
|
||||
printf ' 原檔備份：CLAUDE.md.before-markers -->\n\n'
|
||||
cat "CLAUDE.md.before-markers"
|
||||
printf '\n<!-- sdt:local end -->\n'
|
||||
} > CLAUDE.md
|
||||
rm -f "$FW_TMP"
|
||||
MIGRATED+=("CLAUDE.md → 補上界標（原檔備份 CLAUDE.md.before-markers）")
|
||||
else
|
||||
rm -f "$FW_TMP"
|
||||
keep_file "CLAUDE.md"
|
||||
fi
|
||||
else
|
||||
keep_file "CLAUDE.md"
|
||||
fi
|
||||
fi
|
||||
|
||||
# ── 結果輸出 ───────────────────────────────────────
|
||||
echo ""
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
#!/bin/bash
|
||||
# install-artifact-guard.sh — 實例不准改機制（分離規格 防糾纏閘 S1）
|
||||
#
|
||||
# 掛 PreToolUse（matcher: Write|Edit|MultiEdit）。**排在整條鏈的最前面**——
|
||||
# 範圍最大的規則先擋，錯誤訊息才會指向最根本的那條。
|
||||
#
|
||||
# ── 擋什麼 ──────────────────────────────────────
|
||||
# 寫入「安裝產物區」＝ 框架發下來的機制檔（hook、範本、安裝腳本、plugin 目錄）。
|
||||
# 判準來自 system-dev/.template-manifest：**凡是框架管的檔（class=overwrite）都算**。
|
||||
# 不另寫一份路徑表——兩處維護同一條規則，遲早不同步。
|
||||
#
|
||||
# ── 為什麼要擋（實測數據，不是潔癖）─────────────────
|
||||
# 拿一個真實使用中的實例對照框架：6 支框架 hook 裡 **4 支已被手改**，
|
||||
# 另有 11 支是實例自己發明的，而**沒有任何機制知道這件事**。
|
||||
# 兩層後果：
|
||||
# ① 框架之後修好的 bug，永遠送不到那些被手改的檔
|
||||
# ② 手改的內容沒人審、也不會回饋給框架 ⇒ 同一個坑每個實例各踩一次
|
||||
# 機制要改就回上游改，一次修全家；在自己家裡改，只有自己受惠、且下次更新就孤立。
|
||||
#
|
||||
# ── 怎麼放行 ────────────────────────────────────
|
||||
# 框架 repo 自己開發時本來就要改這些檔 ⇒ 兩種放行方式：
|
||||
# · repo 根目錄有 .sdt-framework-dev 檔（框架 repo 自帶並 commit，零記憶負擔）
|
||||
# · 環境變數 SDT_FRAMEWORK_DEV=1（臨時情境）
|
||||
# 注意：官方**沒有** --framework-dev 這個 CLI 參數（實查，非記憶），別去找。
|
||||
#
|
||||
# 誠實限制：擋直接寫檔。bash 繞道改檔擋不到。留痕可審，不宣稱防偽。
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
. "$HOOK_DIR/lib/role-lib.sh" 2>/dev/null || exit 0
|
||||
|
||||
# ── 框架開發模式 → 放行 ────────────────────────────
|
||||
ROOT="$(sdt_repo_root)"
|
||||
[ -f "$ROOT/.sdt-framework-dev" ] && exit 0
|
||||
[ "${SDT_FRAMEWORK_DEV:-}" = "1" ] && exit 0
|
||||
|
||||
INPUT="$(cat)"
|
||||
FILE_PATH="$(sdt_file_path "$INPUT")"
|
||||
[ -z "$FILE_PATH" ] && exit 0
|
||||
REL="$(sdt_rel_path "$FILE_PATH")"
|
||||
|
||||
MANIFEST="$ROOT/system-dev/.template-manifest"
|
||||
|
||||
is_managed_artifact() {
|
||||
# ⓪ 使用者的自訂插槽 → 一律放行，**這一條要排在最前面**
|
||||
# 它們存在的目的就是給實例填自己的規則，而且 update 不會覆蓋它們。
|
||||
# （踩過：本 hook 的錯誤訊息叫人「去改 pre-write-guard.sh」，
|
||||
# 結果自己把那支也擋了——叫人走的路自己堵住，是最糟的一種閘。）
|
||||
case "$1" in
|
||||
.claude/hooks/pre-write-guard.sh) return 1 ;;
|
||||
*.template.sh|*.template.md) return 1 ;;
|
||||
.claude/settings.json) return 1 ;;
|
||||
esac
|
||||
# ① manifest 是權威：它說這是框架管的邏輯檔（class=overwrite）才擋
|
||||
if [ -f "$MANIFEST" ]; then
|
||||
if awk -F'\t' -v d="$1" '!/^#/ && $1==d && $2=="overwrite" {found=1} END{exit !found}' "$MANIFEST"; then
|
||||
return 0
|
||||
fi
|
||||
fi
|
||||
# ② manifest 還沒有／這個檔還沒登記（舊實例、或框架剛加的新檔）
|
||||
# → 退回路徑慣例，別因為沒表就整條規則失效
|
||||
case "$1" in
|
||||
.claude/hooks/*|.claude/plugins/*) return 0 ;;
|
||||
system-dev/scripts/*) return 0 ;;
|
||||
esac
|
||||
return 1
|
||||
}
|
||||
|
||||
if is_managed_artifact "$REL"; then
|
||||
cat >&2 <<EOF
|
||||
❌ BLOCKED by install-artifact-guard（防糾纏閘 S1）
|
||||
|
||||
這個檔是**框架發下來的機制**，實例不改機制。
|
||||
|
||||
路徑：$REL
|
||||
|
||||
正確做法：
|
||||
· 機制要改 → 回框架／政策包 repo 提案，bump 版本，實例再 update
|
||||
（一次修全家，別人也拿得到；在這裡改只有你受惠，而且下次更新就孤立）
|
||||
· 只是這個專案的特殊禁令 → 寫進 .claude/hooks/pre-write-guard.sh 的自訂區
|
||||
（那支就是留給你填的插槽，不會被 update 覆蓋）
|
||||
· 你就是在開發框架本身 → 這個 repo 根目錄該有 .sdt-framework-dev
|
||||
|
||||
為什麼擋（實測，不是原則潔癖）：
|
||||
對照過一個真實使用中的實例——6 支框架 hook 裡 4 支已被手改，
|
||||
而沒有任何人知道。那 4 支從此收不到框架的任何修正。
|
||||
EOF
|
||||
exit 2
|
||||
fi
|
||||
|
||||
exit 0
|
||||
@@ -0,0 +1,167 @@
|
||||
#!/bin/bash
|
||||
# jdd-format-guard.sh — PM 軌文件的格式閘（JDD 規則 J4＋J5＋J8）
|
||||
#
|
||||
# 掛 PreToolUse（matcher: Write|Edit|MultiEdit）。
|
||||
#
|
||||
# J4 root.md 的 🔴 卡缺【要驗證 ＋ 對帳日】 → 擋
|
||||
# 為什麼：紅卡＝賭注。賭注沒有「賭輸了怎麼知道」和「什麼時候結算」，
|
||||
# 就會永遠是「還在做」，永遠不必認賠——那不是賭注，是藉口。
|
||||
#
|
||||
# J5 tasks.md **新增**的任務缺站號 → 擋
|
||||
# 為什麼：sprint 的單位是站。任務不掛站，就沒有人答得出
|
||||
# 「這個任務不做，哪一站會掛？」——那正是認領流程唯一的問題。
|
||||
#
|
||||
# J8 root.md／journeys.md 出現技術名詞 → 擋
|
||||
# 為什麼：這兩份是給不懂技術的人讀的。技術是達成手段，寫進各專案自己的規格。
|
||||
#
|
||||
# ── J8 的關鍵細節：只掃「卡片／站的本體」，其餘一概不掃 ──────────
|
||||
# 踩過兩次同一類坑（第二次是本閘自己被真實文件抓包）：
|
||||
# ① 文件開頭的規矩說明裡寫「各 repo 的規格」→ 被自己的自檢抓到
|
||||
# ② 文件結尾「這卷還缺什麼」的自述裡提到跨 repo 鏈路 → 又被抓到
|
||||
# 兩者都不是卡片內容，是**文件在講自己**。
|
||||
# 閘要是連這些都掃，人就只能把說明寫得不清不楚來換綠燈，本末倒置。
|
||||
#
|
||||
# 第一版用「排除法」（跳過 > 引言、註解、標題）——不夠，因為自述段是普通條列。
|
||||
# 改用**正面圈定**：只掃真正的內容體
|
||||
# · root.md ＝ `- **P<n>**` 卡片行 ＋ 它底下的縮排子項
|
||||
# · journeys.md ＝ `#### S<n>` 站標題以下、到下一個標題之前的內文
|
||||
# 自述段、說明區、索引表因為不在這兩種範圍裡，自然就不會被掃到——
|
||||
# 不必為它們一個個開例外。
|
||||
#
|
||||
# 誠實限制：只認字面與行首形狀。
|
||||
# 「把技術概念用白話包裝起來」它看不出來（那要人讀）；
|
||||
# 用 bash 繞道改檔也擋不到。價值是擋掉明顯的格式錯誤與手滑，不是技術防偽。
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
. "$HOOK_DIR/lib/role-lib.sh" 2>/dev/null || exit 0
|
||||
|
||||
INPUT="$(cat)"
|
||||
FILE_PATH="$(sdt_file_path "$INPUT")"
|
||||
[ -z "$FILE_PATH" ] && exit 0
|
||||
REL="$(sdt_rel_path "$FILE_PATH")"
|
||||
|
||||
CONTENT="$(sdt_write_content "$INPUT")"
|
||||
[ -z "$CONTENT" ] && exit 0
|
||||
|
||||
TECH_TERMS='API|SDK|CLI|MCP|WASM|endpoint|schema|webhook|resturl|JSON|YAML|SQL|資料庫|後端|前端|部署|repo|commit|branch'
|
||||
|
||||
# 正面圈定要掃的行（見上方說明）：
|
||||
# root.md → `- **P<n>**` 卡片行 ＋ 其縮排子項
|
||||
# journeys.md → `#### S<n>` 站標題以下到下一個標題之前的內文
|
||||
card_body_only() { # $1=root|journeys
|
||||
if [ "$1" = "root" ]; then
|
||||
awk '
|
||||
/<!--/ { inc=1 } inc { if (/-->/) inc=0; next }
|
||||
/^[[:space:]]*-[[:space:]]*\*\*P[0-9]+\*\*/ { incard=1; print NR "\t" $0; next }
|
||||
incard && /^[[:space:]]+[-*]/ { print NR "\t" $0; next } # 卡片的縮排子項
|
||||
{ incard=0 }
|
||||
'
|
||||
else
|
||||
awk '
|
||||
/<!--/ { inc=1 } inc { if (/-->/) inc=0; next }
|
||||
/^####[[:space:]]*S[0-9]+/ { instation=1; next } # 進入某一站
|
||||
/^#/ { instation=0; next } # 任何標題結束該站
|
||||
instation && /^[[:space:]]*>/ { next } # 站內引言仍不掃
|
||||
instation && /^[[:space:]]*$/ { next }
|
||||
instation { print NR "\t" $0 }
|
||||
'
|
||||
fi
|
||||
}
|
||||
|
||||
fail() { # $1=規則 $2=標題 $3=細節
|
||||
cat >&2 <<EOF
|
||||
❌ BLOCKED by jdd-format-guard（規則 $1）
|
||||
|
||||
$2
|
||||
|
||||
檔案：$REL
|
||||
|
||||
$3
|
||||
EOF
|
||||
exit 2
|
||||
}
|
||||
|
||||
# ── J4：root.md 的紅卡必須附【要驗證 ＋ 對帳日】────────
|
||||
if printf '%s' "$REL" | grep -q 'root\.md$'; then
|
||||
# 逐張紅卡檢查：紅卡行之後、下一張卡之前，要出現「對帳日」
|
||||
MISSING="$(printf '%s' "$CONTENT" | awk '
|
||||
/^[[:space:]]*-[[:space:]]*\*\*P[0-9]+\*\*/ {
|
||||
if (pending != "" && !found) { print pending }
|
||||
found = 0
|
||||
if ($0 ~ /🔴/) { pending = NR "\t" $0 } else { pending = "" }
|
||||
next
|
||||
}
|
||||
pending != "" && /對帳日/ { found = 1 }
|
||||
END { if (pending != "" && !found) print pending }
|
||||
')"
|
||||
if [ -n "$MISSING" ]; then
|
||||
fail "J4" "紅卡（🔴）少了【要驗證 ＋ 對帳日】。" \
|
||||
" 下列紅卡沒有對帳行：
|
||||
$(printf '%s' "$MISSING" | sed 's/^/ 行 /' | cut -c1-120)
|
||||
|
||||
補成這樣：
|
||||
- **P9** 🔴 <一句白話>。
|
||||
- 【要驗證：<能用真實數字或事實判真假的判準> ｜ 對帳日 YYYY-MM-DD】
|
||||
|
||||
為什麼擋：紅卡是賭注。沒有判準和結算日的賭注，永遠不必認賠——
|
||||
那不是賭注，是把「還沒做到」講得像「正在做」。"
|
||||
fi
|
||||
fi
|
||||
|
||||
# ── J8：root.md／journeys.md 不准出現技術名詞 ────────
|
||||
case "$REL" in
|
||||
*root.md|*journeys.md)
|
||||
KIND="journeys"; printf '%s' "$REL" | grep -q 'root\.md$' && KIND="root"
|
||||
HITS="$(printf '%s' "$CONTENT" | card_body_only "$KIND" | grep -inE "$TECH_TERMS" | head -8 || true)"
|
||||
if [ -n "$HITS" ]; then
|
||||
fail "J8" "PM 軌文件出現技術名詞。" \
|
||||
" 命中（只掃卡片本體，已排除說明區／註解／標題）：
|
||||
$(printf '%s' "$HITS" | cut -c1-120 | sed 's/^/ /')
|
||||
|
||||
怎麼修：
|
||||
· 把它翻成「使用者感覺得到的事」——例如不是「呼叫 API 取得資料」，
|
||||
而是「我按下去之後，畫面上出現我的東西」
|
||||
· 真的必須談技術 → 那句話屬於各專案自己的規格，不屬於這裡
|
||||
|
||||
為什麼擋：這兩份文件唯一的讀者是「不懂技術但要點頭或搖頭的人」。
|
||||
出現一個他看不懂的詞，他就沒辦法判斷這張卡是不是他的意思。"
|
||||
fi
|
||||
;;
|
||||
esac
|
||||
|
||||
# ── J5：tasks.md 新增的任務必須掛站號 ─────────────────
|
||||
if printf '%s' "$REL" | grep -q 'tasks\.md$'; then
|
||||
# 只看這次要寫入的內容裡「長得像新任務」的行
|
||||
NEWTASKS="$(printf '%s' "$CONTENT" | grep -nE '^[[:space:]]*-[[:space:]]*\[[ x~!🔄]\][[:space:]]*[0-9]+\.[0-9]+' || true)"
|
||||
if [ -n "$NEWTASKS" ]; then
|
||||
# 站號標注：任務行本身或緊接的子項出現 S<n> / S-<n> / 「服務：S…」
|
||||
NOSTATION="$(printf '%s' "$CONTENT" | awk '
|
||||
/^[[:space:]]*-[[:space:]]*\[[ x~!🔄]\][[:space:]]*[0-9]+\.[0-9]+/ {
|
||||
if (pending != "" && !found) print pending
|
||||
pending = NR "\t" $0; found = 0
|
||||
if ($0 ~ /S-?[0-9]+/) found = 1
|
||||
next
|
||||
}
|
||||
pending != "" && /S-?[0-9]+/ { found = 1 }
|
||||
/^[[:space:]]*$/ { if (pending != "" && !found) { print pending; pending=""; found=0 } }
|
||||
END { if (pending != "" && !found) print pending }
|
||||
')"
|
||||
if [ -n "$NOSTATION" ]; then
|
||||
fail "J5" "新增的任務沒有標注它服務哪一站。" \
|
||||
" 下列任務缺站號：
|
||||
$(printf '%s' "$NOSTATION" | cut -c1-120 | sed 's/^/ 行 /')
|
||||
|
||||
補成這樣：
|
||||
- [ ] 1.1 <任務描述>
|
||||
- 服務：S3（我按一次就裝到自己的地方）
|
||||
- 驗收：<客觀可驗證的完成標準>
|
||||
|
||||
為什麼擋：sprint 的單位是站。任務不掛站，就沒有人答得出認領流程唯一的問題——
|
||||
「這個任務不做，指定站的考題會掛嗎？」答不出來，這個任務就沒有理由在這一期做。"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
exit 0
|
||||
@@ -0,0 +1,54 @@
|
||||
#!/bin/bash
|
||||
# regression-scope.sh — 動到某一站的東西 → 告訴你要重考哪些題（JDD 規則 J7）
|
||||
#
|
||||
# 掛 PostToolUse（Write|Edit|MultiEdit）。**只提醒，不阻擋**（exit 0）。
|
||||
#
|
||||
# ── 為什麼只提醒 ────────────────────────────────
|
||||
# 重考範圍是判斷題不是是非題——擋下來只會讓人為了繼續工作而亂填。
|
||||
# 它要消滅的失敗模式只有一個：**改完東西，忘了它會弄壞哪幾站**。
|
||||
# （「S3 安裝流程變了 → 後面 S4~S9 全部要重考」這種事，
|
||||
# 不查索引表沒有人會自己想到。）
|
||||
#
|
||||
# ── 判斷「動到哪一站」怎麼做 ─────────────────────
|
||||
# 靠 journeys.md 的**站點索引**。索引裡若有登記關聯路徑就用它；
|
||||
# 沒有登記時退回一個誠實的作法：只要動到 code，就把索引整份摘要推一次，
|
||||
# 讓人自己對——**不猜**。猜錯的重考範圍比沒有更危險（會讓人以為已經涵蓋了）。
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
. "$HOOK_DIR/lib/role-lib.sh" 2>/dev/null || exit 0
|
||||
|
||||
INPUT="$(cat)"
|
||||
FILE_PATH="$(sdt_file_path "$INPUT")"
|
||||
[ -z "$FILE_PATH" ] && exit 0
|
||||
REL="$(sdt_rel_path "$FILE_PATH")"
|
||||
|
||||
# 只對「實作變動」出聲；改文件不必每次都喊
|
||||
case "$REL" in
|
||||
src/*|*/src/*|*.py|*.ts|*.tsx|*.js|*.go|*.rs|*.sh|*.java|*.rb|*.vue|*.svelte) ;;
|
||||
*) exit 0 ;;
|
||||
esac
|
||||
|
||||
ROOT="$(sdt_repo_root)"
|
||||
JOURNEYS=""
|
||||
for cand in "$ROOT/system-dev/docs/journeys.md" "$ROOT/../system-dev/docs/journeys.md"; do
|
||||
[ -f "$cand" ] && JOURNEYS="$cand" && break
|
||||
done
|
||||
[ -z "$JOURNEYS" ] && exit 0 # 沒有 PM 軌文件（多數成員 repo）→ 安靜
|
||||
|
||||
# 取站點索引段（「附：站點索引」以下）
|
||||
INDEX="$(awk '/^##[[:space:]]*附.*站點索引/{f=1} f' "$JOURNEYS" 2>/dev/null | head -60)"
|
||||
[ -z "$INDEX" ] && exit 0
|
||||
|
||||
echo "════════════════════════════════════════════════"
|
||||
echo "🔁 回歸考提醒（J7）：你動了實作，查一下要重考哪幾題"
|
||||
echo "════════════════════════════════════════════════"
|
||||
echo " 剛動的：$REL"
|
||||
echo ""
|
||||
printf '%s\n' "$INDEX" | sed 's/^/ /'
|
||||
echo ""
|
||||
echo " ⚠️ 這份索引是「站 → 被哪些旅程經過 → 改動時重考什麼」。"
|
||||
echo " 對照你剛改的東西屬於哪一站，把**下游**也一起重考——"
|
||||
echo " 安裝那類的站一變，後面全部都要重來。"
|
||||
exit 0
|
||||
@@ -0,0 +1,153 @@
|
||||
#!/bin/bash
|
||||
# role-guard.sh — 角色封路：誰能寫什麼（JDD 規則 J1＋J2＋J3）
|
||||
#
|
||||
# 掛 PreToolUse（matcher: Write|Edit|MultiEdit）。
|
||||
#
|
||||
# ── 為什麼三條規則合成一支 hook ─────────────────────────
|
||||
# J1 orchestrator 不准寫 code
|
||||
# J2 orchestrator 不准寫技術軌文件（任務池／規格）
|
||||
# J3 engineer 不准改考卷（旅程／根文件／任何考題）
|
||||
# 三條都是「同一個 hook 事件 × 同一份身分判定 × 同一張路徑表」。
|
||||
# 拆三支＝解析三次 JSON、三處維護同一張表，改一條規則要記得改三個檔。
|
||||
# 規則編號保留在程式碼與錯誤訊息裡，追溯不會少。
|
||||
#
|
||||
# ── J3 是命門 ───────────────────────────────────────
|
||||
# 考生不能改考卷。這條沒守住，整套 PM 軌就是裝飾品：
|
||||
# 考題沒過的人，只要改一下考題就「過了」，而且沒有人會發現。
|
||||
# 所以 J3 攔的不只是檔案，還包括 md 檔裡的 Gherkin 區塊——
|
||||
# 考題常常就住在別的文件裡。
|
||||
#
|
||||
# 誠實限制：擋的是「直接寫檔」這個語法層動作。
|
||||
# 用 bash 繞道（sed -i / cat > / python 改檔）擋不到。
|
||||
# 價值是「想跳過會被抓到 ＋ 留痕可審」，不是技術防偽。絕不聲稱不可能繞過。
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
# shellcheck source=lib/role-lib.sh
|
||||
. "$HOOK_DIR/lib/role-lib.sh" 2>/dev/null || exit 0 # 函式庫不在就放行（容錯）
|
||||
|
||||
INPUT="$(cat)"
|
||||
FILE_PATH="$(sdt_file_path "$INPUT")"
|
||||
[ -z "$FILE_PATH" ] && exit 0 # 拿不到路徑 → 放行，寧可漏擋不誤殺
|
||||
|
||||
REL="$(sdt_rel_path "$FILE_PATH")"
|
||||
ROLE="$(sdt_role)"
|
||||
|
||||
# 身分矩陣先驗（成員 repo × orchestrator 這格不存在）
|
||||
sdt_assert_identity || exit 2
|
||||
|
||||
# ── 路徑分類 ───────────────────────────────────────
|
||||
is_code_path() {
|
||||
case "$1" in
|
||||
src/*|*/src/*) return 0 ;;
|
||||
*.py|*.ts|*.tsx|*.js|*.jsx|*.go|*.rs|*.java|*.rb|*.c|*.h|*.cpp|*.sh|*.bash|*.zsh) return 0 ;;
|
||||
*.sql|*.vue|*.svelte|*.swift|*.kt|*.php) return 0 ;;
|
||||
esac
|
||||
return 1
|
||||
}
|
||||
|
||||
is_tech_track_doc() { # 技術軌文件：任務池與規格
|
||||
case "$1" in
|
||||
*tasks.md|*requirements.md|*design.md) return 0 ;;
|
||||
esac
|
||||
return 1
|
||||
}
|
||||
|
||||
is_exam_paper() { # 考卷：旅程／根文件／獨立考題檔
|
||||
case "$1" in
|
||||
*journeys.md|*root.md|*.feature) return 0 ;;
|
||||
esac
|
||||
return 1
|
||||
}
|
||||
|
||||
# md 檔內含 Gherkin 區塊？（考題常寄住在別的文件裡）
|
||||
content_has_gherkin() {
|
||||
local c
|
||||
c="$(sdt_write_content "$INPUT")"
|
||||
[ -z "$c" ] && return 1
|
||||
# ```gherkin 圍籬，或 journeys.md 的考題行式（- **G-1.1**），或 Given/When/Then 三件成組
|
||||
printf '%s' "$c" | grep -qiE '```[[:space:]]*gherkin' && return 0
|
||||
printf '%s' "$c" | grep -qE '^\s*-?\s*\*\*G-[0-9]+\.[0-9]+\*\*' && return 0
|
||||
if printf '%s' "$c" | grep -qE '^\s*-?\s*Given ' \
|
||||
&& printf '%s' "$c" | grep -qE '^\s*-?\s*When ' \
|
||||
&& printf '%s' "$c" | grep -qE '^\s*-?\s*Then '; then
|
||||
return 0
|
||||
fi
|
||||
return 1
|
||||
}
|
||||
|
||||
block() { # $1=規則編號 $2=標題 $3=正確做法（多行）
|
||||
cat >&2 <<EOF
|
||||
❌ BLOCKED by role-guard（規則 $1）
|
||||
|
||||
$2
|
||||
|
||||
身分：role=$ROLE（來源：AGENT_ROLE 環境變數／依安裝位置推定）
|
||||
路徑：$REL
|
||||
|
||||
$3
|
||||
EOF
|
||||
exit 2
|
||||
}
|
||||
|
||||
# ── J1／J2：orchestrator 的禁區 ─────────────────────
|
||||
if [ "$ROLE" = "orchestrator" ]; then
|
||||
if is_code_path "$REL"; then
|
||||
block "J1" "總管（PM）不寫 code。" \
|
||||
" 你的工作是決定「要點亮哪幾站、考題是什麼」，不是自己下去寫。
|
||||
|
||||
正確做法：
|
||||
· 把它變成一個掛站號的任務，交給該 repo 的 engineer
|
||||
· 你要的結果寫成考題（Gherkin），不是寫成實作
|
||||
|
||||
為什麼擋：PM 自己下去寫 code，就沒有人在看「零件之間有沒有人掉進縫裡」了
|
||||
——那正是這個角色唯一不能被取代的價值。"
|
||||
fi
|
||||
if is_tech_track_doc "$REL"; then
|
||||
block "J2" "總管（PM）不寫技術軌文件（任務池／規格）。" \
|
||||
" 任務池與規格屬於 engineer。你對它們**只讀**。
|
||||
|
||||
正確做法：
|
||||
· 要調整優先順序 → 改 sprint.md 的指定站，讓認領流程自己去挑任務
|
||||
· 覺得少了任務 → 說出「哪一站的考題會掛」，由 engineer 認領或新增
|
||||
· 要改驗收標準 → 改 journeys.md 的考題（那是你的檔）
|
||||
|
||||
為什麼擋：你一旦動手改任務清單，就等於繞過「先認領→不足才新增」的順序，
|
||||
很快會長出第二份平行的任務池，兩邊不同步。"
|
||||
fi
|
||||
fi
|
||||
|
||||
# ── J3：engineer 不准改考卷（命門）─────────────────
|
||||
if [ "$ROLE" = "engineer" ]; then
|
||||
if is_exam_paper "$REL"; then
|
||||
block "J3" "考生不能改考卷。" \
|
||||
" journeys.md／root.md／考題檔是 PM 的檔案，engineer 只能讀當期指定站的段落。
|
||||
|
||||
正確做法：
|
||||
· 考題沒過 → 去把東西做對，不是把題目改掉
|
||||
· 真的認為題目出錯了（判準不合理、站定義有誤）→ **回報 PM**，由他決定改不改
|
||||
· 你需要的是「這站到底要什麼」→ 讀，不要寫
|
||||
|
||||
為什麼這條是命門：考題沒過的人只要改一下考題就「過了」，
|
||||
而且沒有任何人會發現。這樣整套驗收就是裝飾品。"
|
||||
fi
|
||||
# md 檔本身不是考卷，但內容含考題 → 一樣擋（考題常寄住在別的文件裡）
|
||||
case "$REL" in
|
||||
*.md)
|
||||
if content_has_gherkin; then
|
||||
block "J3" "考生不能改考卷（這次寫入的內容含考題）。" \
|
||||
" 這個檔名不是考卷，但你要寫進去的內容裡有 Gherkin 考題（Given／When／Then 或 G-x.y）。
|
||||
|
||||
正確做法：
|
||||
· 要記錄「我做到哪了」→ 寫 wiki／status，不要在文件裡複寫考題
|
||||
· 要提出新考題 → 回報 PM，由他寫進 journeys.md
|
||||
|
||||
為什麼擋：考題散落成兩份就會不同步，
|
||||
而不同步的那一刻起，「全綠」代表什麼就沒人說得準了。"
|
||||
fi
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
|
||||
exit 0
|
||||
@@ -26,6 +26,35 @@ if [ -d ".claude/wiki" ] && [ ! -f "$STATUS_FILE" ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# ── profile 分流（1.19.0）：總管起牀先看「還缺哪幾站」──────────
|
||||
# 為什麼加這段：自動起牀的排程／新 session 最常見的失敗模式是
|
||||
# 「醒來讀到一堆過期任務，只能空轉收工」。治它的不是更勤勞的提醒，
|
||||
# 是**讓它一睜眼就有明確的『離通關還缺什麼』**——那就是本期指定站。
|
||||
# 成員 repo 不需要這段（它的工作單位是任務不是站），維持原行為。
|
||||
SDT_PROFILE="repo"
|
||||
[ -f "system-dev/.profile" ] && SDT_PROFILE="$(tr -d '[:space:]' < system-dev/.profile 2>/dev/null || echo repo)"
|
||||
|
||||
if [ "$SDT_PROFILE" = "orchestrator" ] && [ -f "system-dev/docs/sprint.md" ]; then
|
||||
echo "════════════════════════════════════════════════"
|
||||
echo "🎯 本期要點亮哪幾站（進度語言＝站，不是任務數）"
|
||||
echo "════════════════════════════════════════════════"
|
||||
# 期間、交付、現在幾站亮了——只取前 25 行，不整份灌
|
||||
sed -n '/^## 本期/,/^## 認領流程/p' system-dev/docs/sprint.md 2>/dev/null \
|
||||
| grep -vE '^## 認領流程' | head -25
|
||||
echo ""
|
||||
echo "📌 回報形式：「J-x 已點亮 n/m 站」。狀態只有 ✅ 通（附實測證據）／◐ 半通／❌ 斷。"
|
||||
echo " 「程式碼寫完了」不是狀態。"
|
||||
echo ""
|
||||
if [ -f "system-dev/docs/root.md" ]; then
|
||||
DUE="$(grep -oE '對帳日[^｜】]*' system-dev/docs/root.md 2>/dev/null | head -3)"
|
||||
if [ -n "$DUE" ]; then
|
||||
echo "🔴 紅卡對帳日（到期要拿真實數據判決：承諾成立，或換一個承諾）："
|
||||
printf '%s\n' "$DUE" | sed 's/^/ /'
|
||||
echo ""
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# 三個 push 檔都沒有 → 安靜退出，不干擾還沒 /wiki-init 的專案
|
||||
if [ ! -f "$STATUS_FILE" ] && [ ! -f "$PRINCIPLES_FILE" ] && [ ! -f "$MISTAKES_FILE" ]; then
|
||||
exit 0
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
#!/bin/bash
|
||||
# station-done-guard.sh — 收工判準是「站的考題全綠」，不是「任務全關」（JDD 規則 J6）
|
||||
#
|
||||
# 掛 Stop / SubagentStop（收工那一刻），只在 orchestrator 實例生效。
|
||||
#
|
||||
# ── 它在攔什麼 ──────────────────────────────────
|
||||
# 「任務都關了 ⇒ 這期做完了」——這句話是整套假綠的源頭。
|
||||
# 任務是**技術軌**的單位（沿系統結構切），站是**PM 軌**的單位（沿人的經歷切）。
|
||||
# 零件全部做完、每個都對，人還是可能掉進零件之間的縫裡。
|
||||
# 所以收工只認一件事：**指定站的考題有沒有實測通過**。
|
||||
#
|
||||
# ── 它不做什麼（重要）────────────────────────────
|
||||
# 它**不會**自己去跑考題判斷過沒過——Gherkin 的 Then 寫的是「使用者看到什麼」，
|
||||
# 那本來就不是 shell 判得出來的。它做的是：在你要收工的那一刻，
|
||||
# 把「指定站」和「它們現在的狀態」攤在你眼前，逼你面對還沒填的那幾格。
|
||||
# 自動判綠反而危險：那會製造一個「機器說過了」的假權威。
|
||||
#
|
||||
# 誠實限制：讀的是 sprint.md／journeys.md 的文字狀態。
|
||||
# 有人亂填「✅」它看不出來——它擋的是「忘了填」與「用任務數充當進度」，不是造假。
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
. "$HOOK_DIR/lib/role-lib.sh" 2>/dev/null || exit 0
|
||||
|
||||
[ "$(sdt_scope)" = "orchestrator" ] || exit 0
|
||||
|
||||
ROOT="$(sdt_repo_root)"
|
||||
SPRINT="$ROOT/system-dev/docs/sprint.md"
|
||||
[ -f "$SPRINT" ] || exit 0 # 還沒開始用站號 sprint → 不干擾
|
||||
|
||||
# 本期指定的站
|
||||
STATIONS="$(grep -oE 'S-?[0-9]+' "$SPRINT" 2>/dev/null | sort -u | tr '\n' ' ')"
|
||||
[ -z "$STATIONS" ] && exit 0
|
||||
|
||||
# 還沒亮的站（sprint.md 的「❌ 未亮」「◐ 半通」段）
|
||||
UNLIT="$(awk '/未亮|◐|半通/ {print}' "$SPRINT" 2>/dev/null | grep -oE 'S-?[0-9]+' | sort -u | tr '\n' ' ')"
|
||||
|
||||
echo "════════════════════════════════════════════════"
|
||||
echo "🚦 收工判準：站的考題全綠，不是任務全關（J6）"
|
||||
echo "════════════════════════════════════════════════"
|
||||
echo " 本期指定站：${STATIONS}"
|
||||
if [ -n "$UNLIT" ]; then
|
||||
echo " ⚠️ 還沒亮：${UNLIT}"
|
||||
echo ""
|
||||
echo " 這幾站沒亮，這期就還沒收。收工前擇一："
|
||||
echo " · 真的通了 → 在 journeys.md 標記點亮，**附實測輸出**（不是「應該會過」）"
|
||||
echo " · 半通 → 標 ◐ 並寫明缺什麼"
|
||||
echo " · 沒通 → 標 ❌ 誠實留著，搬到下一期並寫一行為什麼"
|
||||
echo ""
|
||||
echo " ⛔ 不准用「任務都關了」當收工理由——那是技術軌的單位，不是驗收線。"
|
||||
else
|
||||
echo " ✅ 本期指定站都已標記點亮。記得每一站都要附得出實測證據。"
|
||||
fi
|
||||
echo ""
|
||||
exit 0
|
||||
@@ -52,6 +52,17 @@ T:.claude/hooks/pre-write-guard.sh .claude/hooks/pre-write-guard.sh keep-with-te
|
||||
T:.claude/hooks/lib/role-lib.sh .claude/hooks/lib/role-lib.sh overwrite core common
|
||||
T:.claude/hooks/publish-lag-check.sh .claude/hooks/publish-lag-check.sh overwrite core common
|
||||
|
||||
# ── JDD 封路 hook（角色軸屬 common，兩個 profile 都裝）──
|
||||
# 為什麼 role-guard 不按 profile 分裝（設計決策 D5）：
|
||||
# 總管 repo 裡也會派 engineer subagent（身分矩陣右上角那一格）。
|
||||
# 若「考生不能改考卷」只裝在成員 repo，那顆 subagent 在總管 repo 裡就改得動考卷
|
||||
# ——而總管 repo 正是考卷所在地，等於這條規則在最該生效的地方失效。
|
||||
T:.claude/hooks/install-artifact-guard.sh .claude/hooks/install-artifact-guard.sh overwrite core common
|
||||
T:.claude/hooks/role-guard.sh .claude/hooks/role-guard.sh overwrite core common
|
||||
T:.claude/hooks/jdd-format-guard.sh .claude/hooks/jdd-format-guard.sh overwrite core common
|
||||
T:.claude/hooks/station-done-guard.sh .claude/hooks/station-done-guard.sh overwrite core common
|
||||
T:.claude/hooks/regression-scope.sh .claude/hooks/regression-scope.sh overwrite core common
|
||||
|
||||
# ── wiki 模組 ──
|
||||
- system-dev/wiki dir wiki common
|
||||
- system-dev/wiki/cards dir wiki common
|
||||
|
||||
|
@@ -4,13 +4,19 @@
|
||||
# root.md ＋ journeys.md（PM 軌），裡面的 agent 預設身分是 orchestrator
|
||||
# （可寫 root/journeys/sprint，**禁寫 code、禁改 tasks/requirements/design**）。
|
||||
#
|
||||
# ⚠️ 本表目前只有憲法一項。Phase 2（JDD 文件範本：root.md / journeys.md / sprint /
|
||||
# triage-map / plugin-load-order）與 Phase 3（orchestrator-scope-guard.sh）
|
||||
# 的產物**尚未開工**，總管指定 Phase 1 做完先停下驗 Gherkin。屆時往這張表加行即可，
|
||||
# 不必再改 install.sh／update.sh —— 這正是 manifest 的用意（加產物＝加一行資料）。
|
||||
# ⚠️ 四份 JDD 文件的 class 是 add-if-missing，這是刻意的：
|
||||
# 給你一份可以直接動手填的骨架，但**一旦你填了內容，update 永遠不會覆蓋**。
|
||||
# 理由：這幾份是**實例資料**不是框架邏輯——裡面寫的是你的需求、你的旅程、你的站。
|
||||
# 來源檔名帶 .template 後綴、落地時去掉：來源是範本，落地就是你的文件了。
|
||||
#
|
||||
# 欄位定義見 common.tsv。
|
||||
#
|
||||
#src dest class module profile
|
||||
|
||||
T:profiles/orchestrator/CLAUDE.md CLAUDE.md claude-md core orchestrator
|
||||
T:profiles/orchestrator/docs/root.md.template system-dev/docs/root.md add-if-missing core orchestrator
|
||||
T:profiles/orchestrator/docs/journeys.md.template system-dev/docs/journeys.md add-if-missing core orchestrator
|
||||
T:profiles/orchestrator/docs/sprint.md.template system-dev/docs/sprint.md add-if-missing core orchestrator
|
||||
T:profiles/orchestrator/docs/triage-map.md.template system-dev/docs/triage-map.md add-if-missing core orchestrator
|
||||
T:profiles/orchestrator/docs/plugin-load-order.md system-dev/docs/plugin-load-order.md overwrite core orchestrator
|
||||
T:profiles/orchestrator/hooks/orchestrator-scope-guard.sh .claude/hooks/orchestrator-scope-guard.sh overwrite core orchestrator
|
||||
|
||||
|
@@ -0,0 +1,128 @@
|
||||
# journeys.md — PM 軌驗收（[專案／組織名]）
|
||||
|
||||
> **根**：[root.md](root.md)（J-1 對應根卡 **P?**）。本文件**只從人的角度寫**，禁止出現系統／模組名詞。
|
||||
> **誰能寫**：只有總管（orchestrator）。engineer／subagent **禁改本檔與任何考題**——考生不能改考卷。
|
||||
> **標記**：🟢 考過即關 ／ 🔴 考過轉「對帳中」（站上附真實世界判準與對帳日）
|
||||
> **站全域編號**，跨 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。engineer／subagent 寫這個檔會被 hook 擋下——考生不能改考卷。
|
||||
考題不過就去把東西做對，不是去改考題。
|
||||
════════════════════════════════════════════════════════ -->
|
||||
@@ -0,0 +1,58 @@
|
||||
# 政策包（policy pack）＝ 官方 plugin，以及它什麼時候被載入
|
||||
|
||||
> 這份是**約定**，不是實作。它回答一件事：機制是怎麼在 agent 醒來之前就已經在場的。
|
||||
|
||||
---
|
||||
|
||||
## 鐵律：政策包一律做成 Claude Code 官方 plugin
|
||||
|
||||
- 框架**不發明平行的外掛格式**。官方 plugin 已經涵蓋 hooks／skills／agents／commands／
|
||||
MCP server 的打包、安裝與版本分發——自造一套等於重寫一個市場上活得好好的輪子。
|
||||
- 要寫政策包的人，**動手前先讀官方文件**，照現行 schema 實作，
|
||||
不要憑記憶寫設定檔格式。官方會改，記憶不會跟著改。
|
||||
|
||||
---
|
||||
|
||||
## 三層是什麼（別把層搞混，混了就回不去）
|
||||
|
||||
- **框架（L1）**：方法論——雙軌、wiki、封路、階梯、儀表
|
||||
- 判準：**換一家公司照樣成立**
|
||||
- 住這裡：本 template
|
||||
- **政策包（L2）**：一家之言的技術棧政策
|
||||
- 判準：**換一家公司就不成立**
|
||||
- 住這裡：獨立的 plugin repo
|
||||
- **實例（L3）**：資料——卡片內容、wiki、sprint、指標
|
||||
- 判準：**換一個 repo 就不成立**
|
||||
- 住這裡：各實例自己
|
||||
|
||||
> 框架範本裡出現具體專案名 ＝ 格式錯誤（有 CI 擋）。政策包不受此限——專名是它的內容。
|
||||
|
||||
---
|
||||
|
||||
## 載入順序（agent 醒來時世界已就位）
|
||||
|
||||
1. **profile 憲法**（scope 軸：這個資料夾的 CLAUDE.md——總管版或成員版）
|
||||
2. **框架 hooks 上鏈**（common ＋ profile）
|
||||
3. **已安裝的政策包注入**——必讀推到眼前、白名單 hook 排入鏈尾、skill 就緒
|
||||
4. **接關**（wiki 快照）
|
||||
|
||||
- 執行期的總管／engineer **不需要知道** plugin 是官方機制還是框架機制——
|
||||
hooks 在鏈上就會攔、skill 在庫裡就會觸發。
|
||||
- **機制不靠認知，靠結構在場。** 唯一需要懂 plugin 規格的角色，是「改框架／寫政策包的人」。
|
||||
|
||||
---
|
||||
|
||||
## 框架這一側只做兩件事
|
||||
|
||||
1. 文件化上面這個約定與順序（就是這份檔）
|
||||
2. 在兩部憲法裡留 **must-read 注入點**——政策包的 SessionStart hook 有地方把必讀推進來
|
||||
|
||||
注入點長這樣（兩部憲法末尾都有）：
|
||||
|
||||
```markdown
|
||||
## 政策包必讀（policy pack must-read）
|
||||
<!-- policy-pack:must-read -->
|
||||
```
|
||||
|
||||
- 沒裝政策包時它是空的，不影響任何事。
|
||||
- 框架**不需要為此新造機制**——官方 hook 就做得到。
|
||||
@@ -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。engineer／subagent 寫這個檔會被 hook 擋下——考生不能改考卷。
|
||||
════════════════════════════════════════════════════════ -->
|
||||
@@ -0,0 +1,61 @@
|
||||
# sprint.md — 本期要點亮哪幾站
|
||||
|
||||
> **單位是站號，不是一批任務。** 這份檔的存在理由：讓自動起牀的排程／新開的 session
|
||||
> 一睜眼就有明確的「離通關還缺什麼」，而不是讀到一堆過期任務只能空轉收工。
|
||||
> **誰能寫**：只有總管（orchestrator）。
|
||||
|
||||
---
|
||||
|
||||
## 本期
|
||||
|
||||
- **期間**：[YYYY-MM-DD] → [YYYY-MM-DD]
|
||||
- **交付**：[J-x] 的 **[S-a]、[S-b]**
|
||||
- **考題**：G-a.1、G-a.2、G-b.1
|
||||
- **這期不做**：[明寫哪些站這期不碰。沒寫，別人就會自己加戲。]
|
||||
|
||||
### 現在幾站亮了
|
||||
|
||||
- [J-x] 已點亮 **n/m** 站
|
||||
- ✅ 已亮：[S-?]（[實測證據在哪]）
|
||||
- ◐ 半通：[S-?]（[缺什麼]）
|
||||
- ❌ 未亮：[S-?]、[S-?]
|
||||
|
||||
---
|
||||
|
||||
## 認領流程（順序鐵律，不准跳）
|
||||
|
||||
> **先認領 → 認領不足才新增 → 新增必掛站。** 這個順序是為了防止重造一份任務清單。
|
||||
|
||||
1. **先認領**：對現有任務池**逐項**問——
|
||||
「這個任務不做，[S-a]／[S-b] 的考題會掛嗎？」
|
||||
- 會掛 → 認領進本期
|
||||
- 不會 → **留在池子裡，這期不准碰**
|
||||
2. **認領完考題還是過不了** → 池子真的缺東西 → **此時才准新增任務**
|
||||
- 新任務**必須標注它服務哪一站**（無站號＝格式錯誤，hook 會擋）
|
||||
3. **收尾判準**＝指定站的考題**全綠**，不是任務全關
|
||||
- 🟢 站 → 點亮、關閉
|
||||
- 🔴 站 → 點亮 ＋ 轉「對帳中」，等 root.md 上的對帳日
|
||||
|
||||
---
|
||||
|
||||
## 認領清單
|
||||
|
||||
- [S-a] [站名]
|
||||
- 認領：[任務編號／描述]（在哪個 repo）
|
||||
- 認領：[...]
|
||||
- 新增：[...] ← 標明是新增的，以及為什麼池子裡沒有
|
||||
- [S-b] [站名]
|
||||
- 認領：[...]
|
||||
|
||||
---
|
||||
|
||||
## 到期結算（換檔機制）
|
||||
|
||||
> 期間一到就**強制結算**，不准無聲延期——過期的 sprint 檔正是「起牀讀到殘骸」的來源。
|
||||
|
||||
- 到期日 [YYYY-MM-DD] 當天做三件事：
|
||||
- 亮了的站 → 在 journeys.md 標記，附**實測證據**
|
||||
- 沒亮的站 → **搬移**到下一期，並寫一行「為什麼沒亮」
|
||||
- 沒人認領也沒亮的任務 → **作廢或退回池子**，不准留在這裡假裝還活著
|
||||
- 狀態只有三種：**✅ 通（附實測證據）／◐ 半通（標明缺什麼）／❌ 斷**
|
||||
- 「程式碼寫完了」不是狀態
|
||||
@@ -0,0 +1,34 @@
|
||||
# triage-map.md — 能力域 → 誰做
|
||||
|
||||
> 新需求進來時查這張表：這件事該落在哪個成員 repo。
|
||||
> **表上沒有 ⇒ 不准自己開新 repo**，走人閘提案。
|
||||
> **誰能寫**：只有總管（orchestrator）。
|
||||
|
||||
---
|
||||
|
||||
## 對照
|
||||
|
||||
- **[能力域名稱]**
|
||||
- 落在：`[成員 repo 路徑]`
|
||||
- 邊界：[什麼算它的、什麼不算——寫清楚才不會兩個 repo 搶同一件事或互推]
|
||||
- **[能力域名稱]**
|
||||
- 落在：`[成員 repo 路徑]`
|
||||
- 邊界：[...]
|
||||
|
||||
---
|
||||
|
||||
## 分診的第二問（別漏）
|
||||
|
||||
查完「誰做」，還要問**這個需求動到哪條旅程的哪些站**：
|
||||
|
||||
- 動到既有的站 → 查 journeys.md 的**站點索引**，決定重考範圍
|
||||
- 需要新的站 → 走 journeys.md 提案（只有總管能寫）
|
||||
- 連角色都是新的 → **先寫一篇敘事故事**給人驗完整性，再立新旅程
|
||||
|
||||
---
|
||||
|
||||
## 表上沒有的怎麼辦
|
||||
|
||||
- 先確認真的沒有——多數「新能力」其實是既有能力域的延伸，硬開新 repo 只是把邊界問題往後推。
|
||||
- 真的沒有 → 提案開新 repo，**這是人閘**（動到大家共用的結構）。
|
||||
- 提案要寫：這個能力域的邊界在哪、為什麼塞不進既有任何一個、誰維護。
|
||||
@@ -0,0 +1,97 @@
|
||||
#!/bin/bash
|
||||
# orchestrator-scope-guard.sh — 總管不進成員 repo 動實作（分離規格 防糾纏閘 S4）
|
||||
#
|
||||
# 只裝在 orchestrator profile。掛 PreToolUse（Write|Edit|MultiEdit）。
|
||||
#
|
||||
# ── 與 role-guard 的分工（刻意分兩支，不重疊）────────────
|
||||
# role-guard 管「這個**角色**能寫什麼**類型**的檔」（code？考卷？任務池？）
|
||||
# orchestrator-scope-guard 管「總管能不能進這個**位置**」（成員 repo 的地盤）
|
||||
# 兩件事正交：總管在自己家寫 md 沒問題，進成員 repo 寫 md 也沒問題（那是交辦），
|
||||
# 但進成員 repo 寫實作檔就是越界——那是該 repo 的 engineer 的事。
|
||||
#
|
||||
# ── 為什麼「只擋非 .md」──────────────────────────
|
||||
# .md 放行是刻意的：總管要能在成員 repo 裡留交辦文件、筆記、規格討論。
|
||||
# 擋的是「總管自己下去改人家的實作」——那會讓該 repo 的 CC 完全不知道發生什麼事，
|
||||
# 而且繞過了該 repo 自己的規格與 wiki 紀律。
|
||||
#
|
||||
# ── 自動派工放行 ────────────────────────────────
|
||||
# 當「總管派出去的 subagent 已經戴著該 repo 的人格」時，它寫該 repo 的 code 是合理的
|
||||
# （心智已經在那個 repo 裡，context 是隔離的）。雙重夾：
|
||||
# ① 環境變數 CLAUDE_CODE_CHILD_SESSION=1（subagent 標籤；總管主 session 沒有）
|
||||
# ② 路徑在下方白名單內
|
||||
# ⚠️ 隔離保證是 prompt reset（軟的，靠監測），不是結構級。要絕對純淨走獨立 session。
|
||||
#
|
||||
# 誠實限制：擋的是路徑語法層。「把實作偽裝成 .md」或「該交辦卻判斷成可直改」
|
||||
# 這種語意層越界擋不到。它是底線，不是萬能。
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
. "$HOOK_DIR/lib/role-lib.sh" 2>/dev/null || exit 0
|
||||
|
||||
# 只在總管實例生效（裝錯地方就安靜退出）
|
||||
[ "$(sdt_scope)" = "orchestrator" ] || exit 0
|
||||
|
||||
INPUT="$(cat)"
|
||||
FILE_PATH="$(sdt_file_path "$INPUT")"
|
||||
[ -z "$FILE_PATH" ] && exit 0
|
||||
|
||||
ROOT="$(sdt_repo_root)"
|
||||
REL="$(sdt_rel_path "$FILE_PATH")"
|
||||
|
||||
# ── 成員 repo 目錄怎麼認 ─────────────────────────
|
||||
# 不寫死任何專案名（框架不含實例資料）。兩種來源：
|
||||
# ① 實例自填的清單：system-dev/.member-dirs（一行一個目錄前綴）
|
||||
# ② 沒有該檔 → 動態偵測：頂層下「自己帶 .git 的子目錄」就是成員 repo
|
||||
MEMBER_DIRS_FILE="$ROOT/system-dev/.member-dirs"
|
||||
top="${REL%%/*}"
|
||||
[ "$top" = "$REL" ] && exit 0 # 不在任何子目錄裡＝總管自己的檔，放行
|
||||
|
||||
in_member_repo=1
|
||||
if [ -f "$MEMBER_DIRS_FILE" ]; then
|
||||
while IFS= read -r d; do
|
||||
case "$d" in ''|'#'*) continue ;; esac
|
||||
d="${d%/}"
|
||||
case "$REL" in "$d"/*) in_member_repo=0; break ;; esac
|
||||
done < "$MEMBER_DIRS_FILE"
|
||||
else
|
||||
[ -d "$ROOT/$top/.git" ] && in_member_repo=0
|
||||
fi
|
||||
[ "$in_member_repo" -eq 0 ] || exit 0
|
||||
|
||||
# ── 自動派工白名單（實例自填，框架不預設任何路徑）────
|
||||
ALLOW_FILE="$ROOT/system-dev/.autodispatch-allow"
|
||||
if [ "${CLAUDE_CODE_CHILD_SESSION:-}" = "1" ] && [ -f "$ALLOW_FILE" ]; then
|
||||
while IFS= read -r a; do
|
||||
case "$a" in ''|'#'*) continue ;; esac
|
||||
a="${a%/}"
|
||||
case "$REL" in
|
||||
"$a"/*) echo "🤝 [orchestrator-scope-guard] subagent 放行：$a（自動派工）" >&2; exit 0 ;;
|
||||
esac
|
||||
done < "$ALLOW_FILE"
|
||||
fi
|
||||
|
||||
# ── 成員 repo 內：.md 放行（交辦／文件），其餘擋 ────
|
||||
case "$REL" in
|
||||
*.md|*.MD|*.markdown) exit 0 ;;
|
||||
esac
|
||||
|
||||
cat >&2 <<EOF
|
||||
❌ BLOCKED by orchestrator-scope-guard（防糾纏閘 S4）
|
||||
|
||||
總管不進成員 repo 動實作。
|
||||
|
||||
成員 repo：$top
|
||||
路徑：$REL
|
||||
|
||||
正確做法：
|
||||
· 要那個 repo 改什麼 → 在**那個 repo** 開一張交辦（.md 放行），
|
||||
給判準與考題，成品由該 repo 的 CC 按它自己的規格產出
|
||||
· 你能派 subagent 去做 → 那才是正解，不是自己下去改，也不是叫人去開另一個 session
|
||||
· 真要放行 subagent 自動寫某個 repo → 把路徑加進 system-dev/.autodispatch-allow
|
||||
（⚠️ 加＝放權，想清楚它影響誰）
|
||||
|
||||
為什麼擋：你直接改人家的實作，該 repo 的 CC 完全不知道發生過什麼事——
|
||||
它的規格、wiki、驗收全部被繞過，下次它照自己的紀律工作時就會把你的改動蓋掉。
|
||||
EOF
|
||||
exit 2
|
||||
Reference in New Issue
Block a user