universal-dev-standards 5.14.0 → 5.16.0

package/bundled/locales/zh-TW/skills/push/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: push
+source: ../../../../skills/push/SKILL.md
+source_version: 2.0.0
+translation_version: 2.0.0
+last_synced: 2026-06-02
+source_hash: b7812535483c
+scope: universal
+description: |
+  [UDS] AI 輔助 git push 安全層：品質閘門 + 協作護欄。
+  Use when: pushing commits, force pushing, pushing to protected branches, pushing feature branches.
+  Keywords: git push, force push, protected branch, quality gate, push receipt, PR automation, 推送, 保護分支, 品質閘門.
+allowed-tools: Read, Bash(git:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(bun:*)
+argument-hint: "[--force] [--target <branch>] [--skip-gates] [--no-pr]"
+---
+
+# 推送助手
+
+> **語言**: [English](../../../../skills/push/SKILL.md) | 繁體中文
+
+**版本**：2.0.0
+**建立日期**：2026-04-23
+**適用範圍**：Claude Code Skills
+
+---
+
+`git push` 的 AI 輔助安全層。偵測保護分支、強制 force-push 護欄、執行 pre-push 品質閘門、輸出結構化推送收據，並整合 PR 自動化。
+
+## 核心標準
+
+本 Skill 實作 [`.standards/push-standards.ai.yaml`](../../../../.standards/push-standards.ai.yaml)。
+
+---
+
+## 執行工作流程
+
+呼叫 `/push` 後，Claude 原生依序執行以下步驟：
+
+### Step 1：偵測保護分支
+執行 `git rev-parse --abbrev-ref HEAD` 取得目前分支。
+比對 `protected_branches` 清單（預設：main、master、release/*、hotfix/*）。
+若為保護分支：顯示警告 + 待推送的 commit 列表，需使用者明確確認才能繼續。
+
+### Step 2：偵測 Force Push
+若偵測到 `--force` 或 `--force-with-lease`：
+執行 `git log origin/<branch>..HEAD --oneline` 找出將被覆蓋的 commits。
+顯示數量與作者列表。需要使用者輸入 `yes, force push` 才能繼續。
+
+### Step 3：執行 Pre-Push 品質閘門
+依序使用 Bash tool 執行每個已設定的閘門：
+- `lint`：偵測並執行專案 lint 指令
+- `test`：偵測並執行專案測試指令
+- `type-check`（選用）：TypeScript 型別檢查
+- `ac-coverage`（選用）：驗收條件覆蓋率
+- `security-scan`（選用）：安全漏洞掃描
+
+若任何必要閘門失敗：中止並顯示錯誤訊息。
+
+### Step 4：執行推送
+執行 `git push <remote> <branch> [--force]`。
+若推送失敗：顯示 git 錯誤並建議修正方式。
+
+### Step 5：發出推送收據
+將結構化收據輸出到 console（可選擇寫入 `~/.uds/push-history.jsonl`）：
+```json
+{
+  "branch": "<branch>",
+  "commit_sha": "<sha>",
+  "gates_passed": ["lint", "test"],
+  "force_push": false,
+  "timestamp": "<ISO8601>",
+  "target_remote": "origin"
+}
+```
+
+### Step 6：PR 整合
+若 `auto_pr=true` **且** `repo_mode=team` **且**該分支無 open PR：
+建議使用者執行 `/pr-automation-assistant` 建立 Pull Request。
+
+---
+
+## 功能說明
+
+### 1. 推送目標風險偵測
+
+推送前偵測目標分支是否為保護分支（例如 `main`、`master`、`release/*`、`hotfix/*`）。
+
+- 顯示**警告**，列出分支名稱與 commit 清單
+- 需要使用者明確確認才能繼續
+- 使用者未確認則中止推送
+
+### 2. Force-Push 護欄
+
+偵測到 `--force` 時，推送前顯示影響範圍。
+
+- 計算遠端將被覆蓋的 commits
+- 顯示被覆蓋 commits 的數量與作者
+- 要求使用者輸入確認字串（`yes, force push`）
+- 在推送收據中記錄 `force_push: true`
+
+### 3. Pre-Push 品質閘門
+
+推送前依序執行已設定的品質閘門。
+
+| 閘門 | 說明 |
+|------|------|
+| `lint` | 執行 lint 檢查 |
+| `test` | 執行測試 |
+| `type-check` | TypeScript 型別檢查（選用） |
+| `ac-coverage` | AC 覆蓋率檢查（選用） |
+| `security-scan` | 安全掃描（選用） |
+
+### 4. 推送收據
+
+推送成功後輸出結構化收據，供稽核追蹤使用。
+
+```json
+{
+  "branch": "feature/my-feature",
+  "commit_sha": "a1b2c3d",
+  "gates_passed": ["lint", "test"],
+  "gates_skipped": false,
+  "force_push": false,
+  "timestamp": "2026-04-23T10:00:00Z",
+  "target_remote": "origin"
+}
+```
+
+可選擇附加到 `~/.uds/push-history.jsonl` 以持久化稽核追蹤。
+
+### 5. PR 自動化整合入口
+
+推送 feature branch 後，若尚無 PR，提示使用者建立 Pull Request。
+
+- 檢查該分支是否已有 open PR
+- 提示使用者執行 `pr-automation-assistant`
+- 在 `single-owner` repo 模式或使用 `--no-pr` 旗標時跳過
+
+---
+
+## 使用方式
+
+```bash
+# 標準推送（自動執行品質閘門）
+/push
+
+# Force push（顯示被覆蓋 commits，需要確認）
+/push --force
+
+# 推送到指定的遠端分支
+/push --target main
+
+# 跳過品質閘門（緊急情況）
+/push --skip-gates
+
+# 推送但不提示建立 PR
+/push --no-pr
+
+# Force push 且不提示建立 PR（例如更新個人分支）
+/push --force --no-pr
+```
+
+## 參數說明
+
+| 參數 | 說明 |
+|------|------|
+| `--force` | 啟用 force push，含護欄確認 |
+| `--target <branch>` | 明確指定目標遠端分支 |
+| `--skip-gates` | 跳過品質閘門（僅緊急情況） |
+| `--no-pr` | 推送後不提示建立 PR |
+
+---
+
+## 設定
+
+透過 `uds.project.yaml` 設定：
+
+```yaml
+push:
+  repo_mode: team           # "team" | "single-owner"
+  protected_branches:
+    - main
+    - master
+    - "release/*"
+    - "hotfix/*"
+  push_gates:
+    default:
+      - lint
+      - test
+    optional:
+      - type-check
+      - ac-coverage
+      - security-scan
+  receipt:
+    output: console          # "console" | "file" | "both"
+    file_path: "~/.uds/push-history.jsonl"
+  auto_pr: true              # 推送到非保護分支後是否提示建立 PR
+```
+
+### 選項模式
+
+| Option 檔案 | 模式 | 說明 |
+|-------------|------|------|
+| [`options/push/team-mode.md`](../../../../options/push/team-mode.md) | `team` | 完整協作護欄（預設） |
+| [`options/push/single-owner-mode.md`](../../../../options/push/single-owner-mode.md) | `single-owner` | 個人 repo 低摩擦模式 |
+
+---
+
+## 下一步引導
+
+`/push` 完成後，AI 助手應建議：
+
+> **推送完成。建議下一步：**
+> - 執行 `/pr-automation-assistant` 建立或更新 Pull Request ⭐ **推薦** — 確保協作流程完整
+> - 執行 `/checkin` 確認程式碼簽入品質 — 下次提交前的品質確認
+> - 查看 `~/.uds/push-history.jsonl` 確認推送紀錄 — 稽核追蹤
+
+---
+
+## 相關標準
+
+- [Push Standards](../../../../.standards/push-standards.ai.yaml) — 核心推送安全規則
+- [Git Workflow](../../../../.standards/git-workflow.ai.yaml) — 分支策略
+- [Commit Message](../../../../.standards/commit-message.ai.yaml) — Commit 慣例
+- [PR Automation](../pr-automation-assistant/SKILL.md) — Pull Request 自動化
+
+---
+
+## 版本歷程
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 2.0.0 | 2026-04-28 | 還原 workflow 執行步驟（XSPEC-097 採用層解耦）；移除棄用通知 |
+| 1.0.0 | 2026-04-23 | 初始版本 — XSPEC-081 Phase 1 |
+
+---
+
+## 授權
+
+本 Skill 採用 [MIT License](https://opensource.org/licenses/MIT) 與 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 雙重授權發布。
+
+**來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

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

@@ -2,17 +2,61 @@
 name: retrospective-assistant
 source: ../../../../skills/retrospective-assistant/SKILL.md
 source_version: 1.0.0
+source_hash: 9c883f05ad7b
 translation_version: 1.0.0
-last_synced: 2026-03-26
+last_synced: 2026-06-01
 status: current
-description: "[UDS] 引導結構化的團隊回顧，支援 Sprint 和 Release 回顧"
+description: "[UDS] 引導 Sprint 與 Release 週期的結構化團隊回顧"
 ---
 
 # 回顧助手
 
 > **語言**: [English](../../../../skills/retrospective-assistant/SKILL.md) | 繁體中文
 
-引導結構化的團隊回顧，識別改善機會並追蹤行動項目。
+引導結構化的團隊回顧，識別改善機會並追蹤行動項目。支援 Sprint 和 Release 回顧類型，提供多種引導技法。
+
+## 工作流程
+
+```
+PREPARE ──► GATHER ──► ANALYZE ──► DECIDE ──► TRACK
+  準備資料    蒐集意見    分析歸納    決定行動    追蹤落實
+```
+
+### 階段 1：PREPARE（準備）
+
+從 git log、指標和 issue tracker 蒐集數據作為討論基礎。
+
+### 階段 2：GATHER（蒐集）
+
+使用結構化技法蒐集團隊觀點。
+
+### 階段 3：ANALYZE（分析）
+
+分組歸納並識別模式。
+
+### 階段 4：DECIDE（決定）
+
+選出前 1-3 項改善作為行動項目。
+
+### 階段 5：TRACK（追蹤）
+
+檢視過去的行動項目並追蹤新項目。
+
+## 回顧類型
+
+| 類型 | 時機 | 時長 | 焦點 |
+|------|------|------|------|
+| **Sprint** | 迭代結束 | 30-60 分鐘 | 流程、協作、工具 |
+| **Release** | 發布之後 | 60-90 分鐘 | 品質、指標、跨團隊 |
+
+## 引導技法
+
+| 技法 | 適用場景 | 結構 |
+|------|---------|------|
+| **Start-Stop-Continue** | 快速、預設 | 開始 / 停止 / 繼續 |
+| **Starfish** | 細緻分析 | 更多 / 保持 / 減少 / 開始 / 停止 |
+| **4Ls** | 團隊建立 | 喜歡 / 學到 / 缺少 / 渴望 |
+| **Sailboat** | 視覺化、創意 | 風 / 錨 / 礁石 / 島嶼 |
 
 ## 指令
 
@@ -24,21 +68,43 @@ description: "[UDS] 引導結構化的團隊回顧，支援 Sprint 和 Release
 | `/retrospective actions` | 列出未完成行動項目 |
 | `/retrospective --technique starfish` | 使用指定技法 |
 
-## 參考
+## 行動項目格式
 
-- 核心規範：[retrospective-standards.md](../../../../core/retrospective-standards.md)
-- 詳細指南：[guide.md](./guide.md)
+| 欄位 | 說明 |
+|------|------|
+| **Action** | 具體描述 |
+| **Owner** | 單一負責人 |
+| **Due Date** | 預計完成日 |
+| **Status** | Open → In Progress → Done |
 
+### 追蹤規則
 
-## Next Steps Guidance | 下一步引導
+1. 每次回顧**開始**先檢視未完成項目
+2. 每次回顧最多 **3 項**行動項目
+3. 陳舊項目（超過 2 個循環未完成）須重新評估
+4. 每項須有**單一負責人**
 
-After `/retrospective` completes:
+## 存放
 
-> **Retrospective complete. Suggested next steps:**
-> - Commit the retrospective report: `/commit`
-> - Create ADRs for architectural decisions identified: `/adr`
-> - Track action items in your issue tracker
-> - Schedule next retrospective
+```
+docs/retrospectives/
+├── RETRO-2026-03-15-sprint-12.md
+├── RETRO-2026-03-26-release-v5.1.0.md
+└── README.md    # 索引（選用）
+```
+
+## 與其他技能的整合
+
+| 技能 | 整合方式 |
+|------|---------|
+| `/metrics` | 將指標數據引入 Release 回顧 |
+| `/incident` | 事故後建議進行團隊回顧 |
+| `/adr` | 識別架構問題時建議建立 ADR |
+| `/commit` | 以 `docs(retro):` 提交回顧報告 |
+
+## 下一步引導
+
+`/retrospective` 完成後：
 
 > **回顧完成。建議下一步：**
 > - 提交回顧報告：`/commit`
@@ -46,23 +112,23 @@ After `/retrospective` completes:
 > - 在 issue tracker 中追蹤行動項目
 > - 排定下次回顧
 
-## AI Agent Behavior | AI 代理行為
+## AI 代理行為
 
-When `/retrospective` is invoked:
+當呼叫 `/retrospective` 時：
 
-1. **Check type** — Sprint (default) or Release
-2. **Gather data** — Scan git log, check `docs/retrospectives/` for previous actions
-3. **Guide technique** — Use Start-Stop-Continue by default, or specified technique
-4. **Generate report** — Write to `docs/retrospectives/RETRO-YYYY-MM-DD-[type].md`
-5. **Review past actions** — Check previous retro for open action items
-6. **Offer next steps** — Show guidance above
+1. **確認類型** — Sprint（預設）或 Release
+2. **蒐集數據** — 掃描 git log，檢查 `docs/retrospectives/` 中過去的行動項目
+3. **引導技法** — 預設使用 Start-Stop-Continue，或使用指定技法
+4. **產生報告** — 寫入 `docs/retrospectives/RETRO-YYYY-MM-DD-[type].md`
+5. **檢視過去項目** — 檢查先前回顧中未完成的行動項目
+6. **提供下一步** — 顯示上方引導
 
-When `/retrospective actions` is invoked:
-1. Scan `docs/retrospectives/` for all retro files
-2. Parse action items from each
-3. Display open/in-progress items as table
+當呼叫 `/retrospective actions` 時：
+1. 掃描 `docs/retrospectives/` 中所有回顧檔案
+2. 解析各檔案中的行動項目
+3. 以表格顯示未完成／進行中的項目
 
-## Reference | 參考
+## 參考
 
-- Core Standard: [retrospective-standards.md](../../core/retrospective-standards.md)
-- Detailed Guide: [guide.md](./guide.md)
+- 核心規範：[retrospective-standards.md](../../core/retrospective-standards.md)
+- 詳細指南：[guide.md](./guide.md)

package/bundled/locales/zh-TW/skills/reverse-engineer/SKILL.md

@@ -2,48 +2,94 @@
 name: reverse-engineer
 source: ../../../../skills/reverse-engineer/SKILL.md
 source_version: 1.2.0
+source_hash: d543b24b2422
 translation_version: 1.2.0
-last_synced: 2026-02-10
+last_synced: 2026-06-01
 status: current
-description: "[UDS] 將現有程式碼反向工程為規格文件、BDD 場景或 TDD 覆蓋率報告"
+description: "[UDS] 系統考古——跨邏輯、資料、執行環境三維度反向工程程式碼"
 ---
 
 # 反向工程助手
 
 > **語言**: [English](../../../../skills/reverse-engineer/SKILL.md) | 繁體中文
 
-將現有程式碼反向工程為規格文件、BDD 場景或 TDD 覆蓋率報告。
+系統考古框架：從三個維度反向工程既有系統——**邏輯**、**資料**、**執行環境**。
+
+## 三大維度
+
+```
+┌─────────────────────────────────────────────────────────┐
+│              System Archeology Framework                   │
+├──────────┬──────────────┬────────────────────────────────┤
+│  Logic   │     Data     │          Runtime               │
+│ (spec)   │    (data)    │         (runtime)              │
+├──────────┼──────────────┼────────────────────────────────┤
+│ APIs     │ DB Schemas   │ Logs & Error Patterns          │
+│ Modules  │ ORMs/Models  │ Config & Environment           │
+│ Flows    │ Migrations   │ Metrics & Performance          │
+│ Tests    │ Seed Data    │ Infra & Deployment             │
+└──────────┴──────────────┴────────────────────────────────┘
+```
 
 ## 子命令
 
-| 子命令 | 輸入 | 輸出 | 說明 |
-|--------|------|------|------|
-| `spec` | 程式碼檔案/目錄 | `SPEC-XXX.md` | 從程式碼提取規格 |
-| `bdd` | `SPEC-XXX.md` | `.feature` | 將 AC 轉為 Gherkin |
-| `tdd` | `.feature` | 覆蓋率報告 | 分析測試覆蓋率 |
+| 子命令 | 維度 | 輸入 | 輸出 | 說明 |
+|--------|------|------|------|------|
+| *(無)* | 全部 | 專案根目錄 | 完整考古報告 | 三維度全面分析 |
+| `spec` | 邏輯 | 程式碼檔案/目錄 | `SPEC-XXX.md` | 從程式碼提取規格 |
+| `data` | 資料 | DB 結構、ORM、遷移檔 | 資料模型規格 | 分析資料模型與結構 |
+| `runtime` | 執行環境 | 日誌、設定、指標 | 執行環境基準 | 分析執行環境基準 |
+| `bdd` | — | `SPEC-XXX.md` | `.feature` | 將 AC 轉為 Gherkin |
+| `tdd` | — | `.feature` | 覆蓋率報告 | 分析測試覆蓋率 |
+
+## 全面分析模式
+
+當 `/reverse` 在未帶子命令的情況下被呼叫時，依序執行全部三個維度：
+
+1. **資料（Data）** → 掃描結構、ORM、遷移檔
+2. **執行環境（Runtime）** → 分析日誌、設定、部署
+3. **邏輯（Logic / spec）** → 提取 API、流程、測試 → 產生 SPEC
+
+輸出：整合三個維度的 **系統考古報告（System Archeology Report）**。
 
-## 工作流程
+## 維度詳情
 
-### spec：程式碼轉規格
+### spec：邏輯維度（既有）
 
-1. **掃描** - 讀取原始碼檔案，識別公開 API、資料流和業務邏輯
+1. **掃描** - 讀取原始碼檔案，識別公開 API、資料流與業務邏輯
 2. **分類** - 將每個發現標記為 `[Confirmed]`、`[Inferred]` 或 `[Unknown]`
 3. **結構化** - 整理為 SDD 規格格式，包含驗收條件
-4. **引用來源** - 每個反向結果皆引用 `file:line` 來源參考
+4. **引用來源** - 每項反向結果皆以 `file:line` 引用來源
 
-### bdd：規格轉 Gherkin
+### data：資料維度（新增）
 
-1. **解析** - 讀取 SPEC-XXX.md 並提取驗收條件
-2. **轉換** - 將每個 AC 對應為一個 Gherkin Scenario（1:1 對應）
-3. **標記** - 加入 `@SPEC-XXX` 和 `@AC-N` 標籤以確保可追溯性
-4. **輸出** - 產生 `.feature` 檔案，包含 `# [Source: path:AC-N]` 註解
+1. **探索** - 找出資料庫結構、ORM 模型、遷移檔、種子資料
+2. **對應** - 從程式碼證據建立實體關聯模型
+3. **分類** - 將關聯標記為 `[Confirmed]`（FK 約束）或 `[Inferred]`（程式碼模式）
+4. **報告** - 輸出資料模型規格，包含：
+   - 含欄位與型別的實體清單
+   - 關聯對應（1:1、1:N、M:N）
+   - 索引與約束清單
+   - 遷移歷史摘要
+   - 資料流路徑（寫入 → 讀取）
 
-### tdd：Feature 轉覆蓋率報告
+**證據來源**：`schema.prisma`、`*.migration.*`、`models/`、`entities/`、`knexfile.*`、`sequelize`、`typeorm`、SQL 檔案、`docker-compose.yml`（DB 服務）
 
-1. **解析** - 讀取 `.feature` 檔案中的場景
-2. **搜尋** - 使用 Grep/Glob 尋找對應的測試檔案
-3. **對應** - 將場景與現有單元測試進行配對
-4. **報告** - 輸出覆蓋率矩陣（已覆蓋 / 缺失 / 部分覆蓋）
+### runtime：執行環境維度（新增）
+
+1. **掃描設定** - 環境變數、設定檔、功能旗標
+2. **分析日誌** - 日誌模式、錯誤頻率、日誌層級
+3. **檢查基礎設施** - Docker 設定、CI/CD 管線、部署清單
+4. **建立基準** - 輸出執行環境基準，包含：
+   - 環境變數清單（僅名稱，**絕不含值/密鑰**）
+   - 設定檔對應與階層
+   - 外部服務依賴（API、佇列、快取）
+   - 部署拓撲（容器、服務）
+   - 健康檢查與監控端點
+
+**證據來源**：`.env.example`、`docker-compose.yml`、`Dockerfile`、`*.config.*`、CI/CD 檔案、`k8s/`、日誌檔案（僅模式）
+
+**安全性**：絕不輸出實際密鑰值。僅列出變數名稱並描述其用途。
 
 ## 防幻覺規則
 
@@ -52,23 +98,33 @@ description: "[UDS] 將現有程式碼反向工程為規格文件、BDD 場景
 | **確定性標籤** | 所有發現須使用 `[Confirmed]`、`[Inferred]`、`[Unknown]` 標注 |
 | **來源引用** | 每項反向結果須引用 `file:line` 來源 |
 | **禁止捏造** | 不得捏造程式碼中不存在的 API 或行為 |
+| **禁止密鑰** | 不得輸出設定檔或環境變數的密鑰值 |
 
 ## 使用方式
 
-- `/reverse spec src/auth/` - 從 auth 模組提取規格
-- `/reverse bdd specs/SPEC-AUTH.md` - 將規格 AC 轉為 Gherkin 場景
-- `/reverse tdd features/auth.feature` - 分析 feature 檔案的測試覆蓋率
+```
+/reverse                              - 三維度全面分析
+/reverse spec src/auth/               - 邏輯：提取規格
+/reverse data                         - 資料：分析結構與模型
+/reverse runtime                      - 執行環境：分析設定與基礎設施
+/reverse bdd specs/SPEC-AUTH.md       - 將規格 AC 轉為 Gherkin
+/reverse tdd features/auth.feature    - 分析測試覆蓋率
+```
 
 ## 下一步引導
 
 `/reverse`（完整或 `spec`）完成後，AI 助手應建議：
 
 > **系統考古完成。建議下一步：**
-> - 執行 `/sdd` 審查並核准此規格
-> - 執行 `/derive` 從規格推導測試
-> - 審查規格中的 `[Inferred]` 和 `[Unknown]` 標記
+> - 執行 `/sdd` 審查並核准此規格 ⭐ **推薦** — 審查並核准產生的規格
+> - 執行 `/derive` 從規格推導測試 — 從規格推導測試（須先核准）
+> - 審查規格中的 `[Inferred]` 和 `[Unknown]` 標記 — 手動審查不確定性標籤
 
 ## 參考
 
 - 詳細指南：[guide.md](./guide.md)
 - 核心規範：[reverse-engineering-standards.md](../../../../core/reverse-engineering-standards.md)
+
+## AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/reverse`](../commands/reverse.md#ai-agent-behavior--ai-代理行為)