feat: 安裝結構收進 system-dev/(不污染用戶根目錄)+ 舊版自動遷移 + bump 1.9.0

工具產物原散在用戶根目錄(docs 七層、scripts),又把 wiki/VERSION 寄生在 CC 原生
.claude/ 裡,用戶分不清哪個 docs 是工具的。這版徹底收斂:除 .claude/(settings/
commands/hooks)與 CLAUDE.md 留根,工具所有資料收進 system-dev/。

對應 SDD: system-dev/docs/3-specs/install-layout/(內部記錄,依原則不推)。

- 新結構 system-dev/{VERSION,wiki/,docs/,scripts/};.claude/ 只剩 CC 機制檔
- wiki 改寫產物落點正式化:install 建 system-dev/wiki/cards/(.gitkeep)
- docs 雙語義拆開:工具文件→system-dev/docs/;用戶 raw source 維持原處只讀
- scripts 一開始就裝進 system-dev/scripts/
- 舊版自動遷移雙保險:update.sh 冪等搬移(wiki 含 .git、docs 白名單)
  + session-start hook 偵測舊結構未遷移時提示(low-code 用戶兜底)
- wiki-secret-scan 觸發路徑改 system-dev/wiki/**(否則新結構防護失效)
- 全套路徑引用同步:CLAUDE/SKILL/wiki-*/sdd-*/hooks/INDEX/README(中英)
- 沙盒驗證:遷移含 .git commit 一致、冪等、用戶自填 docs 保留;全 bash -n 過

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

scripts/update.sh

@@ -30,11 +30,17 @@ UPDATED=()
 KEPT=()
 NEW=()
 TEMPLATED=()
+MIGRATED=()
 
 # ── 版本比對：先看本機 vs 遠端，給使用者「值不值得更新」的判斷 ──
+# VERSION 新位置在 system-dev/，舊位置在 .claude/（1.8.x 以前）。優先讀新、回退舊。
 LOCAL_VER="$(tn '(未知)' '(unknown)')"
-[ -f ".claude/VERSION" ] && LOCAL_VER="$(tr -d '[:space:]' < .claude/VERSION)"
-REMOTE_VER="$(curl -sSL "$TEMPLATE_URL/.claude/VERSION" 2>/dev/null | tr -d '[:space:]' || echo '')"
+if [ -f "system-dev/VERSION" ]; then
+  LOCAL_VER="$(tr -d '[:space:]' < system-dev/VERSION)"
+elif [ -f ".claude/VERSION" ]; then
+  LOCAL_VER="$(tr -d '[:space:]' < .claude/VERSION)"
+fi
+REMOTE_VER="$(curl -sSL "$TEMPLATE_URL/system-dev/VERSION" 2>/dev/null | tr -d '[:space:]' || echo '')"
 
 echo ""
 echo "🔄 system-dev-template updater"
@@ -58,6 +64,53 @@ if [ "$LOCAL_VER" = "$REMOTE_VER" ]; then
   echo ""
 fi
 
