feat(W2 Phase 0-1): 雙 profile 地基＋JDD 兩軸身分＋兩支防炸閘
SDD: docs/3-specs/jdd-dual-profile（draft → active，leo 2026-08-05 回「開工」）
範圍：總管指定的「防炸兩件 → Phase 0 → Phase 1」，Phase 2 以後未開工。
■ 防炸（排在所有 task 之前，因為它們炸的是既有的東西）
- check-no-instance-names.sh ＋ instance-names.txt：框架範本不得混入實例專名
基線實測 22 行命中（非先前誤報的 20）→ 9 行無損泛化改寫、13 行檔級豁免記帳待 W3 搬走
拒絕假性清理（把專名換成模糊詞＝資訊消失、分層問題還在）
- check-legacy-paths.sh：已發佈腳本引用的 35 條遠端路徑只增不移
舊實例跑的是舊腳本、路徑寫死；搬檔＝整排 404 且不會有下一次更新來修它（1.16.0 前科）
■ Phase 0 地基
- template/manifest/{common,repo,orchestrator}.tsv：安裝清單單一真相源
修好 install/update 兩份硬編清單的既有漂移——install 從不裝 wiki-first-search /
subagent-wiki-guard / publish-lag-check / decisions-summary，但 update 會
⇒ 乾淨安裝反而拿不到 1.16/1.17/1.18 的招牌功能
- .claude/hooks/lib/role-lib.sh：scope×role 兩軸機械判定，零自陳
身分矩陣六組實測全通過，含「成員 repo × orchestrator」不存在的格子擋下
- .sdt-framework-dev：框架開發標記（官方沒有 --framework-dev 這個參數，實查非記憶）
■ Phase 1 雙 profile
- profiles/{repo,orchestrator}/CLAUDE.md 兩部憲法
- install.sh：--profile ＋ 自動偵測＋寫檔前確認、manifest 驅動、
CLAUDE.md 三段組裝（框架區/本地補充區界標＋sha256）、.profile、.template-manifest、
settings.json 寫入 env.AGENT_ROLE 預設
- update.sh：漂移偵測（不覆蓋手改檔、另存 .new、白話清單）＋ 基準快照隨更新前進
- template/CLAUDE.md 原路徑凍結留底（相容）
■ 順手修掉兩個舊 bug（都在本次要動的函式裡）
- add_if_missing 少了 mkdir -p ⇒ 新目錄的檔 curl 失敗但 VERSION 照升（2026-07 記「待回報」至今未修）
- 下載健全性只用 [ -s ]＝非空即接受 ⇒ 404 頁面會無聲覆寫好檔
（SKILL.md 260→1 行的機制；同一支腳本的版本號那條路早就防了，檔案這條沒防）
■ 實測（非推論）
- G4 憲法分流：兩個乾淨環境各裝一次，orchestrator 版含 SDD 三件式關鍵字 0 次、
repo 版含上游指針 8 次；界標 4/4；sha 宣告與實算相符
- G7 CI 擋實例名：注入違規行 → fail 並指出 sdd-check.md:77，exit 1；還原後 exit 0
- 漂移偵測：手改兩支 hook → 正確報 2 支、手改內容保住、產 .new；
解掉後歸零；連跑三輪冪等
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,18 @@
|
||||
# .sdt-framework-dev — 這裡是「框架 repo 本身」的標記
|
||||
#
|
||||
# 存在即生效，內容不重要（這些字只是給人看的）。
|
||||
#
|
||||
# 它解除的是什麼：
|
||||
# 實例側有一條封路——「不准改安裝產物區（.claude/hooks/、system-dev/ 範本區、
|
||||
# plugin 安裝目錄）」，因為機制變更必須回框架提案，而不是各實例自己手改
|
||||
# （手改的下場：4 支 hook 已經漂移，而且沒有任何人知道）。
|
||||
# 但在**框架 repo 自己**開發時，改那些檔正是本職工作 ⇒ 這個標記讓 guard 放行。
|
||||
#
|
||||
# 為什麼是檔案而不是 CLI 參數：
|
||||
# 《分離導入規格》§6.1 寫的是「`--framework-dev` 標記的 session」，
|
||||
# 但 Claude Code **沒有這個官方參數**（實查，非記憶）。
|
||||
# 改用檔案的好處：框架 repo 天生就帶著它、隨 clone 就在、零記憶負擔，
|
||||
# 不必每次開 session 記得加旗標。
|
||||
# （臨時情境仍可用環境變數 SDT_FRAMEWORK_DEV=1 達到同樣效果。）
|
||||
#
|
||||
# ⚠️ 實例不該有這個檔。實例裡出現它 ＝ 有人在關掉自己的封路，git 上看得見。
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
status: draft # active | draft | paused | closed（生命週期鐵律見 ../SDD-LIFECYCLE.md）
|
||||
status: active # active | draft | paused | closed（生命週期鐵律見 ../SDD-LIFECYCLE.md）
|
||||
superseded_by: "" # closed 且被取代時填接替的 SDD 資料夾名
|
||||
---
|
||||
|
||||
@@ -8,11 +8,13 @@ superseded_by: "" # closed 且被取代時填接替的 SDD 資料夾名
|
||||
> 建立：2026-08-05 | 最後更新：2026-08-05
|
||||
> 負責人：system-dev-template CC
|
||||
> 來源：InkStoneCo 總管交辦 **W2**
|
||||
> **狀態：draft — 等 leo confirm 才升 active，未實作任何 code**
|
||||
> **狀態：active（2026-08-05 leo 回「開工」升活性）**
|
||||
>
|
||||
> 為什麼是 `draft` 而非 `active`：D35 ②③ 規定 CC 不得自行讓 SDD 生效；
|
||||
> 本 repo 目前 **0 份 active**（見「現況實查」§0.1），本案 confirm 後直接升 active，
|
||||
> 不需搬移任何未完成任務（無現任 active 可搬）。
|
||||
> 升活性前實查：全 repo 帶 frontmatter 的只有 `TEMPLATE-sdd`（draft，範本不算數）
|
||||
> ⇒ active 數 = 0，**無衝突、無未完成任務需搬移**（D35 ④ a 步驟空集合）。
|
||||
>
|
||||
> 施工順序由總管指定：**發現①、發現⑦ 的防炸工程 → Phase 0 → Phase 1 → 停下驗 Gherkin**。
|
||||
> Phase 2 以後未經確認不得開工。
|
||||
|
||||
---
|
||||
|
||||
@@ -407,6 +409,33 @@ SessionStart
|
||||
|
||||
---
|
||||
|
||||
## 附錄 A：三個 marker 檔的格式規格（task 0.3）
|
||||
|
||||
| 檔 | 位置 | 內容 | 誰寫 | 誰讀 |
|
||||
|---|---|---|---|---|
|
||||
| `.profile` | 實例 `system-dev/.profile` | 單行：`repo` 或 `orchestrator`（前後空白會被 trim） | `install.sh --profile` | `role-lib.sh` 的 `sdt_scope()`、`update.sh`、CI |
|
||||
| `.template-manifest` | 實例 `system-dev/.template-manifest` | TSV：`dest class version sha256`（安裝當下的雜湊） | install／update | `update.sh` 的三態判定 |
|
||||
| `.sdt-framework-dev` | **框架 repo 根**（實例不該有） | 任意文字，存在即生效 | 框架 repo 自帶並 commit | `install-artifact-guard.sh` |
|
||||
|
||||
- 三者都是「機器可讀的事實」，不是設定選項——agent 不得靠它們表達意圖，只能讀。
|
||||
- `.profile` 讀不到 → 視為 `repo`（代價寫在 `role-lib.sh` 註解裡，不假裝沒有）。
|
||||
- `.sdt-framework-dev` 出現在實例裡 ＝ 有人在關掉自己的封路，**git diff 看得見**。
|
||||
|
||||
---
|
||||
|
||||
## 附錄 B：本波實作的兩支機械閘（先於一切 task，防炸用）
|
||||
|
||||
| 閘 | 檔 | 擋什麼 | 實測 |
|
||||
|---|---|---|---|
|
||||
| 實例專名 | `scripts/check-no-instance-names.sh` ＋ `scripts/instance-names.txt` | 框架範本混入實例專名 | 基線 22 行 → 處置後 0 違規／13 行檔級豁免；注入違規行可 fail 並指出檔案:行號 |
|
||||
| 相容路徑 | `scripts/check-legacy-paths.sh` | 搬檔／改名導致舊實例 update 整排 404 | 追蹤 35 條已發佈路徑；移走 `template/CLAUDE.md` 可正確 fail |
|
||||
|
||||
> 為什麼這兩支要排在所有 task 之前（總管裁定）：它們**炸的是既有的東西**，不是新功能沒做好。
|
||||
> 專名閘晚做 → 之後每加一個範本檔都可能再混進實例名，債只會更大；
|
||||
> 相容閘晚做 → Phase 1 一搬 `CLAUDE.md` 就把所有舊實例的自動更新弄死，而且**沒有下一次更新能修它**。
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- `requirements.md`（本卷）／`tasks.md`（本卷）
|
||||
|
||||
@@ -3,7 +3,9 @@
|
||||
> 權威來源：此檔案是進度真相，不是 CLAUDE.md 或對話。
|
||||
> 規則：動手前標 [🔄]，完成立刻標 [x]，不批次更新。
|
||||
> **每一項都標「服務哪條 Gherkin」**（G1–G7 定義見 `requirements.md` §四）。
|
||||
> 🔴 **本卷 status: draft — 等 leo confirm 才准動工。以下一項都還沒開始。**
|
||||
> 🟢 **status: active（2026-08-05 leo 回「開工」）**。
|
||||
> 進度：**防炸兩閘 ＋ Phase 0 ＋ Phase 1 已完成**（Phase 1 有兩項 ◐，見下）。
|
||||
> **Phase 2 以後未經確認不得開工**（總管指定：先停下驗 Gherkin）。
|
||||
|
||||
---
|
||||
|
||||
@@ -28,14 +30,14 @@
|
||||
|
||||
### Tasks
|
||||
|
||||
- [ ] 0.1 定義 manifest 格式並產出三份 `template/manifest/{common,repo,orchestrator}.tsv`
|
||||
- [x] 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`（兩軸判定函式庫）
|
||||
- [x] 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）
|
||||
@@ -43,7 +45,7 @@
|
||||
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`
|
||||
- [x] 0.3 立 marker 檔約定：`system-dev/.profile`、`system-dev/.template-manifest`、`.sdt-framework-dev`
|
||||
- 服務：**G4**、**G6**
|
||||
- 驗收：三個檔的格式各寫一段規格進 design 的附錄，並在框架 repo 自己放一份
|
||||
`.sdt-framework-dev`（commit）
|
||||
@@ -55,54 +57,56 @@
|
||||
|
||||
> 前置條件：Phase 0 全部完成
|
||||
|
||||
- [ ] 1.1 建 `template/profiles/repo/CLAUDE.md`（repo 憲法範本）
|
||||
- [x] 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`（總管憲法範本）
|
||||
- [x] 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` ＋ 自動偵測 ＋ 一次性人確認
|
||||
- [x] 1.3 `install.sh` 加 `--profile=repo|orchestrator` ＋ 自動偵測 ＋ 一次性人確認
|
||||
- 服務：**G4**
|
||||
- 偵測規則：目前目錄下存在多個各自帶 `.git` 的子目錄 → 建議 orchestrator
|
||||
- 驗收：三種呼叫（明示 repo／明示 orchestrator／不指定走偵測）各跑一次乾淨環境，
|
||||
貼出各自產生的 `system-dev/.profile` 內容
|
||||
- 注意：**確認在寫入任何檔案之前**問，別裝了一半才問
|
||||
|
||||
- [ ] 1.4 `install.sh` 改讀 manifest 鋪設產物 ＋ 產 `.template-manifest`
|
||||
- [x] 1.4 `install.sh` 改讀 manifest 鋪設產物 ＋ 產 `.template-manifest`
|
||||
- 服務：**G4**、G6
|
||||
- 驗收：repo profile 裝出的檔案集合 = `common.tsv ∪ repo.tsv`，
|
||||
且**不含** orchestrator 專屬檔（`ls` 對照貼出）
|
||||
|
||||
- [ ] 1.5 CLAUDE.md 三段組裝（框架區界標 ＋ 本地補充區界標 ＋ sha256）
|
||||
- [x] 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` 預設
|
||||
- [x] 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 ＋ 三態判定 ＋ 漂移清單輸出
|
||||
- [~] 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 清單漂移的根因只修了一半
|
||||
|
||||
- [ ] 1.8 `update.sh` 舊實例遷移：無 manifest → 一次性補植 ＋ CLAUDE.md 界標補植
|
||||
- [~] 1.8 `update.sh` 舊實例遷移：無 manifest → 一次性補植 ＋ CLAUDE.md 界標補植
|
||||
- 服務：**G4**、G6
|
||||
- 驗收：拿一份 1.18.0 的實例副本跑兩次 update，第二次為 no-op（冪等，貼兩次輸出對照）
|
||||
- 注意：舊 CLAUDE.md 整份包進 `sdt:local` 區，一個字都不能掉
|
||||
- 現況：◐ 舊實例無 manifest → 首輪自動建基準（已實測）；**CLAUDE.md 界標補植未做**
|
||||
|
||||
- [ ] 1.9 `template/CLAUDE.md` 原路徑保留轉址說明（向下相容）
|
||||
- [x] 1.9 `template/CLAUDE.md` 原路徑保留轉址說明（向下相容）
|
||||
- 服務：**G4**
|
||||
- 驗收：舊版 update.sh 對該路徑的 curl 仍回 200（決策 D3）
|
||||
|
||||
|
||||
Executable
+95
@@ -0,0 +1,95 @@
|
||||
#!/bin/bash
|
||||
# check-legacy-paths.sh — 相容閘：已發佈的安裝/更新腳本會抓的每個遠端路徑，都必須還在
|
||||
#
|
||||
# 這支存在的理由（SDD jdd-dual-profile 發現⑦ ＋ 決策 D3）：
|
||||
# install.sh / update.sh 是**逐檔 curl**：檔案清單與遠端路徑**寫死在腳本裡**。
|
||||
# 而 update.sh 的「自我更新」在腳本**尾端**——舊實例這一輪跑的是**舊腳本**。
|
||||
# ⇒ 只要框架把某個既有檔搬走／改名，舊實例的那一輪就是**整排 404**，
|
||||
# 而且它們不會自動好：更新機制本身壞了，就沒有下一次更新來修它。
|
||||
#
|
||||
# 前科：1.16.0「update/install 來源改指 Gitea」——來源一改，
|
||||
# 舊實例的自動更新當場死掉（CHANGELOG 1.16.0 有記）。同一種病。
|
||||
#
|
||||
# 所以鐵律是：**遠端路徑對既有實例是契約，只增不移。**
|
||||
# 要搬版面 → 先在原路徑留相容檔（轉址說明／原內容），確認本閘綠了才准動。
|
||||
#
|
||||
# 作法：
|
||||
# 從「已發佈版本」的 install.sh / update.sh 裡抽出所有 $REPO_URL/... $TEMPLATE_URL/...
|
||||
# $SCRIPTS_URL/... 引用，映射回本 repo 的實體路徑，逐一確認檔案存在。
|
||||
#
|
||||
# 誠實限制：
|
||||
# · 只驗「路徑還在不在」，不驗內容還對不對（舊腳本抓到新內容仍可能語意不相容）。
|
||||
# · 基準是 git 裡的已發佈版本（預設 HEAD）；再更老的版本若引用過更多路徑，
|
||||
# 本閘看不到——要驗更早的版本，用 BASE=<commit> 指定。
|
||||
#
|
||||
# 用法：
|
||||
# bash scripts/check-legacy-paths.sh # 以 HEAD 為已發佈基準
|
||||
# BASE=dc4fe67 bash scripts/check-legacy-paths.sh
|
||||
set -euo pipefail
|
||||
|
||||
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
cd "$REPO_ROOT"
|
||||
|
||||
BASE="${BASE:-HEAD}"
|
||||
|
||||
# ── 取出基準版本的兩支腳本 ────────────────────────────
|
||||
TMP="$(mktemp -d)"
|
||||
trap 'rm -rf "$TMP"' EXIT
|
||||
|
||||
for s in install.sh update.sh; do
|
||||
if ! git show "$BASE:scripts/$s" > "$TMP/$s" 2>/dev/null; then
|
||||
echo "⚠️ 基準 $BASE 沒有 scripts/$s，略過" >&2
|
||||
: > "$TMP/$s"
|
||||
fi
|
||||
done
|
||||
|
||||
# ── 抽出遠端引用 → 映射成本地實體路徑 ──────────────────
|
||||
# $REPO_URL/x → template/x
|
||||
# $TEMPLATE_URL/x → template/x
|
||||
# $SCRIPTS_URL/x → scripts/x
|
||||
extract_paths() {
|
||||
grep -oE '\$\{?(REPO_URL|TEMPLATE_URL|SCRIPTS_URL)\}?/[A-Za-z0-9._/-]+' "$1" 2>/dev/null \
|
||||
| sed -e 's|\${*REPO_URL}*/|template/|' \
|
||||
-e 's|\${*TEMPLATE_URL}*/|template/|' \
|
||||
-e 's|\${*SCRIPTS_URL}*/|scripts/|' \
|
||||
|| true
|
||||
}
|
||||
|
||||
ALL="$( { extract_paths "$TMP/install.sh"; extract_paths "$TMP/update.sh"; } | sort -u )"
|
||||
|
||||
if [ -z "$ALL" ]; then
|
||||
echo "⚠️ 在 $BASE 的腳本裡找不到任何遠端引用——抽取規則可能過時，本閘等同關閉" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
TOTAL=0
|
||||
MISSING=0
|
||||
MISSING_LIST=""
|
||||
|
||||
while IFS= read -r p; do
|
||||
[ -z "$p" ] && continue
|
||||
TOTAL=$((TOTAL + 1))
|
||||
if [ ! -e "$p" ]; then
|
||||
MISSING=$((MISSING + 1))
|
||||
MISSING_LIST="${MISSING_LIST} ✗ ${p}"$'\n'
|
||||
fi
|
||||
done <<< "$ALL"
|
||||
|
||||
if [ "$MISSING" -gt 0 ]; then
|
||||
cat >&2 <<EOF
|
||||
════════════════════════════════════════════════
|
||||
❌ 相容閘：已發佈腳本會抓的路徑不見了（$MISSING / $TOTAL）
|
||||
════════════════════════════════════════════════
|
||||
$MISSING_LIST
|
||||
後果（不是理論，是 1.16.0 真的發生過）：
|
||||
舊實例跑 update 時對上面每個路徑 curl 404 → 更新失敗 →
|
||||
**更新機制本身壞掉，之後也不會有下一次更新來修它**。
|
||||
|
||||
正解：搬版面時在原路徑留相容檔（轉址說明或原內容），
|
||||
本閘綠了才准繼續。遠端路徑是契約，只增不移。
|
||||
EOF
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ 相容閘：已發佈腳本（基準 $BASE）引用的 $TOTAL 個路徑全部還在"
|
||||
exit 0
|
||||
Executable
+136
@@ -0,0 +1,136 @@
|
||||
#!/bin/bash
|
||||
# check-no-instance-names.sh — 機械閘 #2：框架範本不得混入實例專名
|
||||
#
|
||||
# 出處：《分離導入規格》第六節第 2 條、第七節第四題 Gherkin。
|
||||
# Scenario: 框架混入實例名被 CI 擋
|
||||
# Given 範本檔新增一行含 "arcrun"
|
||||
# When CI 執行
|
||||
# Then 檢查 fail 並指出檔案與行號
|
||||
#
|
||||
# 為什麼需要它（不是潔癖，是分層會自己塌）：
|
||||
# L1 框架的判準是「換一家公司照樣成立」。一旦範本裡寫著某個實例的專案名，
|
||||
# 下一個裝這套 template 的人就會讀到一段對他不成立的規則——而他無從分辨
|
||||
# 「這條是普世方法論」還是「這是別人家的家規」。分層一旦糊掉就回不去了。
|
||||
#
|
||||
# ── 豁免機制（為什麼要有）─────────────────────────────
|
||||
# 本閘上線時，範本區已經有 22 行命中（8 個檔）。若不給豁免就硬上線，唯一的
|
||||
# 通關方式會是「把 arcrun 改寫成『某工作流引擎』」——**資訊消失了，問題還在**
|
||||
# （假性清理）。所以：真正該搬走的東西標豁免、記在帳上，隨 policy pack 一起搬；
|
||||
# 純粹是註解舉例的，當場改寫成通用敘述。
|
||||
# 豁免有兩級：
|
||||
# · 行級 `sdt-instance-name-ok` → 該行豁免。用在「檔案本身是框架的，只有這行欠著」。
|
||||
# · 檔級 `sdt-instance-name-ok-file` → 整檔豁免（寫在檔首 30 行內，需附理由）。
|
||||
# 用在「整支本來就是 L2 政策包產物、只是還沒搬走」——逐行標 13 次是雜訊不是紀律。
|
||||
#
|
||||
# 誠實限制：這支只認「字面出現」。它擋不了「把實例假設寫成通用語氣」
|
||||
# （例如寫「你的工作流引擎會在遠端執行」其實只有某一家成立）。
|
||||
# 它是底線不是萬能——真正的分層判斷仍要人／CC 動腦。
|
||||
#
|
||||
# 用法：
|
||||
# bash scripts/check-no-instance-names.sh # CI 模式，有未豁免命中 → exit 1
|
||||
# bash scripts/check-no-instance-names.sh --baseline # 只列清單（含已豁免），永遠 exit 0
|
||||
#
|
||||
set -euo pipefail
|
||||
|
||||
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
cd "$REPO_ROOT"
|
||||
|
||||
NAMES_FILE="scripts/instance-names.txt"
|
||||
SCAN_DIR="template"
|
||||
EXEMPT_MARK="sdt-instance-name-ok"
|
||||
EXEMPT_FILE_MARK="sdt-instance-name-ok-file"
|
||||
EXEMPT_HEAD_LINES=30 # 檔級豁免標記必須寫在檔首這麼多行內（強迫它顯眼、不許藏在檔尾）
|
||||
|
||||
MODE="ci"
|
||||
[ "${1:-}" = "--baseline" ] && MODE="baseline"
|
||||
|
||||
if [ ! -f "$NAMES_FILE" ]; then
|
||||
echo "❌ 找不到黑名單設定檔：$NAMES_FILE" >&2
|
||||
exit 1
|
||||
fi
|
||||
if [ ! -d "$SCAN_DIR" ]; then
|
||||
echo "❌ 找不到範本區：$SCAN_DIR/" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# ── 讀黑名單 → 組成 grep 的 alternation pattern ───────────────
|
||||
PATTERN=""
|
||||
while IFS= read -r line; do
|
||||
case "$line" in ''|'#'*) continue ;; esac
|
||||
term="$(printf '%s' "$line" | tr -d '[:space:]')"
|
||||
[ -z "$term" ] && continue
|
||||
if [ -z "$PATTERN" ]; then PATTERN="$term"; else PATTERN="$PATTERN|$term"; fi
|
||||
done < "$NAMES_FILE"
|
||||
|
||||
if [ -z "$PATTERN" ]; then
|
||||
echo "⚠️ 黑名單是空的，本閘等同關閉（$NAMES_FILE）"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# ── 掃描 ────────────────────────────────────────────
|
||||
# policy pack 不受此限（L2 本來就是一家之言）。目前尚無 policy pack 目錄，
|
||||
# 先把慣例路徑寫在這裡，W3 建立時自動生效。
|
||||
HITS="$(grep -rniE "$PATTERN" "$SCAN_DIR" 2>/dev/null \
|
||||
| grep -v "^$SCAN_DIR/policy-packs/" || true)"
|
||||
|
||||
VIOLATIONS=0
|
||||
EXEMPTED=0
|
||||
VIOL_LINES=""
|
||||
EXEMPT_LINES=""
|
||||
|
||||
if [ -n "$HITS" ]; then
|
||||
while IFS= read -r hit; do
|
||||
[ -z "$hit" ] && continue
|
||||
hit_file="${hit%%:*}"
|
||||
# 檔級豁免：整支本來就是 L2 產物，檔首宣告過就整檔記帳
|
||||
if [ -f "$hit_file" ] && head -n "$EXEMPT_HEAD_LINES" "$hit_file" 2>/dev/null | grep -q "$EXEMPT_FILE_MARK"; then
|
||||
EXEMPTED=$((EXEMPTED + 1))
|
||||
EXEMPT_LINES="${EXEMPT_LINES}${hit}"$'\n'
|
||||
continue
|
||||
fi
|
||||
# 行級豁免：檔案是框架的，只有這行欠著
|
||||
if printf '%s' "$hit" | grep -q "$EXEMPT_MARK"; then
|
||||
EXEMPTED=$((EXEMPTED + 1))
|
||||
EXEMPT_LINES="${EXEMPT_LINES}${hit}"$'\n'
|
||||
else
|
||||
VIOLATIONS=$((VIOLATIONS + 1))
|
||||
VIOL_LINES="${VIOL_LINES}${hit}"$'\n'
|
||||
fi
|
||||
done <<< "$HITS"
|
||||
fi
|
||||
|
||||
# ── 輸出 ────────────────────────────────────────────
|
||||
if [ "$MODE" = "baseline" ]; then
|
||||
echo "════════════════════════════════════════════════"
|
||||
echo "📊 實例專名基線報表（$SCAN_DIR/）"
|
||||
echo "════════════════════════════════════════════════"
|
||||
echo "未豁免（違規）：$VIOLATIONS 行"
|
||||
[ -n "$VIOL_LINES" ] && printf '%s' "$VIOL_LINES" | cut -c1-160 | sed 's/^/ ❌ /'
|
||||
echo "已豁免（記在帳上，待搬遷）：$EXEMPTED 行"
|
||||
[ -n "$EXEMPT_LINES" ] && printf '%s' "$EXEMPT_LINES" | cut -c1-160 | sed 's/^/ ⏳ /'
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [ "$VIOLATIONS" -gt 0 ]; then
|
||||
echo "════════════════════════════════════════════════" >&2
|
||||
echo "❌ 框架範本混入實例專名（$VIOLATIONS 行）" >&2
|
||||
echo "════════════════════════════════════════════════" >&2
|
||||
printf '%s' "$VIOL_LINES" | cut -c1-200 | sed 's/^/ /' >&2
|
||||
cat >&2 <<EOF
|
||||
|
||||
鐵律：框架不含實例資料（《分離導入規格》第一節鐵律 2）。
|
||||
L1 範本要「換一家公司照樣成立」；上面這些行只對某一家成立。
|
||||
|
||||
怎麼修（擇一，別選第四條「把詞換掉了事」）：
|
||||
1. 只是註解／舉例 → 改寫成通用敘述（例：「某個 repo」而非具體專案名）
|
||||
2. 其實是政策包的內容 → 搬進 policy pack（L2），不要留在框架
|
||||
3. 真的暫時搬不走 → 行尾加註記 $EXEMPT_MARK ＋ 一句「為什麼還不能拿掉」
|
||||
⚠️ 不准做的：把專名換成模糊詞讓檢查過關——資訊消失了，分層問題還在。
|
||||
|
||||
已豁免（不計違規）：$EXEMPTED 行
|
||||
EOF
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ 範本區無未豁免的實例專名（已豁免 $EXEMPTED 行，記在帳上待搬遷）"
|
||||
exit 0
|
||||
+231
-98
@@ -36,29 +36,49 @@ SCRIPTS_URL="$TEMPLATE_SOURCE/scripts"
|
||||
CREATED=()
|
||||
SKIPPED=()
|
||||
|
||||
# ── 解析模組參數 ──────────────────────────────────
|
||||
# ── 解析模組 / profile 參數 ────────────────────────
|
||||
# profile ＝ scope 軸（這個資料夾是「成員 repo」還是「總管」）。
|
||||
# 它決定裝哪一部憲法——agent 在哪裡醒來就只讀得到哪部，**不靠 agent 自我判斷**。
|
||||
#
|
||||
# ⚠️ 契約在檔案，不在這支腳本：真正的 scope 真相源是 `system-dev/.profile`。
|
||||
# 本腳本只是**其中一個寫入者**——「把網址丟給 AI 幫我裝」那條路（主打入口）
|
||||
# 同樣必須寫出這個檔，格式一致即可互通。腳本入口是備援與參考實作，不是唯一路徑。
|
||||
MODULE=""
|
||||
PROFILE=""
|
||||
for arg in "$@"; do
|
||||
case "$arg" in
|
||||
--wiki|--wiki-only) MODULE="wiki" ;;
|
||||
--sdd|--sdd-only) MODULE="sdd" ;;
|
||||
--all) MODULE="all" ;;
|
||||
--wiki|--wiki-only) MODULE="wiki" ;;
|
||||
--sdd|--sdd-only) MODULE="sdd" ;;
|
||||
--all) MODULE="all" ;;
|
||||
--profile=repo) PROFILE="repo" ;;
|
||||
--profile=orchestrator) PROFILE="orchestrator" ;;
|
||||
--profile=*)
|
||||
echo "❌ 不認得的 profile：${arg#--profile=}（只接受 repo / orchestrator）" >&2
|
||||
exit 1 ;;
|
||||
-h|--help)
|
||||
if [ "$IS_ZH" = "yes" ]; then
|
||||
cat <<'HELP'
|
||||
用法：install.sh [--wiki | --sdd | --all]
|
||||
用法：install.sh [--wiki | --sdd | --all] [--profile=repo|orchestrator]
|
||||
--wiki 只裝 LLM Wiki（CC 記憶系統 + 機敏防護）
|
||||
--sdd 只裝 SDD 系統（動 code 前強制要有設計文件）
|
||||
--all 兩個都裝（預設）
|
||||
無參數 互動式詢問要裝哪個
|
||||
|
||||
--profile=repo 成員 repo：實際寫 code 的子專案（預設）
|
||||
--profile=orchestrator 總管：管一群成員 repo 的上層資料夾
|
||||
未指定 → 自動偵測並請你確認一次（結果寫進 system-dev/.profile，之後不再問）
|
||||
HELP
|
||||
else
|
||||
cat <<'HELP'
|
||||
Usage: install.sh [--wiki | --sdd | --all]
|
||||
Usage: install.sh [--wiki | --sdd | --all] [--profile=repo|orchestrator]
|
||||
--wiki Install LLM Wiki only (CC memory system + secret protection)
|
||||
--sdd Install SDD system only (require a design doc before touching code)
|
||||
--all Install both (default)
|
||||
no flag Interactively ask which to install
|
||||
|
||||
--profile=repo Member repo: a project where code actually gets written (default)
|
||||
--profile=orchestrator Orchestrator: the folder that manages several member repos
|
||||
unset -> auto-detect and ask once (result stored in system-dev/.profile)
|
||||
HELP
|
||||
fi
|
||||
exit 0 ;;
|
||||
@@ -107,6 +127,57 @@ echo ""
|
||||
t "📦 安裝模組：$MODULE" "📦 Module: $MODULE"
|
||||
echo ""
|
||||
|
||||
# ── 決定 profile（scope 軸）──────────────────────────
|
||||
# 必須在**寫任何檔案之前**問完（EARS-1.1.3）——裝了一半才問是最差的體驗。
|
||||
#
|
||||
# 偵測規則：目前目錄下有多個「各自帶 .git 的子目錄」＝ 這裡像是管著一群 repo 的上層
|
||||
# → 建議 orchestrator。偵測只給建議，**仍要人確認一次**（一次性，之後寫進 marker 檔）。
|
||||
detect_profile() {
|
||||
local n=0 d
|
||||
for d in */; do
|
||||
[ -d "$d/.git" ] && n=$((n + 1))
|
||||
[ "$n" -ge 2 ] && break
|
||||
done
|
||||
if [ "$n" -ge 2 ]; then printf 'orchestrator'; else printf 'repo'; fi
|
||||
}
|
||||
|
||||
if [ -z "$PROFILE" ]; then
|
||||
SUGGESTED="$(detect_profile)"
|
||||
if [ -t 0 ]; then
|
||||
echo ""
|
||||
t "🧭 這個資料夾是哪一種？（決定裝哪一部憲法）" \
|
||||
"🧭 What is this folder? (decides which constitution gets installed)"
|
||||
t " 1) 成員 repo —— 實際寫 code 的子專案" \
|
||||
" 1) Member repo — a project where code actually gets written"
|
||||
t " 2) 總管 —— 管一群成員 repo 的上層資料夾" \
|
||||
" 2) Orchestrator — the folder that manages several member repos"
|
||||
echo ""
|
||||
if [ "$SUGGESTED" = "orchestrator" ]; then
|
||||
t " （偵測到底下有多個各自獨立的 repo → 看起來像 2）" \
|
||||
" (found multiple independent repos below -> looks like 2)"
|
||||
else
|
||||
t " （沒偵測到多個獨立 repo → 看起來像 1）" \
|
||||
" (no multiple independent repos found -> looks like 1)"
|
||||
fi
|
||||
tn "請輸入 1 / 2 [預設：$SUGGESTED]：" "Enter 1 / 2 [default: $SUGGESTED]: "
|
||||
read -r pchoice || pchoice=""
|
||||
case "$pchoice" in
|
||||
1) PROFILE="repo" ;;
|
||||
2) PROFILE="orchestrator" ;;
|
||||
*) PROFILE="$SUGGESTED" ;;
|
||||
esac
|
||||
else
|
||||
# 非互動（curl | bash 無 tty）→ 用偵測值，並在結尾大聲說它是怎麼決定的
|
||||
PROFILE="$SUGGESTED"
|
||||
t "🧭 非互動環境 → 自動判定 profile：$PROFILE（可事後改 system-dev/.profile）" \
|
||||
"🧭 Non-interactive -> auto-detected profile: $PROFILE (change system-dev/.profile later)"
|
||||
fi
|
||||
fi
|
||||
|
||||
echo ""
|
||||
t "🧭 安裝 profile：$PROFILE" "🧭 Profile: $PROFILE"
|
||||
echo ""
|
||||
|
||||
# ── 重複安裝防呆（1.10.1）：install 只管「全新安裝」，一切後續歸 update ──
|
||||
# 判準是「裝過沒」，不分新版舊版：
|
||||
# - 新結構 system-dev/ 已存在，或
|
||||
@@ -243,97 +314,93 @@ download_if_missing() {
|
||||
fi
|
||||
}
|
||||
|
||||
# ── 共用結構 ──────────────────────────────────────
|
||||
# 工具自己的文件骨架收進 system-dev/docs/（不污染用戶根目錄、不跟用戶自己的 docs/ 混）。
|
||||
# 注意語義分離：這裡的 system-dev/docs/ 是「工具文件」；用戶的 raw source（原始文件）
|
||||
# 另有其處（見上方 vault 偵測），工具只讀、不搬。
|
||||
# .claude/ 只留 CC 死綁的 commands/ + hooks/，工具資料一律不放這。
|
||||
create_dir "system-dev/docs/1-vision"
|
||||
create_dir "system-dev/docs/2-architecture/decisions"
|
||||
create_dir "system-dev/docs/4-guides"
|
||||
create_dir "system-dev/docs/5-records/incidents"
|
||||
create_dir "system-dev/docs/5-records/test-reports"
|
||||
create_dir "system-dev/docs/6-user"
|
||||
create_dir ".claude/commands"
|
||||
create_dir ".claude/hooks"
|
||||
download_if_missing "system-dev/docs/README.md" "$REPO_URL/system-dev/docs/README.md"
|
||||
# ── Manifest 驅動的安裝（取代原本硬編的檔案清單）──────────────
|
||||
# 為什麼改成這樣（SDD jdd-dual-profile 決策 D1）：
|
||||
# 原本清單硬編在這裡，update.sh 另有一份幾乎重複的硬編。兩份手抄必然漂移，
|
||||
# 而且**已經漂了**——install 從來不裝 wiki-first-search.sh / subagent-wiki-guard.sh /
|
||||
# publish-lag-check.sh / decisions-summary.md，但 update 會裝／會保留。
|
||||
# ⇒ 乾淨安裝的人反而拿不到最新三版的招牌功能。
|
||||
# 現在兩支腳本讀同一份 manifest，這類漂移在結構上不可能再發生。
|
||||
#
|
||||
# manifest 欄位：src \t dest \t class \t module \t profile（詳見 template/manifest/common.tsv）
|
||||
|
||||
# Logseq 任務 marker 解析（單一真相源）：vault 萃取（/wiki-extract）與 tasks→Project
|
||||
# 投影（tasks-project-sync）共用同一套解析，別各寫一份。放共用區，兩模組都拿得到。
|
||||
download_if_missing "system-dev/docs/4-guides/logseq-markers.md" "$REPO_URL/system-dev/docs/4-guides/logseq-markers.md"
|
||||
MANIFEST_DIR="system-dev/.template-manifest.d"
|
||||
mkdir -p "$MANIFEST_DIR"
|
||||
|
||||
# 工具版號：放 system-dev/，不寄生 .claude/。
|
||||
download_if_missing "system-dev/VERSION" "$REPO_URL/system-dev/VERSION"
|
||||
fetch_manifest() { # $1=名稱（common|repo|orchestrator）
|
||||
local name="$1" out="$MANIFEST_DIR/$1.tsv"
|
||||
if curl -sSL "$REPO_URL/manifest/$name.tsv" -o "$out" 2>/dev/null && [ -s "$out" ]; then
|
||||
return 0
|
||||
fi
|
||||
rm -f "$out"
|
||||
return 1
|
||||
}
|
||||
|
||||
# ── WIKI 模組 ─────────────────────────────────────
|
||||
# wiki 是工具資料 → 放 system-dev/wiki/（不放 .claude/）。
|
||||
# commands/ 與 hooks/ 是 CC 機制檔 → 維持 .claude/。
|
||||
if $WANT_WIKI; then
|
||||
create_dir "system-dev/wiki"
|
||||
download_if_missing "system-dev/wiki/INDEX.md" "$REPO_URL/system-dev/wiki/INDEX.md"
|
||||
download_if_missing "system-dev/wiki/TAXONOMY.md" "$REPO_URL/system-dev/wiki/TAXONOMY.md"
|
||||
download_if_missing "system-dev/wiki/status.md" "$REPO_URL/system-dev/wiki/status.md"
|
||||
download_if_missing "system-dev/wiki/mistakes.md" "$REPO_URL/system-dev/wiki/mistakes.md"
|
||||
download_if_missing "system-dev/wiki/principles.md" "$REPO_URL/system-dev/wiki/principles.md"
|
||||
download_if_missing "system-dev/wiki/.wikiignore" "$REPO_URL/system-dev/wiki/.wikiignore"
|
||||
if ! fetch_manifest common; then
|
||||
echo "❌ 抓不到安裝清單（$REPO_URL/manifest/common.tsv）——網路或來源網址有問題，中止。" >&2
|
||||
exit 1
|
||||
fi
|
||||
fetch_manifest "$PROFILE" || true # profile 專屬清單可以是空的
|
||||
|
||||
# wiki 改寫產物（AI 自讀定稿卡片）的正式落點：由工具建好，不靠用戶自救。
|
||||
create_dir "system-dev/wiki/cards"
|
||||
# src 前綴 → 實際來源網址
|
||||
resolve_src() { # $1=src 欄
|
||||
case "$1" in
|
||||
T:*) printf '%s/%s' "$REPO_URL" "${1#T:}" ;;
|
||||
S:*) printf '%s/%s' "$SCRIPTS_URL" "${1#S:}" ;;
|
||||
*) printf '' ;;
|
||||
esac
|
||||
}
|
||||
|
||||
# 要不要裝這一行（依模組）
|
||||
want_module() { # $1=module 欄
|
||||
case "$1" in
|
||||
core) return 0 ;;
|
||||
wiki) $WANT_WIKI && return 0 || return 1 ;;
|
||||
sdd) $WANT_SDD && return 0 || return 1 ;;
|
||||
*) return 1 ;;
|
||||
esac
|
||||
}
|
||||
|
||||
# 逐行安裝。CLAUDE.md（class=claude-md）不在這裡處理——它要三段組裝，走下方專段。
|
||||
install_from_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
|
||||
case "$class" in
|
||||
dir)
|
||||
create_dir "$dest"
|
||||
;;
|
||||
claude-md)
|
||||
CLAUDE_MD_SRC="$(resolve_src "$src")" # 交給下方 CLAUDE.md 組裝段
|
||||
;;
|
||||
*)
|
||||
url="$(resolve_src "$src")"
|
||||
[ -z "$url" ] && continue
|
||||
download_if_missing "$dest" "$url"
|
||||
;;
|
||||
esac
|
||||
done < "$f"
|
||||
}
|
||||
|
||||
CLAUDE_MD_SRC=""
|
||||
install_from_manifest "$MANIFEST_DIR/common.tsv"
|
||||
install_from_manifest "$MANIFEST_DIR/$PROFILE.tsv"
|
||||
|
||||
# wiki 卡片落點的 .gitkeep（目錄由 manifest 建，這顆種子檔留在腳本裡）
|
||||
if $WANT_WIKI && [ -d "system-dev/wiki/cards" ]; then
|
||||
[ -f "system-dev/wiki/cards/.gitkeep" ] || { : > "system-dev/wiki/cards/.gitkeep"; CREATED+=("system-dev/wiki/cards/.gitkeep"); }
|
||||
|
||||
download_if_missing ".claude/commands/wiki-init.md" "$REPO_URL/.claude/commands/wiki-init.md"
|
||||
download_if_missing ".claude/commands/wiki-capture.md" "$REPO_URL/.claude/commands/wiki-capture.md"
|
||||
download_if_missing ".claude/commands/wiki-update.md" "$REPO_URL/.claude/commands/wiki-update.md"
|
||||
download_if_missing ".claude/commands/wiki-recall.md" "$REPO_URL/.claude/commands/wiki-recall.md"
|
||||
# vault 增量萃取（Logseq/Obsidian → system-dev/wiki，冪等）：給 Routine 反覆跑。
|
||||
download_if_missing ".claude/commands/wiki-extract.md" "$REPO_URL/.claude/commands/wiki-extract.md"
|
||||
|
||||
# wiki 相關 hooks：接關 + 機敏掃描
|
||||
download_if_missing ".claude/hooks/session-start-recall.sh" "$REPO_URL/.claude/hooks/session-start-recall.sh"
|
||||
download_if_missing ".claude/hooks/wiki-secret-scan.sh" "$REPO_URL/.claude/hooks/wiki-secret-scan.sh"
|
||||
|
||||
# Cowork（claude.ai）整理 wiki 用的 skill：與 CC 的 /wiki-init 共用同一套規則
|
||||
# （含 typed-edge、frontmatter 標籤、gloss）。沒這支 → claude.ai 來掃時身上沒規則。
|
||||
download_if_missing "system-dev/docs/SKILL.md" "$REPO_URL/system-dev/docs/SKILL.md"
|
||||
fi
|
||||
|
||||
# ── SDD 模組 ──────────────────────────────────────
|
||||
if $WANT_SDD; then
|
||||
create_dir "system-dev/docs/3-specs"
|
||||
download_if_missing "system-dev/docs/3-specs/TEMPLATE-sdd/design.md" "$REPO_URL/system-dev/docs/3-specs/TEMPLATE-sdd/design.md"
|
||||
download_if_missing "system-dev/docs/3-specs/TEMPLATE-sdd/tasks.md" "$REPO_URL/system-dev/docs/3-specs/TEMPLATE-sdd/tasks.md"
|
||||
download_if_missing "system-dev/docs/2-architecture/decisions/TEMPLATE-adr.md" "$REPO_URL/system-dev/docs/2-architecture/decisions/TEMPLATE-adr.md"
|
||||
|
||||
download_if_missing ".claude/commands/sdd-check.md" "$REPO_URL/.claude/commands/sdd-check.md"
|
||||
download_if_missing ".claude/hooks/sdd-guard.sh" "$REPO_URL/.claude/hooks/sdd-guard.sh"
|
||||
|
||||
# SDD 生命週期鐵律（1.14，issue #6）：規則真相源 + 規格變更緩衝區 + 獨立單一活性檢查
|
||||
download_if_missing "system-dev/docs/3-specs/SDD-LIFECYCLE.md" "$REPO_URL/system-dev/docs/3-specs/SDD-LIFECYCLE.md"
|
||||
download_if_missing "system-dev/docs/3-specs/pending-changes.md" "$REPO_URL/system-dev/docs/3-specs/pending-changes.md"
|
||||
download_if_missing "system-dev/scripts/sdd-active-check.sh" "$REPO_URL/scripts/sdd-active-check.sh"
|
||||
|
||||
# ── tasks⇄Project 投影（optional，issue #16）──────────────────
|
||||
# 帶檔 ≠ 啟用：workflow yaml 只是「留記錄＋手動啟用素材」，啟用＝對話答好且 acr push。
|
||||
# 投影邏輯依附 tasks.md（住 3-specs），故隨 SDD 模組帶下來；裝了不代表開。
|
||||
create_dir "system-dev/workflows"
|
||||
download_if_missing "system-dev/workflows/tasks-project-sync.yaml" "$REPO_URL/system-dev/workflows/tasks-project-sync.yaml"
|
||||
download_if_missing "system-dev/workflows/tasks-project-sync.local.sh" "$REPO_URL/system-dev/workflows/tasks-project-sync.local.sh"
|
||||
fi
|
||||
|
||||
# ── 安裝/更新腳本：一開始就放進 system-dev/scripts/ ──
|
||||
# 為什麼一開始就裝：之後要更新，用戶（或 CC）直接 `bash system-dev/scripts/update.sh`，
|
||||
# 不必每次都記那串 curl。腳本來源在 main/scripts/（不在 template/）。
|
||||
create_dir "system-dev/scripts"
|
||||
download_if_missing "system-dev/scripts/install.sh" "$SCRIPTS_URL/install.sh"
|
||||
download_if_missing "system-dev/scripts/update.sh" "$SCRIPTS_URL/update.sh"
|
||||
|
||||
# ── 共用 hook：專案自訂禁令骨架（預設停用）────────
|
||||
download_if_missing ".claude/hooks/pre-write-guard.sh" "$REPO_URL/.claude/hooks/pre-write-guard.sh"
|
||||
|
||||
# ── 共用指引：GitHub issue 處理（讀/回普世，跨 repo 發要先問，禁自動輪詢）──
|
||||
download_if_missing ".claude/commands/issue-handle.md" "$REPO_URL/.claude/commands/issue-handle.md"
|
||||
# ── scope 軸 marker：這個實例是哪一種 ────────────────
|
||||
# 這是 role-lib.sh 判 scope 的**唯一**來源。AI 代裝路徑也必須寫出同格式的檔。
|
||||
printf '%s\n' "$PROFILE" > "system-dev/.profile"
|
||||
CREATED+=("system-dev/.profile ($PROFILE)")
|
||||
|
||||
chmod +x .claude/hooks/*.sh 2>/dev/null || true
|
||||
chmod +x .claude/hooks/lib/*.sh 2>/dev/null || true
|
||||
chmod +x system-dev/workflows/*.sh 2>/dev/null || true
|
||||
chmod +x system-dev/scripts/*.sh 2>/dev/null || true
|
||||
|
||||
@@ -346,7 +413,9 @@ build_hooks_json() {
|
||||
session_hooks='{ "type": "command", "command": ".claude/hooks/session-start-recall.sh" }'
|
||||
fi
|
||||
|
||||
# PreToolUse 依模組疊加
|
||||
# PreToolUse 依模組疊加。
|
||||
# 順序原則：**範圍大的擋在前**——這樣錯誤訊息會指向最根本的那條規則，
|
||||
# 而不是讓人先修一個表層問題、修完才發現底下還有一條。
|
||||
local pt=()
|
||||
$WANT_SDD && pt+=('{ "type": "command", "command": ".claude/hooks/sdd-guard.sh" }')
|
||||
pt+=('{ "type": "command", "command": ".claude/hooks/pre-write-guard.sh" }')
|
||||
@@ -354,7 +423,15 @@ build_hooks_json() {
|
||||
local IFS=,
|
||||
pretool_hooks="${pt[*]}"
|
||||
|
||||
printf '{\n "hooks": {\n'
|
||||
# role 軸預設值：由 profile 決定，寫進 settings.json 的 env。
|
||||
# 為什麼要寫死一個預設：AGENT_ROLE 沒設時 role-lib.sh 會「依 scope 推定」，
|
||||
# 但推定是保險不是設計——明寫出來，人才看得見自己這個實例預設是什麼身分。
|
||||
local default_role="engineer"
|
||||
[ "$PROFILE" = "orchestrator" ] && default_role="orchestrator"
|
||||
|
||||
printf '{\n'
|
||||
printf ' "env": { "AGENT_ROLE": "%s" },\n' "$default_role"
|
||||
printf ' "hooks": {\n'
|
||||
if [ -n "$session_hooks" ]; then
|
||||
printf ' "SessionStart": [\n { "matcher": "startup|resume|clear",\n "hooks": [ %s ] }\n ],\n' "$session_hooks"
|
||||
fi
|
||||
@@ -369,19 +446,75 @@ else
|
||||
SKIPPED+=(".claude/settings.json $(tn '(已存在，請手動合併 hooks)' '(already exists — merge hooks manually)')")
|
||||
fi
|
||||
|
||||
# ── CLAUDE.md：只在完全不存在時建立 ────────────────
|
||||
# 新建時把偵測到的 raw source 宣告 append 進去（在建立的當下寫入，
|
||||
# 不回頭改使用者既有的 CLAUDE.md，維持「已有不覆蓋」原則）。
|
||||
# ── CLAUDE.md：由 profile 範本三段組裝 ────────────────
|
||||
# 結構（界標用 HTML 註解：md 渲染看不見、grep 定位得到、CC 讀得到）：
|
||||
#
|
||||
# <!-- sdt:framework begin profile=X version=Y sha256=Z -->
|
||||
# （profile 憲法範本原文，一字不改）
|
||||
# <!-- sdt:framework end -->
|
||||
# <!-- sdt:local begin -->
|
||||
# （raw source 宣告 ＋ 之後使用者/CC 自由追加）
|
||||
# <!-- sdt:local end -->
|
||||
#
|
||||
# 為什麼要界標：在這之前 CLAUDE.md 是「整份下載 ＋ append」，**沒有任何邊界** ⇒
|
||||
# update 無從分辨「這段是框架的、那段是你寫的」，因此永遠不敢覆蓋，
|
||||
# 框架改了憲法也送不到既有實例；而使用者手改框架段也沒人看得見。
|
||||
# 有了界標＋sha256，兩件事同時解決：框架段可安全更新、被手改時抓得到（漂移偵測）。
|
||||
sdt_sha256() { # 跨平台取 sha256（macOS 用 shasum，Linux 多為 sha256sum）
|
||||
if command -v shasum >/dev/null 2>&1; then shasum -a 256 "$1" | awk '{print $1}'
|
||||
elif command -v sha256sum >/dev/null 2>&1; then sha256sum "$1" | awk '{print $1}'
|
||||
else printf 'nohash'; fi
|
||||
}
|
||||
|
||||
if [ ! -f "CLAUDE.md" ]; then
|
||||
download_if_missing "CLAUDE.md" "$REPO_URL/CLAUDE.md"
|
||||
if [ -f "CLAUDE.md" ]; then
|
||||
emit_raw_source_block >> CLAUDE.md
|
||||
CREATED+=("CLAUDE.md $(tn "← 已寫入 raw source 宣告（${VAULT_TYPE}）" "← raw source declaration written (${VAULT_TYPE})")")
|
||||
if [ -z "$CLAUDE_MD_SRC" ]; then
|
||||
echo "⚠️ manifest 沒有指定 $PROFILE 的 CLAUDE.md 範本，略過憲法安裝" >&2
|
||||
else
|
||||
FW_TMP="$(mktemp)"
|
||||
if curl -sSL "$CLAUDE_MD_SRC" -o "$FW_TMP" 2>/dev/null && [ -s "$FW_TMP" ]; then
|
||||
FW_SHA="$(sdt_sha256 "$FW_TMP")"
|
||||
TOOL_VER="$(tr -d '[:space:]' < system-dev/VERSION 2>/dev/null || echo 'unknown')"
|
||||
{
|
||||
printf '<!-- sdt:framework begin profile=%s version=%s sha256=%s -->\n' \
|
||||
"$PROFILE" "$TOOL_VER" "$(printf '%s' "$FW_SHA" | cut -c1-12)"
|
||||
cat "$FW_TMP"
|
||||
printf '<!-- sdt:framework end -->\n\n'
|
||||
printf '<!-- sdt:local begin — 這一區是你的，update 永遠不會動它 -->\n'
|
||||
emit_raw_source_block
|
||||
printf '\n<!-- sdt:local end -->\n'
|
||||
} > CLAUDE.md
|
||||
rm -f "$FW_TMP"
|
||||
CREATED+=("CLAUDE.md $(tn "← ${PROFILE} 憲法 ＋ 本地補充區（raw source: ${VAULT_TYPE}）" "← ${PROFILE} constitution + local section (raw source: ${VAULT_TYPE})")")
|
||||
else
|
||||
rm -f "$FW_TMP"
|
||||
echo "⚠️ 抓不到 $PROFILE 憲法範本（$CLAUDE_MD_SRC），CLAUDE.md 未建立" >&2
|
||||
fi
|
||||
fi
|
||||
else
|
||||
SKIPPED+=("CLAUDE.md $(tn '(已存在，請手動加入對應區塊)' '(already exists — add the block manually)')")
|
||||
SKIPPED+=("CLAUDE.md $(tn '(已存在，未覆蓋——要導入 profile 憲法請跑 update.sh)' '(already exists — run update.sh to adopt the profile constitution)')")
|
||||
fi
|
||||
|
||||
# ── 產生 .template-manifest（漂移偵測的基準）────────────
|
||||
# 記下每個安裝產物「安裝當下」的雜湊。update 時比對：
|
||||
# 實檔 sha == 這裡的 sha → 乾淨，可安全覆蓋成新版
|
||||
# 實檔 sha != 這裡的 sha → **被手改過**，不覆蓋、列進漂移清單
|
||||
# 沒有這張表，就只能「不敢覆蓋」或「盲目覆蓋」二選一，兩個都錯。
|
||||
{
|
||||
printf '# dest\tclass\tversion\tsha256 —— 安裝當下的快照，供 update 判漂移用，勿手改\n'
|
||||
TOOL_VER="$(tr -d '[:space:]' < system-dev/VERSION 2>/dev/null || echo 'unknown')"
|
||||
for mf in "$MANIFEST_DIR/common.tsv" "$MANIFEST_DIR/$PROFILE.tsv"; do
|
||||
[ -f "$mf" ] || continue
|
||||
while IFS=$'\t' read -r m_src m_dest m_class m_module m_profile; do
|
||||
case "$m_src" in ''|'#'*) continue ;; esac
|
||||
[ -z "${m_dest:-}" ] && continue
|
||||
[ "$m_class" = "dir" ] && continue
|
||||
[ -f "$m_dest" ] || continue
|
||||
printf '%s\t%s\t%s\t%s\n' "$m_dest" "$m_class" "$TOOL_VER" "$(sdt_sha256 "$m_dest")"
|
||||
done < "$mf"
|
||||
done
|
||||
} > system-dev/.template-manifest
|
||||
CREATED+=("system-dev/.template-manifest")
|
||||
|
||||
# ── 輸出結果 ──────────────────────────────────────
|
||||
echo ""
|
||||
t "✅ 建立了：" "✅ Created:"
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
# instance-names.txt — 實例專名黑名單（機械閘 #2 的判準來源）
|
||||
#
|
||||
# 鐵律（《分離導入規格》第一節鐵律 2）：
|
||||
# **框架不含實例資料**——L1 範本檔出現具體專案名（arcrun、mira、leo21c…）＝格式錯誤。
|
||||
# 換一家公司照樣成立的才配住在框架裡；換一家公司就不成立的，那是 L2 政策包或 L3 實例的事。
|
||||
#
|
||||
# 用法：scripts/check-no-instance-names.sh 掃 template/（範本區），命中即 fail。
|
||||
#
|
||||
# ── 豁免（唯一合法的例外，留痕可審）──────────────────────
|
||||
# 在命中行的行尾加註記： sdt-instance-name-ok
|
||||
# 規矩：豁免必須附一句「為什麼還不能拿掉」，且應該有對應的搬遷計畫。
|
||||
# 豁免不是赦免——它是「這行欠著，記在帳上」。
|
||||
#
|
||||
# ── 不受此檢查的地方 ────────────────────────────────
|
||||
# · policy pack（L2 政策包本來就是一家之言，專名是它的內容不是它的錯）
|
||||
# · 本 repo 自己的工作現場：docs/、system-dev/、CHANGELOG.md、README*、scripts/
|
||||
# （那些是「我們怎麼做出來的」，不是發給別人的範本）
|
||||
#
|
||||
# 一行一個詞，大小寫不敏感。# 開頭為註解。
|
||||
|
||||
arcrun
|
||||
mira
|
||||
leo21c
|
||||
inkstone
|
||||
uncle6
|
||||
polaris
|
||||
richblack
|
||||
+137
-4
@@ -127,13 +127,88 @@ if [ "$NEEDS_MIGRATE" = "yes" ]; then
|
||||
echo ""
|
||||
fi
|
||||
|
||||
# ── 漂移偵測（1.19.0 新增）─────────────────────────
|
||||
# 病根：實例會手改安裝產物（hook、範本），而**沒有任何機制知道**。
|
||||
# 實測基線（2026-08-05，拿一個真實使用中的實例對照框架）：
|
||||
# 6 支框架 hook 裡 **4 支已被手改**，另有 11 支是該實例自己發明的。
|
||||
# 兩層後果：① 框架修好的 bug 送不到那些檔 ② 手改內容沒人審、沒回饋回框架
|
||||
# ⇒ 同一個坑每個實例各踩一次。
|
||||
#
|
||||
# 判準：安裝當下的 sha（記在 system-dev/.template-manifest）vs 現在的 sha。
|
||||
# 相同 → 沒動過 → 安全覆蓋成新版
|
||||
# 不同 → **被手改過** → 不覆蓋、另存 .new、列進漂移清單，讓人自己決定
|
||||
#
|
||||
# 為什麼不直接覆蓋：無聲吃掉別人的修改（他多半是在修一個框架還沒修的問題）。
|
||||
# 為什麼不永遠不覆蓋：那更新就永遠送不到 ＝ 等於沒有更新機制。
|
||||
# **分辨得出來**才是解法，兩個極端都不對。
|
||||
DRIFTED=()
|
||||
|
||||
sdt_sha256() {
|
||||
if command -v shasum >/dev/null 2>&1; then shasum -a 256 "$1" | awk '{print $1}'
|
||||
elif command -v sha256sum >/dev/null 2>&1; then sha256sum "$1" | awk '{print $1}'
|
||||
else printf 'nohash'; fi
|
||||
}
|
||||
|
||||
MANIFEST_FILE="system-dev/.template-manifest"
|
||||
|
||||
manifest_sha() { # 查登記的 sha；查不到回空
|
||||
[ -f "$MANIFEST_FILE" ] || return 0
|
||||
awk -F'\t' -v d="$1" '!/^#/ && $1==d {print $4; exit}' "$MANIFEST_FILE"
|
||||
}
|
||||
|
||||
# 本次 update 經手過的檔（不論更新、保留或漂移）。收工時用它重寫 manifest。
|
||||
# ⚠️ 沒有這一步的話會出現**自己造的 bug**：update 把檔覆蓋成新版後，manifest 還留著舊 sha
|
||||
# ⇒ 下一次跑 update 會把「框架自己更新的檔」誤判成「使用者手改」，整排假漂移。
|
||||
# 基準快照必須跟著實檔一起前進。
|
||||
MANAGED=()
|
||||
|
||||
is_drifted() { # 0=被手改過；1=沒動過或無從判斷（保守，不誤報）
|
||||
local dest="$1" recorded
|
||||
recorded="$(manifest_sha "$dest")"
|
||||
[ -z "$recorded" ] && return 1
|
||||
[ -f "$dest" ] || return 1
|
||||
[ "$(sdt_sha256 "$dest")" = "$recorded" ] && return 1
|
||||
return 0
|
||||
}
|
||||
|
||||
# ── 下載健全性檢查（修一個舊 bug）──────────────────
|
||||
# 原本只用 [ -s ]＝「非空就接受」。但 curl 對 404 會把「404: Not Found」當內容寫出來，
|
||||
# **那也是非空** ⇒ 好檔被覆寫成一行垃圾，而且沒有任何錯誤訊息。
|
||||
# 實錄：SKILL.md 曾被無聲覆寫 260 行 → 1 行（template issue #13）。
|
||||
# 諷刺的是本腳本的「版本號比對」那段早就防了這招（見上方 REMOTE_VER 的驗證），
|
||||
# 檔案下載這條路卻沒防——同一個坑，防了一半。
|
||||
looks_like_error_page() {
|
||||
local f="$1"
|
||||
[ -s "$f" ] || return 0 # 空的 → 當失敗
|
||||
# 極短又長得像錯誤訊息 → 當失敗（正常範本檔不會只有一兩行還寫著 404）
|
||||
if [ "$(wc -l < "$f" | tr -d ' ')" -le 2 ] && head -c 200 "$f" | grep -qiE '40[0-9]|not found|<html'; then
|
||||
return 0
|
||||
fi
|
||||
return 1
|
||||
}
|
||||
|
||||
# ── 工具函式 ───────────────────────────────────────
|
||||
# 覆蓋更新：模板/邏輯檔，無條件抓最新版蓋掉。
|
||||
# 覆蓋更新：模板/邏輯檔，抓最新版蓋掉——**除非它被手改過**。
|
||||
update_file() {
|
||||
local dest="$1" src="$2"
|
||||
mkdir -p "$(dirname "$dest")"
|
||||
MANAGED+=("$dest\toverwrite")
|
||||
if [ -f "$dest" ]; then
|
||||
if curl -sSL "$src" -o "$dest.tmp" 2>/dev/null && [ -s "$dest.tmp" ]; then
|
||||
if is_drifted "$dest"; then
|
||||
# 被手改過：不覆蓋，把新版放旁邊供 diff
|
||||
if curl -sSL "$src" -o "$dest.new" 2>/dev/null && ! looks_like_error_page "$dest.new"; then
|
||||
if cmp -s "$dest" "$dest.new"; then
|
||||
rm -f "$dest.new" # 手改後剛好等於新版 → 沒事，不用吵
|
||||
else
|
||||
DRIFTED+=("$dest")
|
||||
fi
|
||||
else
|
||||
rm -f "$dest.new"
|
||||
DRIFTED+=("$dest")
|
||||
fi
|
||||
return 0
|
||||
fi
|
||||
if curl -sSL "$src" -o "$dest.tmp" 2>/dev/null && ! looks_like_error_page "$dest.tmp"; then
|
||||
if cmp -s "$dest" "$dest.tmp"; then
|
||||
rm -f "$dest.tmp" # 內容相同，不算更新
|
||||
else
|
||||
@@ -145,7 +220,7 @@ update_file() {
|
||||
t " ⚠️ 抓取失敗，保留原檔：$dest" " ⚠️ Download failed, keeping the original: $dest"
|
||||
fi
|
||||
else
|
||||
if curl -sSL "$src" -o "$dest" 2>/dev/null && [ -s "$dest" ]; then
|
||||
if curl -sSL "$src" -o "$dest" 2>/dev/null && ! looks_like_error_page "$dest"; then
|
||||
NEW+=("$dest") # 新功能：舊版沒有的檔
|
||||
else
|
||||
rm -f "$dest"
|
||||
@@ -163,12 +238,19 @@ keep_file() {
|
||||
# 不存在 → 抓範本下來（之後由使用者/CC 填）；已存在 → 當用戶資料保留，絕不覆蓋。
|
||||
add_if_missing() {
|
||||
local dest="$1" src="$2"
|
||||
MANAGED+=("$dest\tadd-if-missing")
|
||||
if [ -f "$dest" ]; then
|
||||
KEPT+=("$dest")
|
||||
elif curl -sSL "$src" -o "$dest" 2>/dev/null && [ -s "$dest" ]; then
|
||||
return 0
|
||||
fi
|
||||
# 🐛 修：原本少了 mkdir -p ⇒ 目標在**新目錄**時 curl 直接失敗，
|
||||
# 但 VERSION 照樣升上去 ＝ 典型假綠（2026-07 在一個實例升級時撞到，當時記「待回報 template」）。
|
||||
mkdir -p "$(dirname "$dest")"
|
||||
if curl -sSL "$src" -o "$dest" 2>/dev/null && ! looks_like_error_page "$dest"; then
|
||||
NEW+=("$dest")
|
||||
else
|
||||
rm -f "$dest"
|
||||
t " ⚠️ 抓取失敗：$dest" " ⚠️ Download failed: $dest"
|
||||
fi
|
||||
}
|
||||
|
||||
@@ -318,6 +400,29 @@ if [ ${#UPDATED[@]} -gt 0 ]; then
|
||||
t "⬆️ 已更新（覆蓋成新版）：" "⬆️ Updated (overwritten with the new version):"
|
||||
for f in "${UPDATED[@]}"; do echo " ~ $f"; done
|
||||
fi
|
||||
if [ ${#DRIFTED[@]} -gt 0 ]; then
|
||||
echo ""
|
||||
t "⚠️ 下列 ${#DRIFTED[@]} 個檔被手改過，這一版**沒有**覆蓋它們：" \
|
||||
"⚠️ ${#DRIFTED[@]} file(s) were modified by hand and were NOT overwritten:"
|
||||
for f in "${DRIFTED[@]}"; do
|
||||
if [ -f "$f.new" ]; then
|
||||
t " ✋ $f → 新版已放在 $f.new，請 diff" \
|
||||
" ✋ $f → new version saved as $f.new — please diff"
|
||||
else
|
||||
t " ✋ $f （新版抓取失敗，稍後再試）" \
|
||||
" ✋ $f (couldn't fetch the new version; try again later)"
|
||||
fi
|
||||
done
|
||||
echo ""
|
||||
t " 這代表什麼：你（或某個 CC）改過框架發下來的檔。" \
|
||||
" What this means: you (or a CC) edited a file that the framework ships."
|
||||
t " 兩條路，擇一——別放著不管，放著＝框架之後的修正永遠送不到這個檔：" \
|
||||
" Pick one — leaving it means future framework fixes will never reach this file:"
|
||||
t " ① 把你的改動寫成框架提案（推薦）——一次修全家，別人也拿得到" \
|
||||
" 1. Turn your change into a framework proposal (recommended) — fixes it for everyone"
|
||||
t " ② 放棄本地改動：mv <檔>.new <檔>" \
|
||||
" 2. Drop your local change: mv <file>.new <file>"
|
||||
fi
|
||||
if [ ${#NEW[@]} -eq 0 ] && [ ${#UPDATED[@]} -eq 0 ]; then
|
||||
echo ""
|
||||
t "✨ 模板邏輯檔已全部最新，無需變動。" \
|
||||
@@ -387,6 +492,34 @@ PYEOF
|
||||
fi
|
||||
fi
|
||||
|
||||
# ── 重寫漂移基準快照（manifest）──────────────────────
|
||||
# 兩個作用：
|
||||
# ① 舊實例（1.18.x 以前沒有 manifest）→ 這一輪之後就有了，下次起就能偵測漂移。
|
||||
# 注意本輪它們**不會**被判漂移（查無登記＝不判定），這是刻意的保守：
|
||||
# 沒有基準就宣稱「你改過」等於瞎猜。第一輪建基準，第二輪起才有話語權。
|
||||
# ② 已有 manifest → 把「本輪更新過的檔」的 sha 推進到新值。
|
||||
# 少了這步就會自己造一個 bug：框架自己覆蓋的檔，下一輪被誤判成使用者手改。
|
||||
# 漂移中的檔**不更新其基準**——它們仍然是「相對於安裝版被改過」，下次還要繼續報。
|
||||
{
|
||||
printf '# dest\tclass\tversion\tsha256 —— update 維護的漂移基準，勿手改\n'
|
||||
for entry in ${MANAGED[@]+"${MANAGED[@]}"}; do
|
||||
m_dest="$(printf '%b' "$entry" | cut -f1)"
|
||||
m_class="$(printf '%b' "$entry" | cut -f2)"
|
||||
[ -f "$m_dest" ] || continue
|
||||
skip=""
|
||||
for d in ${DRIFTED[@]+"${DRIFTED[@]}"}; do
|
||||
[ "$d" = "$m_dest" ] && skip="yes" && break
|
||||
done
|
||||
if [ -n "$skip" ]; then
|
||||
# 保留原登記值（它還在漂移中，基準不能跟著漂）
|
||||
old="$(manifest_sha "$m_dest")"
|
||||
[ -n "$old" ] && printf '%s\t%s\t%s\t%s\n' "$m_dest" "$m_class" "$LOCAL_VER" "$old"
|
||||
continue
|
||||
fi
|
||||
printf '%s\t%s\t%s\t%s\n' "$m_dest" "$m_class" "$REMOTE_VER" "$(sdt_sha256 "$m_dest")"
|
||||
done
|
||||
} > "$MANIFEST_FILE.tmp" && mv "$MANIFEST_FILE.tmp" "$MANIFEST_FILE"
|
||||
|
||||
echo ""
|
||||
t "🚀 更新完成：${LOCAL_VER} → ${REMOTE_VER}" "🚀 Update complete: ${LOCAL_VER} → ${REMOTE_VER}"
|
||||
t " 下次更新直接跑：bash system-dev/scripts/update.sh" " Next time, just run: bash system-dev/scripts/update.sh"
|
||||
|
||||
@@ -44,13 +44,13 @@ issue 作者（可能是另一個 repo 的 CC，或人類）要靠你的回覆
|
||||
|
||||
## 3. 跨 repo 署名（鐵律 — 絕不可漏）
|
||||
|
||||
所有 repo（mira / graph-plugin / ingest-plugin / Arcrun / template…）共用**同一個 GitHub 帳號**發 issue/comment，
|
||||
所以 issue/comment 的 author **全顯示同一個帳號、看不出是哪個 repo 的 CC 發的**。
|
||||
當你的多個 repo 共用**同一個託管帳號**發 issue/comment 時，
|
||||
issue/comment 的 author **全顯示同一個帳號、看不出是哪個 repo 的 CC 發的**。
|
||||
|
||||
> **跨 repo 的 issue/comment 一律在開頭署名 `[<本 repo> CC]`**，靠內容署名溯源。
|
||||
|
||||
- 收件方 CC 回報：`[graph-plugin CC]` / `[mira CC]` / `[ingest CC]` / `[arcrun CC]`…
|
||||
- 總管下令/追問：`[InkStoneCo 總管]`
|
||||
- 收件方 CC 回報：`[<收件 repo 名> CC]`（例：`[<某子系統> CC]`）
|
||||
- 上游／總管下令、追問：`[<上游 repo 名> 總管]`
|
||||
- 署名放 comment **第一行或標題式開頭**（既有的「## 回報（graph CC）」即合格）。
|
||||
|
||||
為什麼只能這樣：GitHub issue/comment 的 author = 發送帳號，**沒有 per-repo 身份這設定**；
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
把**筆記 vault**（Logseq graph 如 `notes`/`kb`、或 Obsidian）的原始筆記，**增量、冪等**地
|
||||
萃成 `system-dev/wiki/` 的精耕卡＋`[[wikilink]]`。這是知識一庫 ingest 的**前段**：
|
||||
AI 只產卡片檔，下游 Arcrun ingest 再從 wikilink 機械拉三元組進 KBDB。
|
||||
AI 只產卡片檔，下游 ingest 管線再從 wikilink 機械拉三元組進知識庫。
|
||||
|
||||
> **跟 `/wiki-init` 的分工**：
|
||||
> - `/wiki-init` 是**首次**建結構 + 全庫首萃（一次性）。
|
||||
@@ -12,7 +12,7 @@ AI 只產卡片檔，下游 Arcrun ingest 再從 wikilink 機械拉三元組進
|
||||
|
||||
> **邊界（硬規矩，別越界）**
|
||||
> - 只往 `system-dev/wiki/` 寫。**絕不寫入 KBDB、絕不拉三元組紀錄**——三元組是下游
|
||||
> Arcrun 從你產的 `[[wikilink]]` + `## 關聯` 機械映射（另一張 issue），不是這支的事。
|
||||
> 下游 ingest 管線從你產的 `[[wikilink]]` + `## 關聯` 機械映射，不是這支的事。
|
||||
> - **原始筆記唯讀**：`journals/`、`pages/`、Obsidian 根 `.md` 是 leo 的手寫真身，
|
||||
> 改了會被 Syncthing 推回他手機污染筆記 App。萃取＝只讀原文、只寫 wiki。
|
||||
> - **D16 精耕非 RAG**：萃「知識點」成自包含原子卡 + 建 wikilink，**不地毯灌原文全文**。
|
||||
|
||||
@@ -0,0 +1,172 @@
|
||||
#!/bin/bash
|
||||
# role-lib.sh — 兩軸身分判定函式庫（被 source，不獨立掛 hook）
|
||||
#
|
||||
# 出處：《分離導入規格》第二節「兩軸身分（scope × role，全部機械判定，agent 不自我判斷）」
|
||||
# ＋《JDD 導入規格》第四節「角色與權限」。
|
||||
#
|
||||
# ── 為什麼是「兩軸」而不是「一個角色設定」──────────────────────
|
||||
# scope（我在誰的地盤）＝**安裝位置**決定：agent 在哪個資料夾醒來，
|
||||
# 就只讀得到那部憲法。來源＝ system-dev/.profile（install 時寫死）。
|
||||
# role （我是什麼工種）＝**環境變數 AGENT_ROLE** 決定：
|
||||
# orchestrator 效忠 root+journeys、禁寫 code 禁改 tasks；
|
||||
# engineer 效忠 requirements、禁改考卷（journeys/root/Gherkin）。
|
||||
#
|
||||
# 兩軸都有機械來源 ⇒ **沒有任何一格是靠 agent 自陳的**。
|
||||
# 這是整套封路的地基：agent 說自己是誰不算數，檔案和環境說了才算。
|
||||
#
|
||||
# ── 身分矩陣（注意右下角那個空格）──────────────────────────
|
||||
# AGENT_ROLE=orchestrator AGENT_ROLE=engineer
|
||||
# orchestrator profile PM 本尊 ✅ 總管 repo 裡的技術 subagent ✅
|
||||
# repo profile ❌ 不存在（擋） 寫 code 的 subagent ✅
|
||||
#
|
||||
# 左下角為什麼要擋而不是靜默降級：成員 repo 裡沒有 PM。
|
||||
# 靜默降級＝把一個設定錯誤變成「看起來正常但權限不對」，那比報錯危險。
|
||||
# 空格也是封路（分離導入規格 §2）。
|
||||
#
|
||||
# ── 為什麼是函式庫不是六支各自為政的 hook ────────────────────
|
||||
# 六支封路 hook 都要做同樣四件事：解析 JSON 取 file_path、算 repo 相對路徑、
|
||||
# 判 scope、判 role。各寫一份＝四處維護同一條規則，正是分離導入規格 §6.4
|
||||
# 要避免的「兩處維護同一條規則」。
|
||||
#
|
||||
# 用法（在 hook 裡）：
|
||||
# source "$(dirname "${BASH_SOURCE[0]}")/lib/role-lib.sh"
|
||||
# INPUT="$(cat)"
|
||||
# FILE_PATH="$(sdt_file_path "$INPUT")"
|
||||
# sdt_assert_identity || exit 2
|
||||
#
|
||||
# 誠實限制：這裡判的是「宣告出來的身分」。有人硬改 .profile 或亂設 AGENT_ROLE
|
||||
# 一樣會通過——它擋的是**意外與疏忽**，不是刻意繞道。留痕可審，不宣稱防偽。
|
||||
|
||||
# 注意：本檔被 source，**不要**在這裡 set -euo pipefail
|
||||
#（會把呼叫端的 shell 選項一起改掉，hook 的容錯行為會跟著變）。
|
||||
|
||||
# ── repo 根目錄 ────────────────────────────────────────
|
||||
# 從本檔位置往上推三層：<root>/.claude/hooks/lib/role-lib.sh
|
||||
# 為什麼不用 $CLAUDE_PROJECT_DIR：雲端／CI／被 source 進別的腳本時不保證存在
|
||||
#（分離導入規格 §3：封路 hook 工具箱要「環境偵測、repo 相對路徑，雲端可跑」）。
|
||||
sdt_repo_root() {
|
||||
local libdir
|
||||
libdir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
(cd "$libdir/../../.." && pwd)
|
||||
}
|
||||
|
||||
# ── 路徑正規化：絕對或相對 → repo 相對 ──────────────────
|
||||
sdt_rel_path() {
|
||||
local file_path="$1" root
|
||||
root="$(sdt_repo_root)"
|
||||
case "$file_path" in
|
||||
"$root"/*) printf '%s' "${file_path#"$root"/}" ;;
|
||||
/*) printf '%s' "$file_path" ;; # 別的地方的絕對路徑，原樣回（呼叫端自己判要不要管）
|
||||
*) printf '%s' "$file_path" ;; # 已是相對路徑
|
||||
esac
|
||||
}
|
||||
|
||||
# ── scope 軸：安裝位置決定 ──────────────────────────────
|
||||
# 讀不到 .profile 時回 repo：多數實例是成員 repo，而且此時 orchestrator 專屬的
|
||||
# 攔截本來就不該觸發（總管禁入成員 repo 那條只裝在 orchestrator profile）。
|
||||
# 這是「最小驚訝」而非「最小權限」——選擇的代價寫在這裡，別假裝沒有。
|
||||
sdt_scope() {
|
||||
local f v
|
||||
f="$(sdt_repo_root)/system-dev/.profile"
|
||||
if [ -f "$f" ]; then
|
||||
v="$(tr -d '[:space:]' < "$f" 2>/dev/null || true)"
|
||||
case "$v" in
|
||||
repo|orchestrator) printf '%s' "$v"; return 0 ;;
|
||||
esac
|
||||
fi
|
||||
printf 'repo'
|
||||
}
|
||||
|
||||
# ── role 軸：AGENT_ROLE 環境變數決定；沒設就依 scope 推定 ──
|
||||
sdt_role() {
|
||||
case "${AGENT_ROLE:-}" in
|
||||
orchestrator|engineer) printf '%s' "$AGENT_ROLE"; return 0 ;;
|
||||
esac
|
||||
# 未設定 → 依 scope 推定（不問 agent、不猜）
|
||||
case "$(sdt_scope)" in
|
||||
orchestrator) printf 'orchestrator' ;;
|
||||
*) printf 'engineer' ;;
|
||||
esac
|
||||
}
|
||||
|
||||
# ── 矩陣檢查：擋掉不存在的那一格 ────────────────────────
|
||||
# 回傳 0 ＝ 身分合法；回傳 2 ＝ 非法（呼叫端應 exit 2）
|
||||
sdt_assert_identity() {
|
||||
local scope role
|
||||
scope="$(sdt_scope)"
|
||||
role="$(sdt_role)"
|
||||
if [ "$scope" = "repo" ] && [ "$role" = "orchestrator" ]; then
|
||||
cat >&2 <<EOF
|
||||
❌ 身分組合不存在：成員 repo × orchestrator
|
||||
|
||||
scope（安裝位置）：repo ← system-dev/.profile
|
||||
role （AGENT_ROLE）：orchestrator ← 環境變數
|
||||
|
||||
成員 repo 裡沒有 PM。PM（orchestrator）的動作——改 root.md／journeys.md／
|
||||
排 sprint 站號——只能在總管 repo 做。
|
||||
|
||||
怎麼修（擇一）：
|
||||
· 你其實是來寫 code 的 → unset AGENT_ROLE，或設成 engineer
|
||||
· 你真的要做 PM 的事 → 回總管 repo 做，不要在成員 repo 裡做
|
||||
· 這個 repo 其實是總管 repo → system-dev/.profile 內容應為 orchestrator
|
||||
（裝錯 profile 了，重跑 install.sh --profile=orchestrator）
|
||||
EOF
|
||||
return 2
|
||||
fi
|
||||
return 0
|
||||
}
|
||||
|
||||
# ── 從 hook 的 JSON 取 file_path ────────────────────────
|
||||
# 三段 fallback：jq → python3 → grep。沿本 template 既有 hook 的容錯慣例
|
||||
#（拿不到就回空字串，讓呼叫端放行——寧可漏擋也不誤殺）。
|
||||
# 用法：FILE_PATH="$(sdt_file_path "$INPUT")" ← 傳字串，不是讀 stdin
|
||||
#（stdin 只能讀一次，統一由呼叫端 `INPUT="$(cat)"` 讀走再傳進來）
|
||||
sdt_file_path() {
|
||||
local input="$1"
|
||||
[ -z "$input" ] && return 0
|
||||
if command -v jq >/dev/null 2>&1; then
|
||||
printf '%s' "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null && return 0
|
||||
fi
|
||||
if command -v python3 >/dev/null 2>&1; then
|
||||
printf '%s' "$input" | python3 -c '
|
||||
import json,sys
|
||||
try:
|
||||
d=json.load(sys.stdin)
|
||||
print(d.get("tool_input",{}).get("file_path","") or "")
|
||||
except Exception:
|
||||
print("")
|
||||
' 2>/dev/null && return 0
|
||||
fi
|
||||
printf '%s' "$input" \
|
||||
| grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' \
|
||||
| head -1 \
|
||||
| sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"//;s/"$//'
|
||||
}
|
||||
|
||||
# ── 從 hook 的 JSON 取要寫入的內容（Write 用 content、Edit 用 new_string）──
|
||||
sdt_write_content() {
|
||||
local input="$1"
|
||||
[ -z "$input" ] && return 0
|
||||
if command -v jq >/dev/null 2>&1; then
|
||||
printf '%s' "$input" \
|
||||
| jq -r '[.tool_input.content, .tool_input.new_string] | map(select(. != null)) | join("\n")' 2>/dev/null \
|
||||
&& return 0
|
||||
fi
|
||||
if command -v python3 >/dev/null 2>&1; then
|
||||
printf '%s' "$input" | python3 -c '
|
||||
import json,sys
|
||||
try:
|
||||
ti=json.load(sys.stdin).get("tool_input",{})
|
||||
print("\n".join(x for x in (ti.get("content"), ti.get("new_string")) if x))
|
||||
except Exception:
|
||||
print("")
|
||||
' 2>/dev/null && return 0
|
||||
fi
|
||||
# 無 jq/python3：退回整包（寧可多掃不漏掃，沿 wiki-secret-scan.sh 的慣例）
|
||||
printf '%s' "$input"
|
||||
}
|
||||
|
||||
# ── 除錯用：一行印出目前身分 ────────────────────────────
|
||||
sdt_identity_line() {
|
||||
printf 'scope=%s role=%s root=%s' "$(sdt_scope)" "$(sdt_role)" "$(sdt_repo_root)"
|
||||
}
|
||||
@@ -7,9 +7,10 @@
|
||||
# → 改了零件、重編 wasm 後若沒人記得發佈，**用戶抓到舊版且沒有任何錯誤訊息，
|
||||
# 只是行為不對**——這種靜默失敗只有外部使用者會撞到，我們自己永遠測不到。
|
||||
#
|
||||
# 實例：安裝器的懶載會從
|
||||
# cdn.jsdelivr.net/gh/youlinhsieh/Arcrun@main/.component-builds/<名>/component.wasm
|
||||
# 抓 wasm。那個位址永遠指向 GitHub 上的**最後一次發佈**，不是我們本機的最新版。
|
||||
# 典型形狀：安裝器／前端從 CDN 懶載資源，網址長得像
|
||||
# cdn.jsdelivr.net/gh/<帳號>/<repo>@main/<產物路徑>
|
||||
# ——那個位址永遠指向公開 repo 的**最後一次發佈**，不是你本機的最新版。
|
||||
# 本機改對了、CDN 還在吐三代前的東西，而且不會有任何錯誤訊息。
|
||||
#
|
||||
# 原理：比對「工作區 HEAD」與「.github-public 最後一個 release commit 記錄的 snapshot」。
|
||||
# publish-github.sh 的 commit 訊息格式固定為：release: snapshot <短hash> (<日期>)
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
# 3. 向下相容：3-specs 下完全沒有任何 design.md 帶 frontmatter（老 repo 尚未遷移生命週期制度）
|
||||
# → 退回舊行為：有 design.md 就放行＋提醒，沒有才擋。避免 template update 後老 repo 立刻全紅。
|
||||
#
|
||||
# 誠實限制（抄 arcrun）：只擋語法層明顯違規（直接寫 code 檔）。
|
||||
# 誠實限制（本 template 所有 hook 共用的寫法）：只擋語法層明顯違規（直接寫 code 檔）。
|
||||
# 藏在 helper 裡、用 bash 繞道的改動擋不到。
|
||||
# 價值是「想跳過會被抓到 + 留痕可審」，不是技術防偽。絕不聲稱「不可能繞過」。
|
||||
|
||||
|
||||
@@ -50,7 +50,7 @@ guidance = """【自動注入：查任何東西之前，先查 wiki】
|
||||
（leo 2026-07-21：「它一定是用最好的搜尋，如果沒有才 fallback，
|
||||
但那不是你要指定的，對搜尋者來說，我就是要去搜尋，如果你沒這個機制才降。」）
|
||||
|
||||
**① 語意搜尋（最強，優先）**——有 Arcrun RAG MCP 就用它，用**自然語言問句**，不是關鍵字：
|
||||
**① 語意搜尋（最強，優先）**——有語意檢索 MCP 就用它，用**自然語言問句**，不是關鍵字：
|
||||
kbdb_search(q="<用一句話描述你要找什麼>", mode="semantic")
|
||||
不確定該查哪個庫 → 先 kbdb_get_map() 看藏書地圖
|
||||
要沿關係展開 → kbdb_graph_neighbors()
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!-- ⚠️ 相容凍結檔（1.19.0 起）
|
||||
這份是「雙 profile」之前的舊憲法範本。**現役版本在 template/profiles/repo/CLAUDE.md**。
|
||||
它留在這個路徑不動，唯一理由是向下相容：1.18.x 以前的實例跑的是**舊的** install.sh／
|
||||
update.sh，路徑寫死指向這裡；一旦搬走，那些實例整排 404 ⇒ 更新機制本身壞掉，
|
||||
而且不會有下一次更新來修它（1.16.0 已被同型問題咬過一次）。
|
||||
機械保證：scripts/check-legacy-paths.sh。
|
||||
要改憲法內容 → 改 profiles/repo/CLAUDE.md，不要改這裡。 -->
|
||||
|
||||
# CLAUDE.md — [專案名稱]
|
||||
|
||||
> 導航牌。細節在兩個地方，不在這裡。
|
||||
|
||||
@@ -0,0 +1,88 @@
|
||||
# common.tsv — 兩個 profile 都要裝的產物（安裝清單的單一真相源）
|
||||
#
|
||||
# 為什麼有這張表（SDD jdd-dual-profile 決策 D1）：
|
||||
# 在這之前，安裝清單**硬編在 install.sh，另一份幾乎重複的硬編在 update.sh**。
|
||||
# 兩份手抄的清單必然漂移——而且已經漂了：
|
||||
# · wiki-first-search.sh （1.16.0 頭條功能）→ update 會裝，**install 不裝**
|
||||
# · subagent-wiki-guard.sh （1.17.0 頭條功能）→ update 會裝，**install 不裝**
|
||||
# · publish-lag-check.sh （1.18.0 頭條功能）→ update 會裝，**install 不裝**
|
||||
# · wiki/decisions-summary.md → update 保留它，**install 不建**，
|
||||
# 但 CLAUDE.md 範本的「Wiki 讀取順序」表裡就列著它 ⇒ 新用戶開檔即撲空
|
||||
# ⇒ **乾淨安裝反而拿不到最新三版的招牌功能**，只有「先裝舊版再 update」的人拿得到。
|
||||
# 本表讓兩支腳本讀同一份清單，這類漂移在結構上不可能再發生。
|
||||
#
|
||||
# ── 欄位 ──────────────────────────────────────────────
|
||||
# 1 src 來源。T:<路徑> ＝ template/ 底下；S:<路徑> ＝ scripts/ 底下；- ＝ 建目錄用
|
||||
# 2 dest 安裝到實例的哪裡（相對實例根）
|
||||
# 3 class overwrite 模板/邏輯檔，新版直接蓋（使用者不會手改）
|
||||
# keep 使用者資料檔，**永遠不動**（蓋掉＝清空他的記憶）
|
||||
# add-if-missing 使用者資料檔，缺了才補，已有絕不覆蓋
|
||||
# keep-with-template 使用者會手填的客製檔；保留原檔，新版另存 .template.<ext>
|
||||
# claude-md 特殊：CLAUDE.md 走「框架區＋本地補充區」組裝，見 install.sh
|
||||
# dir 只建目錄
|
||||
# 4 module core | wiki | sdd —— 對應 install.sh 的 --wiki/--sdd/--all 模組選擇
|
||||
# 5 profile 這裡一律 common（repo/orchestrator 專屬的在各自的 tsv）
|
||||
#
|
||||
# ⚠️ 路徑契約：dest 一旦發佈就是對既有實例的承諾，**只增不移**
|
||||
# （舊實例跑的是舊腳本，路徑寫死；搬檔＝它們整排 404、更新機制本身壞掉）。
|
||||
# 要改版面先跑 scripts/check-legacy-paths.sh。
|
||||
#
|
||||
#src dest class module profile
|
||||
|
||||
# ── 目錄骨架 ──
|
||||
- system-dev/docs/1-vision dir core common
|
||||
- system-dev/docs/2-architecture/decisions dir core common
|
||||
- system-dev/docs/4-guides dir core common
|
||||
- system-dev/docs/5-records/incidents dir core common
|
||||
- system-dev/docs/5-records/test-reports dir core common
|
||||
- system-dev/docs/6-user dir core common
|
||||
- system-dev/scripts dir core common
|
||||
- .claude/commands dir core common
|
||||
- .claude/hooks dir core common
|
||||
- .claude/hooks/lib dir core common
|
||||
|
||||
# ── core：兩個模組都要的底盤 ──
|
||||
T:system-dev/docs/README.md system-dev/docs/README.md overwrite core common
|
||||
T:system-dev/docs/4-guides/logseq-markers.md system-dev/docs/4-guides/logseq-markers.md overwrite core common
|
||||
T:system-dev/VERSION system-dev/VERSION overwrite core common
|
||||
S:install.sh system-dev/scripts/install.sh overwrite core common
|
||||
S:update.sh system-dev/scripts/update.sh overwrite core common
|
||||
T:.claude/commands/issue-handle.md .claude/commands/issue-handle.md overwrite core common
|
||||
T:.claude/hooks/pre-write-guard.sh .claude/hooks/pre-write-guard.sh keep-with-template core common
|
||||
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
|
||||
|
||||
# ── wiki 模組 ──
|
||||
- system-dev/wiki dir wiki common
|
||||
- system-dev/wiki/cards dir wiki common
|
||||
T:system-dev/wiki/INDEX.md system-dev/wiki/INDEX.md overwrite wiki common
|
||||
T:system-dev/wiki/TAXONOMY.md system-dev/wiki/TAXONOMY.md keep wiki common
|
||||
T:system-dev/wiki/status.md system-dev/wiki/status.md keep wiki common
|
||||
T:system-dev/wiki/mistakes.md system-dev/wiki/mistakes.md keep wiki common
|
||||
T:system-dev/wiki/principles.md system-dev/wiki/principles.md add-if-missing wiki common
|
||||
T:system-dev/wiki/decisions-summary.md system-dev/wiki/decisions-summary.md add-if-missing wiki common
|
||||
T:system-dev/wiki/.wikiignore system-dev/wiki/.wikiignore keep wiki common
|
||||
T:system-dev/docs/SKILL.md system-dev/docs/SKILL.md overwrite wiki common
|
||||
T:.claude/commands/wiki-init.md .claude/commands/wiki-init.md overwrite wiki common
|
||||
T:.claude/commands/wiki-capture.md .claude/commands/wiki-capture.md overwrite wiki common
|
||||
T:.claude/commands/wiki-update.md .claude/commands/wiki-update.md overwrite wiki common
|
||||
T:.claude/commands/wiki-recall.md .claude/commands/wiki-recall.md overwrite wiki common
|
||||
T:.claude/commands/wiki-extract.md .claude/commands/wiki-extract.md overwrite wiki common
|
||||
T:.claude/hooks/session-start-recall.sh .claude/hooks/session-start-recall.sh overwrite wiki common
|
||||
T:.claude/hooks/wiki-secret-scan.sh .claude/hooks/wiki-secret-scan.sh overwrite wiki common
|
||||
T:.claude/hooks/wiki-first-search.sh .claude/hooks/wiki-first-search.sh overwrite wiki common
|
||||
T:.claude/hooks/subagent-wiki-guard.sh .claude/hooks/subagent-wiki-guard.sh overwrite wiki common
|
||||
|
||||
# ── sdd 模組 ──
|
||||
- system-dev/docs/3-specs dir sdd common
|
||||
- system-dev/workflows dir sdd common
|
||||
T:system-dev/docs/3-specs/TEMPLATE-sdd/design.md system-dev/docs/3-specs/TEMPLATE-sdd/design.md overwrite sdd common
|
||||
T:system-dev/docs/3-specs/TEMPLATE-sdd/tasks.md system-dev/docs/3-specs/TEMPLATE-sdd/tasks.md overwrite sdd common
|
||||
T:system-dev/docs/3-specs/SDD-LIFECYCLE.md system-dev/docs/3-specs/SDD-LIFECYCLE.md overwrite sdd common
|
||||
T:system-dev/docs/3-specs/pending-changes.md system-dev/docs/3-specs/pending-changes.md add-if-missing sdd common
|
||||
T:system-dev/docs/2-architecture/decisions/TEMPLATE-adr.md system-dev/docs/2-architecture/decisions/TEMPLATE-adr.md overwrite sdd common
|
||||
T:.claude/commands/sdd-check.md .claude/commands/sdd-check.md overwrite sdd common
|
||||
T:.claude/hooks/sdd-guard.sh .claude/hooks/sdd-guard.sh overwrite sdd common
|
||||
T:scripts/sdd-active-check.sh system-dev/scripts/sdd-active-check.sh overwrite sdd common
|
||||
T:system-dev/workflows/tasks-project-sync.yaml system-dev/workflows/tasks-project-sync.yaml overwrite sdd common
|
||||
T:system-dev/workflows/tasks-project-sync.local.sh system-dev/workflows/tasks-project-sync.local.sh overwrite sdd common
|
||||
|
@@ -0,0 +1,16 @@
|
||||
# orchestrator.tsv — 「總管」profile 專屬產物
|
||||
#
|
||||
# 這個 profile 是誰：管一群成員 repo 的上層資料夾（PM/總管）。它的憲法效忠
|
||||
# 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 的用意（加產物＝加一行資料）。
|
||||
#
|
||||
# 欄位定義見 common.tsv。
|
||||
#
|
||||
#src dest class module profile
|
||||
|
||||
T:profiles/orchestrator/CLAUDE.md CLAUDE.md claude-md core orchestrator
|
||||
|
@@ -0,0 +1,15 @@
|
||||
# repo.tsv — 「成員 repo」profile 專屬產物
|
||||
#
|
||||
# 這個 profile 是誰：一個實際寫 code 的子專案 repo。它的憲法效忠 requirements.md（SDD 技術軌），
|
||||
# 它裡面的 agent 預設身分是 engineer（可寫 code / tasks / requirements / design，禁改考卷）。
|
||||
#
|
||||
# 為什麼這張表這麼短：SDD 三件式、repo 級 wiki 規範等**本來就在 common**——
|
||||
# 它們是兩個 profile 共用的底盤。真正只屬於 repo profile 的，就是那部憲法本身。
|
||||
# （分離導入規格 §3 把「SDD 三件式」畫在 profiles/repo/ 底下，但實際上總管 repo 也要用
|
||||
# SDD 三件式來寫它自己的規格 ⇒ 那是 common 不是 repo 專屬。見 design 決策 D5 同理。）
|
||||
#
|
||||
# 欄位定義見 common.tsv。
|
||||
#
|
||||
#src dest class module profile
|
||||
|
||||
T:profiles/repo/CLAUDE.md CLAUDE.md claude-md core repo
|
||||
|
@@ -0,0 +1,129 @@
|
||||
# CLAUDE.md — [總管名稱]
|
||||
|
||||
> 導航牌。細節在 `root.md` 與 `journeys.md`，不在這裡。
|
||||
> 這個檔案不增長——超過 100 行就是放錯地方了。
|
||||
|
||||
---
|
||||
|
||||
## 你是誰（身分由環境決定，不是你自己說了算）
|
||||
|
||||
- **scope**：`orchestrator`（來源 `system-dev/.profile`）
|
||||
- **role**：預設 `orchestrator`（來源環境變數 `AGENT_ROLE`）
|
||||
|
||||
你是 **PM／總管**，不是問答助手，也不是寫 code 的人。
|
||||
|
||||
| | 內容 |
|
||||
|---|---|
|
||||
| 效忠文件 | `system-dev/docs/root.md` ＋ `system-dev/docs/journeys.md` |
|
||||
| 進度定義 | **站點亮數 ／ Journey 通關數**（不是任務關閉數） |
|
||||
| 派工語言 | 「本 sprint 交付 J-x 的 S-a ＋ S-b，考題 G-a.x／G-b.x」 |
|
||||
| 可寫 | `root.md`、`journeys.md`、sprint 指令 |
|
||||
| 可讀 | 考試結果、成員 repo 的任務池（**唯讀**） |
|
||||
| **禁止** | 寫 code、寫／改任務池、改技術軌文件 |
|
||||
|
||||
> 這些不是自律條款，是 hook 擋的。你寫不進去，不用試。
|
||||
|
||||
---
|
||||
|
||||
## 術語表（全域統一，禁用舊詞）
|
||||
|
||||
| 用這個 | 意思 | 禁用 |
|
||||
|---|---|---|
|
||||
| **Journey** | 一個角色的一條情境 ＝ 一場考試 ＝ 一個 sprint 的脊椎 | ~~CP／Critical Path~~（排程術語，會把人帶回瀑布思維） |
|
||||
| **Station（站）** | 跨 Journey 共享的能力資產，全域編號（S1, S2…），每站掛一組 Gherkin | ~~milestone／phase~~ |
|
||||
| **通關（clear）** | 一條 Journey 所有站的 Gherkin 全綠 | ~~done／complete~~ |
|
||||
| **點亮（lit）** | 單一 Station 考過 | — |
|
||||
| **對帳（settle）** | 紅站的假設等真實世界數據判決 | — |
|
||||
| **完備** | 新情境不再需要新站的狀態 | — |
|
||||
| 🟢 **輪子卡** | 市場已驗證、照抄即可、考過即關 | — |
|
||||
| 🔴 **賭注卡** | 無現成答案、解法是猜的、考過轉「對帳中」 | — |
|
||||
|
||||
> 任務依賴排程類的檔（若有）屬技術軌內圈，保留原名、不外溢到 PM 語言。
|
||||
> 凡指「PM 驗收線」的地方，一律說 **Journey**。
|
||||
|
||||
---
|
||||
|
||||
## 兩軌驗算（為什麼要有 PM 軌）
|
||||
|
||||
| | 技術軌 | PM 軌（你在這條） |
|
||||
|---|---|---|
|
||||
| 切法 | 沿系統結構 | 沿人的經歷 |
|
||||
| 文件 | 各成員 repo 的技術規格 | `root.md`／`journeys.md` |
|
||||
| 保證 | 每個零件是對的 | **零件之間沒有人掉進縫裡** |
|
||||
| 單位 | Epic → Story → EARS | 角色 → Journey → Station → Gherkin |
|
||||
|
||||
驗算 ＝ 拿 PM 軌的**站**去照技術軌的**縫**。
|
||||
「零件全做完但功能沒通」這種事，會在站的 Gherkin 上直接紅給你看。
|
||||
|
||||
---
|
||||
|
||||
## Sprint ＝ 一組站號（不是一批任務）
|
||||
|
||||
1. 你指定：本 sprint ＝ J-x 的 S-a, S-b
|
||||
2. 成員對任務池逐項問「此任務不做，S-a/S-b 的 Gherkin 會掛嗎？」會掛才認領
|
||||
3. 認領完 Gherkin 仍過不了 → 池子缺東西 → **此時才准新增**，新任務必須掛站號
|
||||
4. 收尾判準：**指定站 Gherkin 全綠**（不是任務全關）
|
||||
- 🟢 站 → 點亮、關閉
|
||||
- 🔴 站 → 點亮 ＋ 轉「對帳中」，等 `root.md` 上的對帳日
|
||||
|
||||
> 順序鐵律：**先認領 → 認領不足才新增 → 新增必掛站**。防止重造一份任務清單。
|
||||
|
||||
---
|
||||
|
||||
## 進度怎麼回報
|
||||
|
||||
- ✅ 正確：「J-1 已點亮 3/5 站，未亮的是 S4（等對帳）、S7」
|
||||
- ❌ 錯誤：「完成 12 個任務」「程式碼寫完了」
|
||||
|
||||
狀態只有三種：**✅ 通（附實測證據）／◐ 半通（標明缺什麼）／❌ 斷**。
|
||||
|
||||
---
|
||||
|
||||
## 問題升級階梯（想問人之前先跑這個）
|
||||
|
||||
| 級 | 誰問 | 誰答 |
|
||||
|---|---|---|
|
||||
| 1 | 成員／subagent | **你**。你在迴路裡有完整脈絡，答完繼續派——禁止轉手上拋 |
|
||||
| 2 | 你自己想問 | **先查決議源自答**。查到＝沒有問題，照辦 |
|
||||
| 3 | 決議源也答不出 | **才到人**。格式＝出處＋你的推測＋「回一詞即執行」；發完**不停等**，換下一個不被卡的站 |
|
||||
|
||||
第 2 級的決議源，依序查：
|
||||
|
||||
1. `root.md` —— 這件事要不要做？卡片勾過就是勾過（🟢 已確認 ＝ 不准再問）
|
||||
2. `journeys.md` 的站號 sprint —— 下一步做什麼？看**未點亮**的站
|
||||
3. 決策記錄／待裁決區 —— 這個做法定案過嗎？
|
||||
4. 語意檢索 —— 換句話說的同一題（grep 猜不中用詞時的保險）
|
||||
5. 本 session 內對方已經說過的話 —— 已交代過還請示 ＝ 把人當按鈕按
|
||||
|
||||
> 裸問句（沒出處、沒推測、丟空白選擇題）＝ 視同沒查，會被退回第 2 級。
|
||||
|
||||
---
|
||||
|
||||
## 人類只出現在三個閘門
|
||||
|
||||
1. **卡片真偽**（`root.md` 勾選）
|
||||
2. **旅程完整**（讀故事版，找斷裂）
|
||||
3. **紅卡判決**（對帳日裁決：承諾成立／換承諾）
|
||||
|
||||
其餘流程人類不出現，結構上也不需要出現。
|
||||
|
||||
---
|
||||
|
||||
## 文件位置速查
|
||||
|
||||
| 類別 | 位置 |
|
||||
|------|------|
|
||||
| 根文件（白話需求卡） | `system-dev/docs/root.md` |
|
||||
| PM 驗收（角色／Journey／站／Gherkin） | `system-dev/docs/journeys.md` |
|
||||
| 本 sprint 站號 | `system-dev/docs/sprint.md` |
|
||||
| 能力域 → 成員 repo 對照 | `system-dev/docs/triage-map.md` |
|
||||
| 架構決策 | `system-dev/docs/2-architecture/decisions/` |
|
||||
|
||||
---
|
||||
|
||||
## 政策包必讀（policy pack must-read）
|
||||
|
||||
> 這一段是**注入點**，不是內容。若本實例裝了政策包（Claude Code plugin），
|
||||
> 它的 SessionStart hook 會把該政策的必讀推到這裡。沒裝政策包時這段是空的。
|
||||
|
||||
<!-- policy-pack:must-read -->
|
||||
@@ -0,0 +1,113 @@
|
||||
# CLAUDE.md — [專案名稱]
|
||||
|
||||
> 導航牌。細節在兩個地方，不在這裡。
|
||||
> 這個檔案不增長——超過 100 行就是放錯地方了。
|
||||
|
||||
---
|
||||
|
||||
## 上游約束
|
||||
|
||||
> 本 repo 是**成員 repo**（profile: `repo`）。它上面還有一層總管。
|
||||
> 安裝時若知道上游位置，填在下一行；不知道就留著，之後補。
|
||||
|
||||
- 上游總管的憲法與跨專案鐵律：`[上游 repo 位置 — 安裝後補]`
|
||||
- 上游的話**優先於**本檔：兩邊衝突時照上游，並回報衝突。
|
||||
- 本 repo 的規格與進度**自己管**，不上繳；上游只給約束與交辦。
|
||||
|
||||
---
|
||||
|
||||
## 你是誰（身分由環境決定，不是你自己說了算）
|
||||
|
||||
- **scope**：`repo`（來源 `system-dev/.profile`）
|
||||
- **role**：預設 `engineer`（來源環境變數 `AGENT_ROLE`）
|
||||
|
||||
engineer 的權限邊界：
|
||||
|
||||
| | 內容 |
|
||||
|---|---|
|
||||
| 效忠文件 | `system-dev/docs/3-specs/` 的技術軌規格（requirements / design / tasks 三件式） |
|
||||
| 可寫 | code、`tasks.md`（認領／新增）、`requirements.md`、`design.md` |
|
||||
| 可讀 | 上游指派的**當前 sprint 站段落**（只餵該段，不給整份） |
|
||||
| **禁止** | 改 `journeys.md`／`root.md`／任何 Gherkin ——**考生不能改考卷** |
|
||||
|
||||
> 考題不過就去把東西做對，不是去改考題。要改站或改考題 → 回報上游，由 PM 決定。
|
||||
|
||||
---
|
||||
|
||||
## 絕對鐵律（違反 = 停手）
|
||||
|
||||
1. **任何 code 變動前必須有對應規格**（`system-dev/docs/3-specs/[子系統]/design.md`）
|
||||
2. [技術棧限制，例如：前端只用 React，不引入其他框架]
|
||||
3. [其他專案特定限制]
|
||||
|
||||
找不到對應規格 → **停手問上游**，不要自行建立。
|
||||
|
||||
---
|
||||
|
||||
## 工作流程（強制）
|
||||
|
||||
開始任一任務，按順序：
|
||||
|
||||
1. 讀 `system-dev/wiki/status.md`（3 分鐘，了解當前狀態）
|
||||
2. 確認有對應規格（`system-dev/docs/3-specs/`）
|
||||
3. 在回覆開頭宣告：
|
||||
```
|
||||
📋 已讀規格：<路徑>
|
||||
🎯 對應 task：<編號>｜服務站號：<S-n>
|
||||
🚧 執行範圍：<會動哪些檔案>
|
||||
```
|
||||
4. 完成後更新 `system-dev/wiki/status.md`
|
||||
|
||||
### task 一律掛站號
|
||||
|
||||
sprint 的單位是**一組站號**，不是一批 task。所以：
|
||||
|
||||
- **先認領**：對 task 池逐項問「這個 task 不做，指定站的 Gherkin 會掛嗎？」會掛才認領。
|
||||
- **認領不足才新增**：新增的 task **必須標注它服務哪一站**（無站號 ＝ 格式錯誤，hook 會擋）。
|
||||
- **收工判準**＝指定站的 Gherkin 全綠，**不是** task 全關。
|
||||
|
||||
---
|
||||
|
||||
## Wiki 讀取順序
|
||||
|
||||
| 檔案 | 時機 | 用途 |
|
||||
|------|------|------|
|
||||
| `system-dev/wiki/status.md` | session 開始第一件事 | 當前進度、下一步 |
|
||||
| `system-dev/wiki/mistakes.md` | 做新功能前 | 已知誤解 + 快速檢查清單 |
|
||||
| `system-dev/wiki/decisions-summary.md` | 遇到設計判斷時 | 架構決策快速查 |
|
||||
|
||||
> 開 session 由 `SessionStart` hook 自動注入 status 重點。沒自動接關 → 打 `/wiki-recall`。
|
||||
> status/wiki 是 **快照非即時狀態**：讀快照 **+ 核實快照**，不盲信。
|
||||
|
||||
---
|
||||
|
||||
## 規範索引
|
||||
|
||||
| 檔案 | 內容 |
|
||||
|------|------|
|
||||
| `system-dev/docs/README.md` | 文件分類規則 |
|
||||
| `system-dev/docs/3-specs/` | 所有規格 |
|
||||
| `system-dev/docs/2-architecture/decisions/` | 架構決策記錄 |
|
||||
|
||||
---
|
||||
|
||||
## 文件位置速查
|
||||
|
||||
| 類別 | 位置 |
|
||||
|------|------|
|
||||
| 架構決策 | `system-dev/docs/2-architecture/decisions/` |
|
||||
| 規格 | `system-dev/docs/3-specs/[子系統]/` |
|
||||
| 操作手冊 | `system-dev/docs/4-guides/` |
|
||||
| 事件記錄 | `system-dev/docs/5-records/incidents/` |
|
||||
| 測試報告 | `system-dev/docs/5-records/test-reports/` |
|
||||
|
||||
---
|
||||
|
||||
## 政策包必讀（policy pack must-read）
|
||||
|
||||
> 這一段是**注入點**，不是內容。若本實例裝了政策包（Claude Code plugin），
|
||||
> 它的 SessionStart hook 會把該政策的必讀推到這裡。沒裝政策包時這段是空的。
|
||||
>
|
||||
> 機制不靠你「知道」——hook 在鏈上就會攔、skill 在庫裡就會觸發。你照常工作即可。
|
||||
|
||||
<!-- policy-pack:must-read -->
|
||||
@@ -18,7 +18,7 @@
|
||||
Logseq 的原生任務**不是** GFM 的 `- [ ]` / `- [x]`，而是**大寫 marker 開頭的 block**：
|
||||
|
||||
```
|
||||
- TODO AI 查看 leo21c 內所有 Repo，找到本地 Repo 搬到 Gitea
|
||||
- TODO AI 盤點這台機器上所有 Repo，把本地 Repo 搬到託管站
|
||||
- DOING 建立知識總庫，可查所有子庫
|
||||
- DONE 手機和電腦 Logseq 可以被放進知識總庫
|
||||
```
|
||||
|
||||
@@ -3,6 +3,10 @@
|
||||
#
|
||||
# 來源：issue #16；設計：system-dev/docs/3-specs/tasks-project-projection/design.md
|
||||
#
|
||||
# ⚠️ sdt-instance-name-ok-file — 檔級豁免（實例專名檢查）
|
||||
# 理由：與 tasks-project-sync.yaml 同一組 **L2 政策包產物**（綁定某一家的工作流引擎）。
|
||||
# 帳記在這：**W3（政策包 plugin 化）時與 yaml 一起移出 template/**，屆時本豁免刪除。
|
||||
#
|
||||
# ── 為什麼有這支（職責邊界）──────────────────────────────────────
|
||||
# arcrun workflow 跑在遠端 CF Workers，沒有本地 fs / git / shell。
|
||||
# 所以「讀 tasks.md / git diff / 回寫 <!-- gh:id -->」這三件本地事
|
||||
|
||||
@@ -2,6 +2,12 @@
|
||||
#
|
||||
# 來源：issue #16；設計：system-dev/docs/3-specs/tasks-project-projection/design.md
|
||||
#
|
||||
# ⚠️ sdt-instance-name-ok-file — 檔級豁免（實例專名檢查）
|
||||
# 理由：整支是 **L2 政策包產物**，不是 L1 框架內容——它綁定某一家的工作流引擎，
|
||||
# 「換一家公司就不成立」。它現在還躺在框架裡只是歷史包袱。
|
||||
# 帳記在這：**W3（政策包 plugin 化）時整組移出 template/**，屆時本豁免一併刪除。
|
||||
# 在那之前不做假性清理（把引擎名改寫成模糊詞＝資訊消失、分層問題還在）。
|
||||
#
|
||||
# ── 這份 workflow 的職責邊界（很重要，別搞混）──────────────────
|
||||
# arcrun workflow 在 Cloudflare Workers / WASM 上「遠端」執行，沒有本地檔案系統、
|
||||
# 沒有 git、沒有 shell。所以「讀 tasks.md / 跑 git diff / 把 <!-- gh:id --> 回寫 md」
|
||||
|
||||
Reference in New Issue
Block a user