universal-dev-standards 5.13.3 → 5.15.1

package/bundled/locales/zh-TW/skills/deploy-assistant/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: deploy
+source: ../../../../skills/deploy-assistant/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-05-28
+scope: universal
+description: |
+  [UDS] 無 CI/CD 平台環境下的可靠部署指引（不依賴 GitHub Actions / GitLab CI）。
+  Use when: deploying to VPS, air-gapped servers, or environments without CI/CD infrastructure.
+  Keywords: deployment, no-cicd, shell script, blue-green, smoke test, rollback, 無CI/CD, 部署.
+allowed-tools: Read, Bash(cat VERSION:*), Bash(git describe:*), Bash(which nginx:*), Bash(which rsync:*)
+argument-hint: "[專案類型: node/python/docker/go]"
+---
+
+# 無 CI/CD 部署助手
+
+> **語言**: [English](../../../../skills/deploy-assistant/SKILL.md) | 繁體中文
+
+引導無 CI/CD 平台環境下的可靠部署，採用三層架構：防錯、驗證、快速回復。
+
+## 三層部署架構
+
+```
+Layer 1：防止錯誤部署            Layer 2：驗證正確性             Layer 3：快速回復
+  set -euo pipefail                Smoke Test + /health           Blue-Green 切換
+  版本 tag 強制                    版本號比對                     rollback.sh < 30s
+  deploy.lock 並發守衛             驗證失敗自動回滾
+```
+
+## 引導式問答
+
+| 問題 | 選項 | 影響 |
+|------|------|------|
+| 專案類型 | node / python / go / docker | 建置指令 |
+| 部署目標 | SSH+rsync / Docker Compose | 傳輸方式 |
+| Blue-Green 支援 | yes / no | rollback.sh 是否生成 |
+| 健康檢查 URL | URL 輸入 | verify.sh 目標 |
+| 版本來源 | VERSION 檔 / package.json / git tag | 版本比對邏輯 |
+
+## 生成的腳本組
+
+### deploy.sh — 主要部署腳本
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+LOCK_FILE="/tmp/deploy.lock"
+trap "rm -f $LOCK_FILE" EXIT
+
+# 防並發守衛
+if [ -f "$LOCK_FILE" ]; then
+  echo "❌ 已有部署進行中（PID: $(cat $LOCK_FILE)）"
+  exit 1
+fi
+echo $$ > "$LOCK_FILE"
+
+# 版本 tag 強制
+CURRENT_TAG=$(git describe --exact-match --tags HEAD 2>/dev/null || echo "")
+if [ -z "$CURRENT_TAG" ]; then
+  echo "❌ HEAD 沒有版本 tag。請執行：git tag vX.Y.Z && git push --tags"
+  exit 1
+fi
+
+echo "[1/4] 執行測試..."
+# {TEST_COMMAND}
+
+echo "[2/4] 建置產物..."
+# {BUILD_COMMAND}
+
+echo "[3/4] 同步至伺服器..."
+rsync -avz --delete ./dist/ {USER}@{SERVER}:/app/
+
+echo "[4/4] 驗證部署..."
+./verify.sh || { echo "驗證失敗，啟動回滾..."; ./rollback.sh; exit 1; }
+
+echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"version\":\"$CURRENT_TAG\",\"operator\":\"$(whoami)\",\"result\":\"success\"}" >> /var/log/deployments.jsonl
+echo "✅ 部署成功：$CURRENT_TAG"
+```
+
+### verify.sh — Smoke Test
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+HEALTH_URL="${HEALTH_URL:-{HEALTH_URL}}"
+EXPECTED_VERSION=$(cat VERSION)
+
+for i in $(seq 1 3); do
+  RESPONSE=$(curl -sf --max-time 10 "$HEALTH_URL" 2>/dev/null) && break
+  echo "健康檢查第 $i/3 次失敗，5 秒後重試..."
+  sleep 5
+done
+
+ACTUAL_VERSION=$(echo "$RESPONSE" | python3 -c "import json,sys; print(json.load(sys.stdin)['version'])")
+
+if [ "$ACTUAL_VERSION" != "$EXPECTED_VERSION" ]; then
+  echo "❌ 版本不符！預期 $EXPECTED_VERSION，實際 $ACTUAL_VERSION"
+  exit 1
+fi
+
+echo "✅ 版本驗證通過：$ACTUAL_VERSION"
+```
+
+### rollback.sh — Blue-Green 回滾
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+CURRENT=$(readlink /app/current 2>/dev/null || echo "/app/blue")
+TARGET=$([[ "$CURRENT" == *"green"* ]] && echo "/app/blue" || echo "/app/green")
+
+ln -sfn "$TARGET" /app/current
+nginx -s reload
+
+echo "✅ 已回滾至 $TARGET ($(date -u +%Y-%m-%dT%H:%M:%SZ))"
+echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"rollback\",\"from\":\"$CURRENT\",\"to\":\"$TARGET\",\"operator\":\"$(whoami)\"}" >> /var/log/deployments.jsonl
+```
+
+### Makefile
+
+```makefile
+.PHONY: deploy rollback verify status
+
+deploy:
+	@./deploy.sh
+
+rollback:
+	@./rollback.sh
+
+verify:
+	@./verify.sh
+
+status:
+	@echo "目前 slot：$$(readlink /app/current 2>/dev/null || echo 'N/A')"
+	@curl -s $${HEALTH_URL:-http://localhost/health} | python3 -m json.tool 2>/dev/null || echo "健康檢查失敗"
+```
+
+## 輸出確認清單
+
+腳本生成後，AI 助手必須確認：
+
+- [ ] `deploy.sh` 含 `set -euo pipefail`
+- [ ] `deploy.sh` 含 deploy.lock 並發守衛
+- [ ] `verify.sh` 比對版本號（不只是 HTTP 200）
+- [ ] `rollback.sh` 在 verify 失敗時自動觸發
+- [ ] `Makefile` 提供 `make deploy / make rollback / make status`
+
+## 使用方式
+
+```bash
+/deploy              # 互動模式 — 自動偵測專案類型
+/deploy node         # Node.js 專案，直接生成
+/deploy docker       # Docker Compose 部署模式
+/deploy --verify-only  # 僅生成 verify.sh
+```
+
+## 下一步引導
+
+`/deploy` 完成後，AI 助手應建議：
+
+> **部署腳本已生成，建議下一步：**
+> - `chmod +x deploy.sh verify.sh rollback.sh` — 設定執行權限
+> - `make verify` — 測試健康檢查設定
+> - `git tag v1.0.0 && git push --tags` — 建立版本 tag
+> - `make deploy` — 執行第一次部署
+
+## 參考
+
+- 核心標準：[no-cicd-deployment.md](../../../../core/no-cicd-deployment.md)
+- 核心標準：[deployment-standards.md](../../../../core/deployment-standards.md)
+- 核心標準：[deployment-standards.md § Defensive Deployment Ordering](../../../../core/deployment-standards.md#defensive-deployment-ordering) — **強制**遵循 extract-verify-then-delete 順序
+- 核心標準：[packaging-standards.md § Archive Format Integrity](../../../../core/packaging-standards.md#archive-format-integrity) — 消費 archive 前先驗證格式
+- 相關：[ci-cd-assistant](../ci-cd-assistant/SKILL.md) — 適用於有 CI/CD 的環境
+
+## 版本歷史
+
+| 版本 | 日期 | 變更說明 |
+|------|------|----------|
+| 1.0.0 | 2026-04-26 | 初始版本 — XSPEC-085 Phase 1b |
+
+## 授權
+
+CC BY 4.0 — 文件內容

package/bundled/locales/zh-TW/skills/dev-methodology/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: methodology
+source: ../../../../skills/dev-methodology/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-05-28
+scope: partial
+description: |
+  [UDS] /methodology: 選擇並追蹤開發方法論（SDD/BDD/TDD）。
+  Use when: 選擇方法論、切換開發模式、查詢當前方法論狀態。
+  若要查詢各階段對應指令請用 /dev-workflow。
+allowed-tools: Read, Write, Grep, Glob
+argument-hint: "[動作] [參數]"
+---
+
+# 方法論系統
+
+> **語言**: [English](../../../../skills/dev-methodology/SKILL.md) | 繁體中文
+
+> [!WARNING]
+> **實驗性功能**
+>
+> 此功能正在積極開發中，可能在 v4.0 中有重大變更。
+
+選擇並管理當前專案啟用的開發方法論。本技能專注於**選擇使用哪種方法論**（SDD、BDD、TDD），並追蹤所選方法論內的階段進度。
+
+> **相關**：如需查詢開發階段對應的 UDS 指令，請改用 `/dev-workflow`。
+
+### 何時使用 `/methodology` 與 `/dev-workflow`
+
+| 情境 | `/methodology` | `/dev-workflow` |
+|------|---------------|-----------------|
+| 在 SDD / BDD / TDD 之間選擇 | ✅ | ❌ |
+| 切換不同方法論 | ✅ | ❌ |
+| 追蹤目前階段進度 | ✅ | ❌ |
+| 找出某個任務該用的 UDS 指令 | ❌ | ✅ |
+| 取得新功能 / Bug 修復的逐步流程 | ❌ | ✅ |
+| 巡覽 8 個開發階段 | ❌ | ✅ |
+
+**兩個獨立系統：**
+- **System A：SDD** — 規格驅動開發（AI 時代，spec-first）
+- **System B：雙迴圈 TDD** — BDD（外圈）+ TDD（內圈）（傳統）
+
+**選用輸入：** ATDD — 驗收測試驅動開發（可餵入任一系統）
+
+## 動作
+
+| 動作 | 說明 |
+|------|------|
+| *(無)* / `status` | 顯示當前階段與檢查清單 |
+| `switch <id>` | 切換到不同方法論 |
+| `phase [name]` | 顯示或變更當前階段 |
+| `checklist` | 顯示當前階段檢查清單 |
+| `skip` | 跳過當前階段（會出現警告） |
+| `list` | 列出可用方法論 |
+| `create` | 建立自訂方法論 |
+
+## 可用方法論
+
+| 系統 | ID | 工作流程 | 說明 |
+|------|-----|----------|------|
+| A: SDD | `sdd` | /sdd → 審查 → /derive-all → 實作 | 規格優先 |
+| B: BDD | `bdd` | Discovery → Formulation → Automation | 外部迴圈 |
+| B: TDD | `tdd` | Red → Green → Refactor | 內部迴圈 |
+| 輸入 | `atdd` | Workshop → Examples → Tests | 驗收測試驅動 |
+
+## 使用範例
+
+```bash
+/methodology                    # 顯示目前狀態
+/methodology switch sdd         # 切換至規格驅動開發
+/methodology phase green        # 移動到 GREEN 階段（TDD）
+/methodology checklist          # 顯示當前階段檢查清單
+/methodology list               # 列出所有可用方法論
+/methodology skip               # 跳過當前階段（會出現警告）
+/methodology create             # 啟動自訂方法論精靈
+```
+
+## 配置
+
+方法論設定儲存於 `.standards/manifest.json`：
+
+```json
+{
+  "methodology": {
+    "active": "sdd",
+    "available": ["tdd", "bdd", "sdd", "atdd"]
+  }
+}
+```
+
+## 下一步引導
+
+`/methodology` 完成後，AI 助手應依所選方法論建議下一步：
+
+> **方法論已設定。建議下一步：**
+> - SDD 方法論 → 執行 `/sdd` 建立規格 ⭐ **推薦**
+> - BDD 方法論 → 執行 `/bdd` 開始場景探索
+> - TDD 方法論 → 執行 `/tdd` 開始紅綠重構
+> - ATDD 方法論 → 執行 `/atdd` 定義驗收條件
+
+## 參考
+
+- 詳細指南：[guide.md](./guide.md)
+
+## AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/methodology`](../../../../skills/commands/methodology.md#ai-agent-behavior--ai-代理行為)

package/bundled/locales/zh-TW/skills/journey-test-assistant/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: journey-test-assistant
+source: ../../../../skills/journey-test-assistant/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-05-28
+scope: partial
+description: "[UDS] 從專案描述生成連貫使用者旅程測試計畫（TESTPLAN）與 E2E 骨架"
+allowed-tools: Read, Write, Grep, Glob
+argument-hint: "[專案描述 | --analyze | --archetype A1|A2|A3]"
+status: stable
+---
+
+# 旅程測試助手
+
+> **語言**: [English](../../../../skills/journey-test-assistant/SKILL.md) | 繁體中文
+
+從專案描述生成連貫的使用者旅程測試計畫（TESTPLAN-NNN.md）與對應的 E2E 骨架，讓每個新專案從第一天起就擁有完整測試旅程。
+
+## 選擇正確的測試 Skill
+
+| 需求 | 使用 |
+|------|------|
+| 單元測試 / TDD 紅綠重構 | `/tdd-assistant` |
+| BDD 場景 / Given-When-Then | `/bdd-assistant` |
+| 驗收測試 / ATDD / 使用者故事 | `/atdd-assistant` |
+| E2E / Playwright / 瀏覽器測試 | `/e2e-assistant` |
+| 合約測試 / API consumer-driven | `/contract-test-assistant` |
+| 測試覆蓋率差距分析 | `/test-coverage-assistant` |
+| 使用者旅程測試計畫 | `/journey-test-assistant` |
+| 一般測試策略 / 測試金字塔 | `/testing-guide` |
+
+## 與 /e2e 的差異
+
+| 維度 | /e2e | /journey-test |
+|------|------|--------------|
+| 組織單位 | 單一 XSPEC / AC | 跨 Story 的使用者旅程 |
+| 測試結構 | 隔離、獨立 | 連貫、狀態共享 |
+| 產物 | `*.spec.ts` 骨架 | `TESTPLAN.md` + `*.journey.spec.ts` |
+| 觸發時機 | 功能完成後 | 專案建立時（Journey-First） |
+| 偵測目標 | 單一 AC 是否正確 | 跨步驟狀態傳遞是否連貫 |
+
+## 工作流程
+
+```
+輸入：專案描述 / 現有 TESTPLAN / --analyze
+    ↓
+Phase 1：定義 Persona
+    分析專案描述 → 識別所有使用者角色 → 定義 Actor / Role / Key Permissions
+    ↓
+Phase 2：設計旅程地圖
+    列出主要業務目標 → 拆解為 T-NNN 群組 → 宣告依賴鏈
+    ↓
+Phase 3：生成 TESTPLAN
+    按格式輸出 test-plans/TESTPLAN-001.md（含 Personas、步驟、依賴圖）
+    ↓
+Phase 4：生成 E2E 骨架
+    從 TESTPLAN T-NNN 生成 *.journey.spec.ts（含 skipIf + 共享 state）
+```
+
+## 模式
+
+### 1. 生成模式（預設）
+
+從專案描述生成完整的 TESTPLAN + E2E 骨架。
+
+```
+/journey-test "電商平台，需要 buyer/seller/admin 三個角色"
+```
+
+產物：
+- `test-plans/TESTPLAN-001.md`：含 Personas、T-000 環境重置、T-001 ~ T-NNN 步驟群組、執行順序依賴圖
+- `src/e2e/journey/main-flow.journey.spec.ts`：含 `describe.skipIf` + 共享 state + T-NNN 對應的完整骨架
+
+### 2. 分析模式（--analyze）
+
+掃描現有測試，找出旅程覆蓋缺口。
+
+```
+/journey-test --analyze
+```
+
+執行步驟：
+1. 讀取 `test-plans/TESTPLAN-NNN.md`（若存在）
+2. 掃描 `src/e2e/` 下所有 `*.journey.spec.ts` 與 `*.journey.e2e.test.ts`
+3. 比對 TESTPLAN T-NNN 與自動化測試中的 T-NNN 引用
+4. 輸出覆蓋缺口報告：列出 TESTPLAN 中缺乏自動化對應的 T-NNN 步驟
+
+### 3. Archetype 模式（--archetype）
+
+使用預設旅程模板，適合已知類型的專案快速啟動。
+
+```
+/journey-test --archetype A1    # Spec-driven 旅程
+/journey-test --archetype A2    # UI-driven 旅程
+/journey-test --archetype A3    # Brownfield 旅程
+```
+
+| Archetype | 模板 | 適用場景 |
+|-----------|------|---------|
+| A1 | Spec-driven | 需求 → Spec → Code → Test，適合 API / Backend 專案 |
+| A2 | UI-driven | 設計稿 → UI → 視覺回歸，適合前端 / 全端專案 |
+| A3 | Brownfield | 現有程式碼 → 分析 → 重構驗證，適合既有專案補測試 |
+
+## TESTPLAN 格式（T-NNN）
+
+以下為完整的 TESTPLAN 範本，展示所有必要區段：
+
+```markdown
+# TESTPLAN-001 <ProjectName> 主線旅程
+
+## Personas
+
+| Actor          | Role           | Key Permissions                |
+|----------------|----------------|--------------------------------|
+| platform_admin | Platform Admin | 建立 Org、管理使用者、查看所有資源 |
+| org_member     | Org Member     | 讀取專案、執行 Pipeline          |
+
+## Environment
+
+- BASE_URL：`http://localhost:3000`（本機） / `$JOURNEY_BASE_URL`（CI）
+- 驗證指令：`curl $BASE_URL/health`
+- 必要帳號：`ADMIN_EMAIL`、`ADMIN_PASSWORD` 環境變數
+
+## T-000 環境重置（optional）
+
+前置條件：無
+depends_on：無
+
+| 步驟    | 操作                          | 預期結果      |
+|---------|-------------------------------|---------------|
+| T-000-1 | [API] GET /health            | 回傳 200 OK   |
+| T-000-2 | [CHECK] 資料庫連線正常        | 無錯誤日誌    |
+
+## T-001 Platform Admin 登入
+
+前置條件：環境正常運行（T-000 通過）
+depends_on：T-000
+
+| 步驟    | 操作                                       | 預期結果                |
+|---------|--------------------------------------------|-------------------------|
+| T-001-1 | [API] POST /api/auth/login（admin 帳號）   | 回傳 200 + authToken    |
+| T-001-2 | [CHECK] authToken 存入共享 state           | let authToken 有值      |
+
+## T-010 主要功能操作
+
+前置條件：authToken 已取得（T-001 通過）
+depends_on：T-001
+
+| 步驟    | 操作                                       | 預期結果                |
+|---------|--------------------------------------------|-------------------------|
+| T-010-1 | [API] POST /api/resources（帶 authToken）  | 回傳 201 + resourceId ★ |
+| T-010-2 | [CHECK] resourceId 存入共享 state          | let resourceId 有值     |
+
+## 執行順序依賴圖
+
+T-000 → T-001 → T-010
+```
+
+## E2E 骨架格式（.journey.spec.ts）
+
+生成的骨架展示三個核心模式：`describe.skipIf` 環境保護、共享 `let` 狀態、T-NNN 識別碼對應。
+
+```typescript
+import { describe, it, expect } from "vitest"
+
+// Journey E2E：需要真實後端，不設定 JOURNEY_BASE_URL 則全部 skip
+const BASE_URL = process.env.JOURNEY_BASE_URL || ""
+
+describe.skipIf(!BASE_URL)("Platform Admin Journey — T-001 → T-010", () => {
+  // 共享 state：每個步驟從前一步驟的結果取值
+  let authToken: string
+  let resourceId: string
+
+  it("T-001: Platform Admin 登入並取得 authToken", async () => {
+    const res = await fetch(`${BASE_URL}/api/auth/login`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        email: process.env.ADMIN_EMAIL,
+        password: process.env.ADMIN_PASSWORD,
+      }),
+    })
+    expect(res.status, "T-001 失敗：登入應回傳 200").toBe(200)
+    const data = await res.json()
+    expect(data.token, "T-001 失敗：應有 token").toBeTruthy()
+    authToken = data.token  // ← 傳遞給後續步驟
+  })
+
+  it("T-010: 執行主要操作（depends on T-001）", async () => {
+    // 若 T-001 失敗，authToken 為 undefined，此步驟的錯誤訊息會清楚說明
+    expect(authToken, "T-010 前置失敗：T-001 的 authToken 不存在").toBeTruthy()
+
+    const res = await fetch(`${BASE_URL}/api/resources`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${authToken}`,
+      },
+      body: JSON.stringify({ name: "journey-test-resource" }),
+    })
+    expect(res.status, `T-010 失敗：預期 201，實際 ${res.status}`).toBe(201)
+    const data = await res.json()
+    resourceId = data.id  // ← 傳遞給後續步驟
+  })
+})
+```
+
+## 後續步驟
+
+完成後建議：
+
+> **TESTPLAN 與 Journey E2E 骨架已生成。建議下一步：**
+> - 執行 `/e2e` 生成各功能的 AC 層測試（補充旅程測試的細節覆蓋）
+> - 執行 `/atdd` 定義各 T-NNN 步驟對應的驗收條件
+> - 執行 `/journey-test --analyze` 定期檢查自動化覆蓋缺口
+
+## 參考
+
+- 標準：[user-journey-testing.ai.yaml](../../../../.standards/user-journey-testing.ai.yaml)
+- 相關 XSPEC：XSPEC-128（UDS 標準定義）
+- 相關 Skill：`/e2e`（AC 層測試）、`/atdd`（驗收條件定義）

package/bundled/locales/zh-TW/skills/knowledge-graph/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: knowledge-graph
+source: ../../../../skills/knowledge-graph/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-05-30
+status: current
+description: "[UDS] 透過知識圖追蹤規格／決策／程式碼的影響鏈（引擎或 Markdown 後備）"
+---
+
+# 知識圖
+
+> **語言**: [English](../../../../skills/knowledge-graph/SKILL.md) | 繁體中文
+
+依據[知識圖記憶標準](../../../../core/knowledge-graph-memory.md)的關係 schema，回答橫跨規格、決策與程式碼的結構性問題——*「XSPEC-205 的完整影響鏈是什麼？」*。有無圖引擎皆可運作。
+
+> **Implements**: XSPEC-237 Phase 5 — knowledge-graph skill（CodeSage opt-in）
+
+## 模式選擇
+
+回答**前**先判斷使用哪種模式：
+
+| 條件 | 模式 |
+|------|------|
+| 設定了 `CODESAGE_URL`，或本機圖引擎 `/health` 有回應 | 服務模式（引擎）|
+| 否則 | 降級模式（Markdown）|
+
+## 工作流程
+
+1. **解析目標**——將參數正規化為標準 id（`XSPEC-205`、`DEC-062`、函式名）。
+2. **選擇模式**——探測圖引擎（服務）否則後備（降級）。
+3. **服務模式（AC-5b）**——送出單一多跳查詢，呈現回傳的鏈（含跨域連結 code → spec → decision）：
+   ```bash
+   curl -s -X POST "$CODESAGE_URL/graph/impact-analysis" \
+     -H 'content-type: application/json' \
+     -d '{"nodeId":"XSPEC-205","maxHops":3}'
+   ```
+4. **降級模式（AC-5a）**——無引擎時，讀取目標文件，沿其 `impacts`/`impacted_by`/`supersedes`/`related` front-matter 與內文 `[[ref]]` 連結讀取被連結檔案，手動組出鏈（受讀取深度限制）。
+5. **呈現鏈**——列出相連的 Spec 與 Decision、每跳的邊型別、以及（若有）各節點的 `confidence`，高者在前。
+6. **說明使用的模式**——務必告知答案來自引擎或 Markdown 後備，以明確完整度。
+
+## 關係 schema
+
+見[知識圖記憶標準](../../../../core/knowledge-graph-memory.md)。front-matter 欄位：`related`、`impacts`、`impacted_by`、`supersedes`、`implements`。
+
+## 下一步引導
+
+- 降級模式若觸及讀取深度上限，告知使用者圖引擎（如 CodeSage）可給出完整鏈，以及如何設定 `CODESAGE_URL`。
+- 若參照的 id 找不到，標示為待修的懸空參照。
+- 主動提議為遍歷過的文件補上缺漏的 `impacts`/`impacted_by` front-matter。
+
+## 參考
+
+- 標準：[core/knowledge-graph-memory.md](../../../../core/knowledge-graph-memory.md)
+- 引擎（opt-in）：[CodeSage](https://github.com/AsiaOstrich/CodeSage) — `@asiaostrich/codesage`
+- 詳細指南：[guide.md](guide.md)