+# ── 結構遷移（1.9.0）：舊版把 wiki/VERSION 放 .claude/、工具 docs 放根 docs/ ──
+# 新版一律收進 system-dev/。這裡冪等遷移：偵測舊位置 → 搬到 system-dev/，已搬過則略過。
+# 必須在「模組偵測」之前跑（偵測靠目錄存在與否判斷，搬完才看得到新位置）。
+#
+# 安全原則：
+#   - wiki 整包搬（含 cards/ 與可能的 wiki/.git），用 mv 保留內含 .git。
+#   - docs 只搬「工具自己鋪的白名單」子目錄；用戶自填在 docs/ 的其他內容一律不動。
+#   - 目的地已存在同名 → 不覆蓋（保留用戶在新位置的東西），略過該項。
+migrate_dir() {  # $1=舊路徑 $2=新路徑
+  local from="$1" to="$2"
+  [ -e "$from" ] || return 0          # 舊的不存在 → 無需遷移
+  if [ -e "$to" ]; then
+    return 0                          # 新的已存在 → 冪等略過，不覆蓋
+  fi
+  mkdir -p "$(dirname "$to")"
+  if mv "$from" "$to" 2>/dev/null; then
+    MIGRATED+=("$from → $to")
+  fi
+}
+
+# 任一舊位置還在 → 需要遷移（遷移本身冪等：已搬的項目會被 migrate_dir 略過）。
+NEEDS_MIGRATE="no"
+if [ -d ".claude/wiki" ] || [ -f ".claude/VERSION" ] \
+   || [ -d "docs/3-specs" ] || [ -f "docs/SKILL.md" ] || [ -f "docs/README.md" ]; then
+  NEEDS_MIGRATE="yes"
+fi
+
+if [ "$NEEDS_MIGRATE" = "yes" ]; then
+  t "🔧 偵測到舊版結構，遷移到 system-dev/ …" "🔧 Old layout detected — migrating into system-dev/ …"
+  mkdir -p system-dev
+
+  # wiki（含 cards/ 與內含的 .git）整包搬
+  migrate_dir ".claude/wiki" "system-dev/wiki"
+  # 工具版號
+  migrate_dir ".claude/VERSION" "system-dev/VERSION"
+  # 工具文件白名單（只搬工具鋪的，用戶自填的 docs 內容不動）
+  migrate_dir "docs/SKILL.md"            "system-dev/docs/SKILL.md"
+  migrate_dir "docs/README.md"           "system-dev/docs/README.md"
+  migrate_dir "docs/1-vision"            "system-dev/docs/1-vision"
+  migrate_dir "docs/2-architecture"      "system-dev/docs/2-architecture"
+  migrate_dir "docs/3-specs"             "system-dev/docs/3-specs"
+  migrate_dir "docs/4-guides"            "system-dev/docs/4-guides"
+  migrate_dir "docs/5-records"           "system-dev/docs/5-records"
+  migrate_dir "docs/6-user"             "system-dev/docs/6-user"
+  echo ""
+fi
+
 # ── 工具函式 ───────────────────────────────────────
 # 覆蓋更新：模板/邏輯檔，無條件抓最新版蓋掉。
 update_file() {
@@ -114,10 +167,11 @@ keep_with_template() {
 }
 
 # ── 偵測已安裝哪些模組（依現有檔案判斷，更新只動已裝的）──
+# 遷移已在上面跑完，這裡看新位置 system-dev/。
 HAS_WIKI=false
 HAS_SDD=false
-[ -d ".claude/wiki" ] && HAS_WIKI=true
-if [ -f ".claude/hooks/sdd-guard.sh" ] || [ -d "docs/3-specs/TEMPLATE-sdd" ]; then HAS_SDD=true; fi
+[ -d "system-dev/wiki" ] && HAS_WIKI=true
+if [ -f ".claude/hooks/sdd-guard.sh" ] || [ -d "system-dev/docs/3-specs/TEMPLATE-sdd" ]; then HAS_SDD=true; fi
 
 t "📦 偵測到已安裝模組：" "📦 Detected installed modules:"
 $HAS_WIKI && echo "   • LLM Wiki"
@@ -136,11 +190,11 @@ keep_with_template ".claude/hooks/pre-write-guard.sh" "$TEMPLATE_URL/.claude/hoo
 # ── 模板/邏輯檔：覆蓋更新 ──────────────────────────
 # 共用 hook 與指引
 update_file ".claude/commands/issue-handle.md" "$TEMPLATE_URL/.claude/commands/issue-handle.md"
-update_file ".claude/VERSION"                  "$TEMPLATE_URL/.claude/VERSION"
+update_file "system-dev/VERSION"               "$TEMPLATE_URL/system-dev/VERSION"
 
 if $HAS_WIKI; then
-  # wiki 的「邏輯檔」：導航與 hooks，可覆蓋
-  update_file ".claude/wiki/INDEX.md"                    "$TEMPLATE_URL/.claude/wiki/INDEX.md"
+  # 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"
   update_file ".claude/commands/wiki-init.md"           "$TEMPLATE_URL/.claude/commands/wiki-init.md"
@@ -148,31 +202,31 @@ if $HAS_WIKI; then
   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"
   # Cowork（claude.ai）的 wiki 整理 skill：規則檔，可覆蓋
-  update_file "docs/SKILL.md"                           "$TEMPLATE_URL/docs/SKILL.md"
+  update_file "system-dev/docs/SKILL.md"                "$TEMPLATE_URL/system-dev/docs/SKILL.md"
 
   # wiki 的「使用者資料」：絕不碰
-  keep_file ".claude/wiki/status.md"
-  keep_file ".claude/wiki/mistakes.md"
-  keep_file ".claude/wiki/decisions-summary.md"
-  keep_file ".claude/wiki/TAXONOMY.md"
-  keep_file ".claude/wiki/.wikiignore"
+  keep_file "system-dev/wiki/status.md"
+  keep_file "system-dev/wiki/mistakes.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 "docs/3-specs/TEMPLATE-sdd/design.md"               "$TEMPLATE_URL/docs/3-specs/TEMPLATE-sdd/design.md"
-  update_file "docs/3-specs/TEMPLATE-sdd/tasks.md"                "$TEMPLATE_URL/docs/3-specs/TEMPLATE-sdd/tasks.md"
-  update_file "docs/2-architecture/decisions/TEMPLATE-adr.md"     "$TEMPLATE_URL/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"
+  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"
 fi
 
-# ── 自我更新：把最新的 update.sh 也抓下來（含 install.sh）──
-# 這兩支在 main/scripts/ 下，不在 template/。
-update_file "scripts/update.sh"  "$REPO_RAW/scripts/update.sh"
-update_file "scripts/install.sh" "$REPO_RAW/scripts/install.sh"
+# ── 自我更新：把最新的 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"
+update_file "system-dev/scripts/install.sh" "$REPO_RAW/scripts/install.sh"
 
-chmod +x .claude/hooks/*.sh scripts/*.sh 2>/dev/null || true
+chmod +x .claude/hooks/*.sh system-dev/scripts/*.sh 2>/dev/null || true
 
 # ── 使用者資料檔：絕不碰，但提醒「設定可能有新欄位要手動補」──
 keep_file ".claude/settings.json"
@@ -181,6 +235,11 @@ keep_file "CLAUDE.md"
 # ── 結果輸出 ───────────────────────────────────────
 echo ""
 echo "─────────────────────────────────"
+if [ ${#MIGRATED[@]} -gt 0 ]; then
+  echo ""
+  t "📦 結構遷移（已收進 system-dev/）：" "📦 Layout migrated (moved into system-dev/):"
+  for f in "${MIGRATED[@]}"; do echo "   ⇒ $f"; done
+fi
 if [ ${#NEW[@]} -gt 0 ]; then
   echo ""
   t "🆕 新功能（舊版沒有，已加入）：" "🆕 New features (absent in the old version, now added):"
@@ -229,6 +288,6 @@ fi
 
 echo ""
 t "🚀 更新完成：${LOCAL_VER} → ${REMOTE_VER}" "🚀 Update complete: ${LOCAL_VER} → ${REMOTE_VER}"
-t "   下次更新直接跑：bash scripts/update.sh" "   Next time, just run: bash scripts/update.sh"
+t "   下次更新直接跑：bash system-dev/scripts/update.sh" "   Next time, just run: bash system-dev/scripts/update.sh"
 t "   改了什麼看：CHANGELOG.md" "   See what changed: CHANGELOG.md"
 echo ""