universal-dev-standards 5.11.0 → 5.13.2

package/bundled/core/self-review-protocol.md

@@ -0,0 +1,160 @@
+# Self-Review Protocol
+
+> **English** | [繁體中文](../locales/zh-TW/core/self-review-protocol.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-05-26
+**Applicability**: All software projects (new, refactoring, migration, maintenance)
+**Scope**: partial
+**Industry Standards**: ISO/IEC 25010 (Documentation maintainability), IEEE 1063-2001 (Software user documentation)
+**References**: Inspired by code review practices from Google Engineering Practices; specialized for large markdown artefact editing
+
+---
+
+## Purpose
+
+This standard mandates a **self-review pass** on large markdown edits before commit, to catch internal cross-reference inconsistencies that internal reasoning routinely misses.
+
+**Relationship to Other Standards**:
+- Complements [code-review.md](code-review.md) which covers code changes
+- Complements [documentation-writing-standards.md](documentation-writing-standards.md) which covers content creation
+- This standard focuses on **post-edit verification** of large markdown documents (DECs, ADRs, XSPECs, SKILL.md, spec documents, runbooks)
+
+---
+
+## Background
+
+Across multiple Claude-assisted editing sessions (e.g., `dev-platform/.claude/skills/eval-source/SKILL.md` v1.1.0 → v1.1.1 and v1.2.0 → v1.2.1), a consistent pattern emerged: **each large markdown edit introduced 3-6 small internal inconsistencies** that were invisible to internal reasoning but surfaced immediately on full re-read.
+
+These inconsistencies fell into **6 recurring categories** and consistently triggered a follow-up patch commit. Adding a mandatory re-read step before commit eliminated this pattern (eval-source v1.3.0 was the first to pass without follow-up patch).
+
+---
+
+## Trigger Conditions
+
+| Change scale | Self-review required? |
+|---|---|
+| Commit modifies **> 50 lines** of markdown | **Mandatory** |
+| Commit modifies ≤ 50 lines of markdown | Optional (small edits rarely have cross-ref risk) |
+| Code / config only changes | Not applicable (covered by lint / test / code review) |
+
+Applicable artefact types:
+- ADRs (architecture decision records)
+- Cross-project specs (XSPEC) and SDD Deltas
+- SKILL.md (Claude Code custom skills)
+- ARCHITECTURE.md, API.md, DEPLOYMENT.md, MIGRATION.md (long-form project docs)
+- Runbooks, playbooks
+- README.md when modifying major sections
+
+---
+
+## The 6 Categories of Internal Inconsistency
+
+### 1. Diagram / Flow vs Step List Mismatch
+**Example**: A workflow diagram with 7 boxes but the document defines 8 steps.
+**Check**: Count nodes in every diagram and compare against `## Step N:` / `## N.` headers.
+
+### 2. Changelog Reference Errors
+**Example**: Changelog entry says "Step 1 added X" but X was actually added at Step 0.
+**Check**: For each changelog line, grep the anchor it references to verify location.
+
+### 3. Count Drift
+**Example**: Document says "self-audit has 4 questions" but the actual list now has 7.
+**Check**: grep for explicit numbers (`N questions`, `N rows`, `N items`) and verify against actual count.
+
+### 4. Stale Templates
+**Example**: A commit template hardcodes `Claude Sonnet 4.6` when the actual model varies.
+**Check**: Find hardcoded model names, tool versions, dates; replace with placeholders or update.
+
+### 5. Wrong Tool / Command References
+**Example**: Document recommends `claude --version` to get the model name, but that command only shows CLI version.
+**Check**: For each CLI command mentioned, mental check or `which X` / `--help` verification.
+
+### 6. Placeholder vs Rule Misalignment
+**Example**: A template example shows `D1/D2/D3` but the rule explicitly says D3 is not mandatory, and the present case specifically demoted its D3.
+**Check**: Every concrete value in examples must be consistent with current rules; examples should not contradict latest case experience.
+
+---
+
+## Procedure
+
+1. **After editing, before committing**, use the file-reading tool to re-read the **entire file** (not just the diff).
+2. Walk through the 6 categories above against the file.
+3. **If issues found**: Edit in place and include fixes in the same commit (don't ship and patch later).
+4. **If already committed** before noticing: Create a patch commit (e.g., v1.2.1 fixing v1.2.0).
+
+---
+
+## Recording the Self-Review Result
+
+The recording format depends on the artefact type:
+
+### For SKILL.md
+Append a changelog line in the format:
+```
+> **v{X.Y.(Z+1)} Self-review pass {YYYY-MM-DD}**: {N} issues found, {M} fixed in same commit; or "0 issues found".
+```
+
+### For ADRs / DECs
+In the `## Follow-up Tracking` table, add a row:
+```
+| Self-review pass | This DEC | ✅ YYYY-MM-DD (6 categories, no issues) |
+```
+
+### For XSPEC SDD Deltas
+After the "non-modification list" section (e.g., §N.6), append:
+```
+> Self-review pass: YYYY-MM-DD (6 categories, no issues)
+```
+
+### In Commit Message Body
+Append a single line at the end:
+```
+Self-review (protocol v1.0.0): N issues found, M applied in same commit / 0 found.
+```
+
+---
+
+## Distinction from Other Review Practices
+
+| Practice | Covers | Trigger |
+|---|---|---|
+| **Code Review** ([code-review.md](code-review.md)) | Code correctness, design, security | Before merging code PR |
+| **Content Self-Audit** (e.g., eval-source skill's 7-question audit) | Content completeness (did we include all required sections?) | Each artefact creation |
+| **Self-Review Protocol** (this standard) | Internal cross-reference consistency (form, not content) | After large markdown edit, before commit |
+| **Peer Review** | Independent perspective, blast radius assessment | Significant changes |
+
+The three review layers are complementary:
+- **Content audit** asks: *Did I include everything required?*
+- **Self-review** asks: *Are the parts I included internally consistent?*
+- **Peer review** asks: *Does the change make sense from another perspective?*
+
+---
+
+## Anti-Patterns to Avoid
+
+1. **Skipping self-review because "the diff looks small"** — small diffs in large files often introduce cross-ref errors elsewhere.
+2. **Doing self-review on the diff only** — must re-read the **whole file** because cross-ref errors may live in unchanged sections that reference changed content.
+3. **Documenting the protocol but not following it** — the discipline is in the practice, not the documentation.
+4. **Treating self-review as a substitute for peer review** — self-review catches inconsistencies, not design flaws.
+
+---
+
+## Verification
+
+Adoption of this standard is verified by:
+
+- **Patch commit ratio**: After adopting, the ratio of `v1.X.0 → v1.X.1` follow-up patches for the same artefact should drop significantly (eval-source went from 100% before v1.3.0 to 0% after).
+- **Issue surface time**: Issues caught by self-review (before commit) vs. issues caught by next reader (after commit) — the former should grow, the latter shrink.
+
+---
+
+## Examples in the Wild
+
+- **dev-platform** `eval-source` skill v1.3.0 — first SKILL.md edit to pass self-review pre-commit (commit `6b45c5d`); preceded by 2 patch cycles (v1.1.0→v1.1.1 with 3 issues, v1.2.0→v1.2.1 with 6 issues) that motivated this standard.
+
+---
+
+## Self-Review Pass
+
+> Self-review pass: 2026-05-26 (6 categories, no issues found on the first draft of this standard itself)

package/bundled/locales/zh-CN/CHANGELOG.md

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 5.11.0
-translation_version: 5.11.0
-last_synced: 2026-05-14
+source_version: 5.13.2
+translation_version: 5.13.2
+last_synced: 2026-05-26
 status: current
 ---
 
@@ -17,6 +17,71 @@ status: current
 
 ## [Unreleased]
 
+## [5.13.2] - 2026-05-26
+
+### 修复
+- **`.github/workflows/publish.yml` Clean-room Install Test（XSPEC-221 hotfix v2）**：将 `uds init --dry-run`（CLI 未实作此 option）换成 `uds init --help` 作为安全的 non-mutating 验证。v5.13.1 publish 失败时 surface — 错误讯息 `error: unknown option '--dry-run'`。gate 第二次自我 bug 被抓出；gate 经此次端对端验证。
+
+## [5.13.1] - 2026-05-26 [PUBLISH 失败 — 见 5.13.2]
+
+### 修复
+- **`.github/workflows/publish.yml` Clean-room Install Test（XSPEC-221 hotfix）**：在 alpine clean-room job 的 `npm install -g .` 之前新增 `npm ci --ignore-scripts` 步骤。
+
+## [5.13.0] - 2026-05-26
+
+### 新增
+- **`core/self-review-protocol.md` v1.0.0**（含 `ai/standards/self-review-protocol.ai.yaml`、`locales/zh-TW/core/self-review-protocol.md`、`cli/standards-registry.json` 注册项）：新标准，要求**大型 markdown 编辑（> 50 行）commit 前必跑 self-review**。明列 **6 类内部 cross-reference 不一致** — diagram/step 不同步、changelog 编号错位、计数错位、stale 模板、错误工具引用、placeholder 与 rule 不对齐 — 并附具体检查方法。与 code review（代码）、内容自我审计（完整性）、同侪审查（设计）三者分工互补。观察源：下游 skill 编辑出现的 `v1.X→v1.X.1` patch 惯性。
+- **`scripts/pre-release-check.sh` Step 22.5 — CHANGELOG hard gate**：当 `CHANGELOG.md [Unreleased]` 为空时拒绝发版。新增 `--skip-changelog` flag 提供 escape valve（发版 commit message 须注明理由）。插在 flow gate（step 22）与 dogfooding gate（step 23）之间。
+- **`scripts/pre-commit.mjs` Step 1.5 — CHANGELOG drift advisory**：当 staged commit 改 substantive source（`core/`、`ai/standards/`、`cli/src`、`cli/bin`、`scripts/`、`skills/*/SKILL.md`、`.github/workflows/`）但没 stage `CHANGELOG.md` 时，黄色 warning（不挡 commit，exit 0）。讯息指向 release-time hard gate 让使用者知道忽略警告的后果。
+- **`.github/workflows/release-reminder.yml`**：每周一 09:00 UTC cron，当 `CHANGELOG.md [Unreleased]` 非空 **且** 距离 latest semver tag ≥ 7 天时，开或更新标 `release-reminder` + `auto-generated` 的 issue。条件不再满足时（发完版或 [Unreleased] 清空）自动 close。内建 semver bump heuristic（依条目内容推 major/minor/patch）。
+- **`scripts/check-skill-structural-integrity.ts`**（XSPEC-223，P1 发版 gate）：验证 skill `SKILL.md` 结构完整性（frontmatter 字段、必要 section）。串接到 `pre-release-check.sh` step 18.5；任何 skill 结构不全则挡发版。
+- **`packaging-standards`**（XSPEC-233 / #112）：新增 API migration contract test fixtures section — 定义跨版本 API 迁移相容性测试的 fixture 格式。
+- **Clean-room install gate**（XSPEC-221）于 `.github/workflows/publish.yml`：Alpine Node 20 容器跑 `npm install -g .`（从 `cli/`），验证 `uds --version` / `uds list` / `uds init --dry-run`。任何步骤失败则挡 `publish` job。
+- **Dogfooding gate**（XSPEC-222）— `scripts/pre-release-check.sh` step 23：新 CLI build 必须能跑 `uds check` 通过自身验证才能发版。
+
+### 变更
+- **`core/deployment-standards.md`**（XSPEC-231 / #110 + #113）：部署防御性配对 — 强制归档格式验证 + 解压-验证-才删除 模式。关闭「压缩档损毁但先被删除」失败类别。
+- **`core/logging-standards.md`**（XSPEC-232 / #111）：强制双触发日志轮替策略 — size **AND** time 两种触发都必须配置（非 OR）。关闭「size 门槛未达所以轮替从未触发」失败模式。
+- **`skills/contract-test-assistant/SKILL.md`** 与 **`skills/runbook-assistant/SKILL.md`**：配合 XSPEC-231/232/233 模式的小幅更新。
+- **依赖升级（`cli/`）**：`lint-staged` 17.0.3→17.0.4（#107）、`@inquirer/prompts` 8.4.2→8.4.3（#106）、`eslint` 10.3.0→10.4.0（#105）、`@vitest/coverage-v8` 4.1.5→4.1.6（#103）、`vitest` 4.1.5→4.1.6（#101）、`@commitlint/cli` 21.0.0→21.0.1（#104）、`tsx` 4.21.0→4.22.3（#109）。
+- **CI actions**：`actions/checkout` 4→6（#98）、`actions/setup-node` 4→6（#99）。
+
+## [5.12.1] - 2026-05-19
+
+### 变更
+- **`full-coverage-testing.ai.yaml`**（`no-tautology-assertions` 规则，XSPEC-220）：AI agent 生成未实作测试骨架时，**必须**使用 `it.todo("AC-XXX: ...")`，禁止使用含 `expect(true).toBe(true)` 的 `it()` callback——无论由人类或 AI agent 生成，均视为 `[ANTI-FAKE-001]` 违规。
+- **`test-governance.ai.yaml`**（`gate-wiring-required` 规则，XSPEC-220）：品质侦测脚本（anti-fake、stub-check、coverage ratchet）**必须**同时出现在至少一个 CI workflow job 与至少一个 local hook。脚本存在于 `scripts/` 但从未被 CI 呼叫，等同不存在，视为治理缺口。
+- **`acceptance-criteria-traceability.ai.yaml`**（`not_implemented` 状态，XSPEC-220）：明确定义 `it.todo()` 占位符对应 `not_implemented 🚫` 状态（不计入覆盖率分母），补充决策树区分 `not_implemented`（有意识标记）与 `uncovered`（遗漏）。
+
+## [5.12.0] - 2026-05-16
+
+### 新增
+- **`docs/user/` 用户文档体系**（XSPEC-211）：新增双轨文档结构，仿照 VibeOps 惯例，包含 8 份文档：
+  - `docs/user/GETTING-STARTED.md` — 5 分钟端到端教程（install → `uds init` → `/sdd` → `/commit`）
+  - `docs/user/SKILLS-INDEX.md` — 自动生成的 54 个 skill 索引，按 Tier（DEC-061）与 Category 分类，含「触发时机速查」表
+  - `docs/user/COMMANDS-INDEX.md` — 自动生成的 48 个 slash command 字母序列表，含 skill 对应
+  - `docs/user/FAQ.md` — 14 题常见问题（安装、skill、SDD、升级、架构）
+  - `docs/user/GLOSSARY.md` — UDS、SDD、ATDD、BDD、TDD、XSPEC、Dual-Layer、Skill Tier、Standard、Activity、Bundle/Source、ADR、AC 等术语定义
+  - `docs/user/TROUBLESHOOTING.md` — 问题→解法指南，整合 `SKILL-FALLBACK-GUIDE.md` 内容
+  - `docs/user/README.md` — 三类受众入口（新手 / 日常用户 / 维护者）+ 文档地图
+  - `docs/user/CHEATSHEET.md` — 从 `docs/` 移入（内容不变）
+- **`scripts/generate-skill-index.ts`** — 从 `uds-manifest.json` + `skills/*/SKILL.md` frontmatter 生成 SKILLS-INDEX.md 与 COMMANDS-INDEX.md。执行：`npm run docs:generate-index`
+- **`scripts/check-skill-index.ts`** — pre-commit 守门；重生成后 diff，不同步则 exit 非零。执行：`npm run docs:check-index`
+- **`scripts/setup-hooks.sh`** — 安装 `.git/hooks/pre-commit`，每次 commit 自动调用 `docs:check-index`
+- **`.github/workflows/docs-check.yml`** — CI job：PR 修改 manifest/SKILL.md/registry 时验证 INDEX 文档已同步
+- **`docs/reference/FEATURE-REFERENCE.md`** — FEATURE-REFERENCE.md 从 `docs/` 迁移至 `docs/reference/`（自动生成，内容不变）
+- **`docs/archive/USER-MANUAL-2026-03-24.md`** — 已废弃 User Manual 的归档备份
+
+### 变更
+- **`package.json`**：新增 `docs:generate-index` 与 `docs:check-index` npm scripts
+- **`scripts/generate-usage-docs.mjs`**：更新英文输出路径（FEATURE-REFERENCE → `docs/reference/`，CHEATSHEET → `docs/user/`）
+- **`skills/README.md`**：新增 banner 指向 `docs/user/SKILLS-INDEX.md` 与 `COMMANDS-INDEX.md`
+- **`README.md`**：Quick Start 段落新增「📚 Documentation」表格，列出 7 份 `docs/user/` 文档直链
+- **`docs/USER-MANUAL.md`**：新增 deprecation banner 指向 `docs/user/README.md`；归档备份保留于 `docs/archive/`
+
+### 移除
+- **`docs/SKILL-FALLBACK-GUIDE.md`**：内容已整合至 `docs/user/TROUBLESHOOTING.md`。非 Claude Code 工具的 fallback 策略与 Skill→Core Standard 对应表保留于「Using UDS Without Claude Code」段落
+
 ## [5.11.0] - 2026-05-14
 
 ### 新增 / Added

package/bundled/locales/zh-CN/README.md

@@ -14,7 +14,7 @@ status: current
 
 > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
 
-**版本**: 5.11.0 | **发布日期**: 2026-05-14 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 5.13.2 | **发布日期**: 2026-05-26 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
 
 语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流，确保不同技术栈之间的一致性、质量和可维护性。
 
@@ -63,7 +63,7 @@ npx universal-dev-standards init
 <!-- UDS_STATS_TABLE_START -->
 | 类别 | 数量 | 说明 |
 |----------|-------|-------------|
-| **核心标准** | 125 | 通用开发准则 |
+| **核心标准** | 127 | 通用开发准则 |
 | **AI Skills** | 54 | 互动式技能 |
 | **斜线命令** | 48 | 快速操作 |
 | **CLI 命令** | 6 | list, init, configure, check, update, skills |

package/bundled/locales/zh-CN/SECURITY.md

@@ -13,7 +13,7 @@ status: current
 <!-- UDS_SUPPORTED_VERSIONS_START -->
 | 版本 | 支持状态 |
 |------|--------|
-| 5.11.0 | ✅ 最新正式版 |
+| 5.13.0 | ✅ 最新正式版 |
 | < 5.0.0 | ❌ 已终止支持 |
 <!-- UDS_SUPPORTED_VERSIONS_END -->
 

package/bundled/locales/zh-TW/CHANGELOG.md

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 5.11.0
-translation_version: 5.11.0
-last_synced: 2026-05-14
+source_version: 5.13.2
+translation_version: 5.13.2
+last_synced: 2026-05-26
 status: current
 ---
 
@@ -17,6 +17,71 @@ status: current
 
 ## [Unreleased]
 
+## [5.13.2] - 2026-05-26
+
+### 修復
+- **`.github/workflows/publish.yml` Clean-room Install Test（XSPEC-221 hotfix v2）**：將 `uds init --dry-run`（CLI 未實作此 option）換成 `uds init --help` 作為安全的 non-mutating 驗證。v5.13.1 publish 失敗時 surface — 錯誤訊息 `error: unknown option '--dry-run'`。gate 第二次自我 bug 被抓出；gate 經此次端對端驗證。
+
+## [5.13.1] - 2026-05-26 [PUBLISH 失敗 — 見 5.13.2]
+
+### 修復
+- **`.github/workflows/publish.yml` Clean-room Install Test（XSPEC-221 hotfix）**：在 alpine clean-room job 的 `npm install -g .` 之前新增 `npm ci --ignore-scripts` 步驟。
+
+## [5.13.0] - 2026-05-26
+
+### 新增
+- **`core/self-review-protocol.md` v1.0.0**（含 `ai/standards/self-review-protocol.ai.yaml`、`locales/zh-TW/core/self-review-protocol.md`、`cli/standards-registry.json` 註冊項）：新標準，要求**大型 markdown 編輯（> 50 行）commit 前必跑 self-review**。明列 **6 類內部 cross-reference 不一致** — diagram/step 不同步、changelog 編號錯位、計數錯位、stale 範本、錯誤工具引用、placeholder 與 rule 不對齊 — 並附具體檢查方法。與 code review（程式碼）、內容自我審計（完整性）、同儕審查（設計）三者分工互補。觀察源：下游 skill 編輯出現的 `v1.X→v1.X.1` patch 慣性。
+- **`scripts/pre-release-check.sh` Step 22.5 — CHANGELOG hard gate**：當 `CHANGELOG.md [Unreleased]` 為空時拒絕發版。新增 `--skip-changelog` flag 提供 escape valve（發版 commit message 須註明理由）。插在 flow gate（step 22）與 dogfooding gate（step 23）之間。
+- **`scripts/pre-commit.mjs` Step 1.5 — CHANGELOG drift advisory**：當 staged commit 改 substantive source（`core/`、`ai/standards/`、`cli/src`、`cli/bin`、`scripts/`、`skills/*/SKILL.md`、`.github/workflows/`）但沒 stage `CHANGELOG.md` 時，黃色 warning（不擋 commit，exit 0）。訊息指向 release-time hard gate 讓使用者知道忽略警告的後果。
+- **`.github/workflows/release-reminder.yml`**：每週一 09:00 UTC cron，當 `CHANGELOG.md [Unreleased]` 非空 **且** 距離 latest semver tag ≥ 7 天時，開或更新標 `release-reminder` + `auto-generated` 的 issue。條件不再滿足時（發完版或 [Unreleased] 清空）自動 close。內建 semver bump heuristic（依條目內容推 major/minor/patch）。
+- **`scripts/check-skill-structural-integrity.ts`**（XSPEC-223，P1 發版 gate）：驗證 skill `SKILL.md` 結構完整性（frontmatter 欄位、必要 section）。串接到 `pre-release-check.sh` step 18.5；任何 skill 結構不全則擋發版。
+- **`packaging-standards`**（XSPEC-233 / #112）：新增 API migration contract test fixtures section — 定義跨版本 API 遷移相容性測試的 fixture 格式。
+- **Clean-room install gate**（XSPEC-221）於 `.github/workflows/publish.yml`：Alpine Node 20 容器跑 `npm install -g .`（從 `cli/`），驗證 `uds --version` / `uds list` / `uds init --dry-run`。任何步驟失敗則擋 `publish` job。
+- **Dogfooding gate**（XSPEC-222）— `scripts/pre-release-check.sh` step 23：新 CLI build 必須能跑 `uds check` 通過自身驗證才能發版。
+
+### 變更
+- **`core/deployment-standards.md`**（XSPEC-231 / #110 + #113）：部署防禦性配對 — 強制歸檔格式驗證 + 解壓-驗證-才刪除 模式。關閉「壓縮檔損毀但先被刪除」失敗類別。
+- **`core/logging-standards.md`**（XSPEC-232 / #111）：強制雙觸發日誌輪替策略 — size **AND** time 兩種觸發都必須配置（非 OR）。關閉「size 門檻未達所以輪替從未觸發」失敗模式。
+- **`skills/contract-test-assistant/SKILL.md`** 與 **`skills/runbook-assistant/SKILL.md`**：配合 XSPEC-231/232/233 模式的小幅更新。
+- **依賴升級（`cli/`）**：`lint-staged` 17.0.3→17.0.4（#107）、`@inquirer/prompts` 8.4.2→8.4.3（#106）、`eslint` 10.3.0→10.4.0（#105）、`@vitest/coverage-v8` 4.1.5→4.1.6（#103）、`vitest` 4.1.5→4.1.6（#101）、`@commitlint/cli` 21.0.0→21.0.1（#104）、`tsx` 4.21.0→4.22.3（#109）。
+- **CI actions**：`actions/checkout` 4→6（#98）、`actions/setup-node` 4→6（#99）。
+
+## [5.12.1] - 2026-05-19
+
+### 變更
+- **`full-coverage-testing.ai.yaml`**（`no-tautology-assertions` 規則，XSPEC-220）：AI agent 生成未實作測試骨架時，**必須**使用 `it.todo("AC-XXX: ...")`，禁止使用含 `expect(true).toBe(true)` 的 `it()` callback——無論由人類或 AI agent 生成，均視為 `[ANTI-FAKE-001]` 違規。
+- **`test-governance.ai.yaml`**（`gate-wiring-required` 規則，XSPEC-220）：品質偵測腳本（anti-fake、stub-check、coverage ratchet）**必須**同時出現在至少一個 CI workflow job 與至少一個 local hook。腳本存在於 `scripts/` 但從未被 CI 呼叫，等同不存在，視為治理缺口。
+- **`acceptance-criteria-traceability.ai.yaml`**（`not_implemented` 狀態，XSPEC-220）：明確定義 `it.todo()` 佔位符對應 `not_implemented 🚫` 狀態（不計入覆蓋率分母），補充決策樹區分 `not_implemented`（有意識標記）與 `uncovered`（遺漏）。
+
+## [5.12.0] - 2026-05-16
+
+### 新增
+- **`docs/user/` 使用者文件體系**（XSPEC-211）：新增雙軌文件結構，仿照 VibeOps 慣例，包含 8 份文件：
+  - `docs/user/GETTING-STARTED.md` — 5 分鐘端到端教學（install → `uds init` → `/sdd` → `/commit`）
+  - `docs/user/SKILLS-INDEX.md` — 自動生成的 54 個 skill 索引，依 Tier（DEC-061）與 Category 分類，含「觸發時機速查」表
+  - `docs/user/COMMANDS-INDEX.md` — 自動生成的 48 個 slash command 字母序清單，含 skill 對應
+  - `docs/user/FAQ.md` — 14 題常見問題（安裝、skill、SDD、升級、架構）
+  - `docs/user/GLOSSARY.md` — UDS、SDD、ATDD、BDD、TDD、XSPEC、Dual-Layer、Skill Tier、Standard、Activity、Bundle/Source、ADR、AC 等術語定義
+  - `docs/user/TROUBLESHOOTING.md` — 問題→解法指南，整合 `SKILL-FALLBACK-GUIDE.md` 內容
+  - `docs/user/README.md` — 三類受眾入口（新手 / 日常使用者 / 維護者）+ 文件地圖
+  - `docs/user/CHEATSHEET.md` — 從 `docs/` 移入（內容不變）
+- **`scripts/generate-skill-index.ts`** — 從 `uds-manifest.json` + `skills/*/SKILL.md` frontmatter 生成 SKILLS-INDEX.md 與 COMMANDS-INDEX.md。執行：`npm run docs:generate-index`
+- **`scripts/check-skill-index.ts`** — pre-commit 守門；重生成後 diff，不同步則 exit 非零。執行：`npm run docs:check-index`
+- **`scripts/setup-hooks.sh`** — 安裝 `.git/hooks/pre-commit`，每次 commit 自動呼叫 `docs:check-index`
+- **`.github/workflows/docs-check.yml`** — CI job：PR 修改 manifest/SKILL.md/registry 時驗證 INDEX 文件已同步
+- **`docs/reference/FEATURE-REFERENCE.md`** — FEATURE-REFERENCE.md 從 `docs/` 遷移至 `docs/reference/`（自動生成，內容不變）
+- **`docs/archive/USER-MANUAL-2026-03-24.md`** — 已廢棄 User Manual 的歸檔備份
+
+### 變更
+- **`package.json`**：新增 `docs:generate-index` 與 `docs:check-index` npm scripts
+- **`scripts/generate-usage-docs.mjs`**：更新英文輸出路徑（FEATURE-REFERENCE → `docs/reference/`，CHEATSHEET → `docs/user/`）
+- **`skills/README.md`**：新增 banner 指向 `docs/user/SKILLS-INDEX.md` 與 `COMMANDS-INDEX.md`
+- **`README.md`**：Quick Start 段落新增「📚 Documentation」表格，列出 7 份 `docs/user/` 文件直連
+- **`docs/USER-MANUAL.md`**：新增 deprecation banner 指向 `docs/user/README.md`；歸檔備份保留於 `docs/archive/`
+
+### 移除
+- **`docs/SKILL-FALLBACK-GUIDE.md`**：內容已整合至 `docs/user/TROUBLESHOOTING.md`。非 Claude Code 工具的 fallback 策略與 Skill→Core Standard 對應表保留於「Using UDS Without Claude Code」段落
+
 ## [5.11.0] - 2026-05-14
 
 ### 新增 / Added

package/bundled/locales/zh-TW/README.md

@@ -14,7 +14,7 @@ status: current
 
 > **語言**: [English](../../README.md) | 繁體中文 | [简体中文](../zh-CN/README.md)
 
-**版本**: 5.11.0 | **發布日期**: 2026-05-14 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 5.13.2 | **發布日期**: 2026-05-26 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
 
 語言無關、框架無關的軟體專案文件標準。透過 AI 原生工作流，確保不同技術堆疊之間的一致性、品質和可維護性。
 
@@ -63,7 +63,7 @@ npx universal-dev-standards init
 <!-- UDS_STATS_TABLE_START -->
 | 類別 | 數量 | 說明 |
 |----------|-------|-------------|
-| **核心標準** | 125 | 通用開發準則 |
+| **核心標準** | 127 | 通用開發準則 |
 | **AI Skills** | 54 | 互動式技能 |
 | **斜線命令** | 48 | 快速操作 |
 | **CLI 指令** | 6 | list, init, configure, check, update, skills |

package/bundled/locales/zh-TW/SECURITY.md

@@ -13,7 +13,7 @@ status: current
 <!-- UDS_SUPPORTED_VERSIONS_START -->
 | 版本 | 支援狀態 |
 |------|--------|
-| 5.11.0 | ✅ 最新正式版 |
+| 5.13.0 | ✅ 最新正式版 |
 | < 5.0.0 | ❌ 已終止支援 |
 <!-- UDS_SUPPORTED_VERSIONS_END -->
 

package/bundled/locales/zh-TW/core/self-review-protocol.md

@@ -0,0 +1,158 @@
+# Self-Review Protocol（自我審查協議）
+
+> [English](../../../core/self-review-protocol.md) | **繁體中文**
+
+**版本**: 1.0.0
+**最後更新**: 2026-05-26
+**適用範圍**: 所有軟體專案（新建、重構、遷移、維護）
+**範圍**: partial
+**業界標準**: ISO/IEC 25010（文件可維護性）、IEEE 1063-2001（軟體使用者文件）
+**參考**: 受 Google Engineering Practices 程式碼審查實踐啟發；專為大型 markdown 物件編輯特化
+
+---
+
+## 目的
+
+本標準規範大型 markdown 編輯**commit 前**必跑 **self-review**，捕捉內部 cross-reference 不一致 — 這類問題慣性被內部推理忽略，但完整 re-read 一次即可 surface。
+
+**與其他標準的關係**：
+- 與 [code-review.md](code-review.md) 互補（後者涵蓋程式碼變更）
+- 與 [documentation-writing-standards.md](documentation-writing-standards.md) 互補（後者涵蓋內容創作）
+- 本標準專注於**大型 markdown 文件**（DEC、ADR、XSPEC、SKILL.md、規格文件、runbook 等）的**編輯後驗證**
+
+---
+
+## 背景
+
+多次 Claude 輔助編輯 session（如 `dev-platform/.claude/skills/eval-source/SKILL.md` v1.1.0 → v1.1.1、v1.2.0 → v1.2.1）觀察到一致模式：**每次大型 markdown 編輯都引入 3-6 處小型內部不一致**，內部推理看不出來，但完整 re-read 立刻 surface。
+
+這些不一致歸納為 **6 大類**，且固定觸發後續 patch commit。在 commit 前加入強制 re-read 步驟後，此模式消失（eval-source v1.3.0 為首次無 patch follow-up 的 SKILL.md 變更）。
+
+---
+
+## 觸發條件
+
+| 變更規模 | 是否必跑 self-review？ |
+|---|---|
+| commit 修改 **> 50 行** markdown | **必跑** |
+| commit 修改 ≤ 50 行 markdown | 可選（小修常無 cross-ref 風險）|
+| 純 code / config 變更 | 不適用（另有 lint / test / code review）|
+
+適用文件類型：
+- ADR（架構決策記錄）
+- 跨專案規格（XSPEC）與 SDD Delta
+- SKILL.md（Claude Code 自訂 skill）
+- ARCHITECTURE.md、API.md、DEPLOYMENT.md、MIGRATION.md 等長型專案文件
+- Runbook、playbook
+- README.md（修改主要 section 時）
+
+---
+
+## 6 類常見內部不一致
+
+### 1. Diagram / Flow 與 step list 不同步
+**範例**：工作流程圖 7 格但文件實際定義 8 步驟
+**檢查**：數每個 diagram 節點數量 vs `## Step N:` / `## N.` heading
+
+### 2. Changelog 引用編號錯位
+**範例**：Changelog 寫「Step 1 新增 X」但 X 實際在 Step 0
+**檢查**：對每條 changelog 描述，grep 其引用的 anchor 位置
+
+### 3. 計數錯位
+**範例**：文件說「自我審計 4 題」但實際 list 有 7 題
+**檢查**：grep 「N 題」「N 列」「N 點」等明確數字並對照實際 count
+
+### 4. Stale 範本
+**範例**：commit 範本寫死 `Claude Sonnet 4.6` 但實際模型隨環境變動
+**檢查**：找硬編碼的模型名、工具版本、日期；改為 placeholder 或更新
+
+### 5. 錯誤工具 / 命令引用
+**範例**：建議用 `claude --version` 取得模型名，但該命令只顯示 CLI 版本
+**檢查**：對每個提及的 CLI 命令做 mental check 或 `which X` / `--help` 驗證
+
+### 6. Placeholder 與 rule 不對齊
+**範例**：example 寫「D1/D2/D3」但 rule 明說 D3 不強制，且當前案例正好把 D3 降為後續追蹤
+**檢查**：example 中每個具體值是否與當前 rule 一致；example 不應與最新案例經驗矛盾
+
+---
+
+## 流程
+
+1. **edit 完成後、commit 前**，用 file-reading 工具重新讀過**完整檔案**（不只 diff）
+2. 依上方 6 類逐項對照
+3. **發現問題** → 直接 Edit 修補後再 commit（同一 commit 包含修正，不要分開 ship）
+4. **若已 commit 才發現** → 新增 patch commit（如 v1.2.1 對 v1.2.0）
+
+---
+
+## 紀錄格式（按文件類型）
+
+### SKILL.md
+在 frontmatter 附近 changelog 追加一行：
+```
+> **v{X.Y.(Z+1)} Self-review pass {YYYY-MM-DD}**：找到 {N} 處 issue，{M} 處於同 commit 修正；或「0 issues found」
+```
+
+### ADR / DEC
+在 `## 後續追蹤` 表格新增一行：
+```
+| Self-review pass | 本 DEC | ✅ YYYY-MM-DD (6 類無 issue) |
+```
+
+### XSPEC SDD Delta
+在「不改動清單」section（如 §N.6）後追加：
+```
+> Self-review pass: YYYY-MM-DD (6 類無 issue)
+```
+
+### Commit message body
+最後一行附：
+```
+Self-review (protocol v1.0.0): N issues found, M applied in same commit / 0 found.
+```
+
+---
+
+## 與其他審查實踐的區別
+
+| 實踐 | 涵蓋面向 | 觸發時機 |
+|---|---|---|
+| **Code Review**（[code-review.md](code-review.md)）| 程式碼正確性、設計、安全 | code PR merge 前 |
+| **內容自我審計**（如 eval-source skill 7 題）| 內容完整性（是否包含所有必要 section）| 每次文件產出 |
+| **Self-Review Protocol**（本標準）| 內部 cross-reference 一致性（形式，非內容）| 大型 markdown 編輯後、commit 前 |
+| **同儕審查** | 獨立視角、blast radius 評估 | 重要變更 |
+
+三層審查互補：
+- **內容審計** 問：*是否包含所有必要的部分？*
+- **Self-review** 問：*包含的部分內部一致嗎？*
+- **同儕審查** 問：*從另一個角度看，這個變更合理嗎？*
+
+---
+
+## 反模式
+
+1. **因為「diff 看起來不大」就跳過 self-review** — 大檔案的小 diff 常引入其他位置的 cross-ref 錯誤
+2. **只 review diff 而非整檔** — cross-ref 錯誤可能在未變動的 section 中（引用了已變動內容）
+3. **記錄 protocol 但不執行** — 紀律在於實踐，不在於文件本身
+4. **把 self-review 當 peer review 的替代品** — self-review 抓不一致，不抓設計缺陷
+
+---
+
+## 驗證
+
+採納本標準的驗證方式：
+
+- **Patch commit 比例**：採納後，同一物件 `v1.X.0 → v1.X.1` 後續 patch 比例應顯著下降（eval-source 從 v1.3.0 前的 100% 降至之後的 0%）
+- **Issue surface 時間**：self-review 抓到的 issue（pre-commit）vs 下一個 reader 抓到的 issue（post-commit）— 前者應上升、後者應下降
+
+---
+
+## 實踐案例
+
+- **dev-platform** `eval-source` skill v1.3.0 — 首次 SKILL.md 變更在 commit 前 self-review pass（commit `6b45c5d`）；前有兩次 patch 週期（v1.1.0→v1.1.1 3 處、v1.2.0→v1.2.1 6 處）促成本標準誕生
+
+---
+
+## Self-Review Pass
+
+> Self-review pass: 2026-05-26 (6 類無 issue；本標準首稿同步 self-review)

package/bundled/skills/README.md

@@ -4,6 +4,9 @@ This directory contains the reference implementations of Universal Development S
 
 > Derived from [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards) core standards.
 
+> **For the full indexed skill list** (by Tier, Category, and use case), see **[docs/user/SKILLS-INDEX.md](../docs/user/SKILLS-INDEX.md)** (auto-generated).
+> For slash command reference, see **[docs/user/COMMANDS-INDEX.md](../docs/user/COMMANDS-INDEX.md)**.
+
 ## Directory Structure
 
 ```

package/bundled/skills/contract-test-assistant/SKILL.md

@@ -91,6 +91,13 @@ ASSESS ──► CHOOSE ──► DEFINE ──► IMPLEMENT ──► VERIFY
 | `/api-design` | Define API contracts during design | 設計時定義 API 合約 |
 | `/ci-cd` | Add contract verification to pipeline | 管線中加入合約驗證 |
 | `/testing` | Contract tests as part of test strategy | 合約測試作為測試策略一部分 |
+| `/migrate` | Capture legacy response fixtures during API migration; verify new impl preserves structural equivalence | API 遷移時捕獲 legacy response fixture，驗證新實作保持結構性等價 |
+
+### Migration Contract Tests — When Replacing an Implementation | 遷移合約測試（替換實作時）
+
+When migrating an API endpoint from one tech stack to another (PHP → .NET, Express → Spring, etc.), a contract test against a **legacy reference fixture** catches missing fields, renamed fields, and placement drift that unit tests on the new DTO cannot. See [migration-assistant § API Migration Contract Tests](../migration-assistant/SKILL.md#api-migration-contract-tests--api-遷移合約測試) for the fixture capture protocol and audit checklist.
+
+當 API endpoint 從一個技術棧遷至另一個（PHP → .NET、Express → Spring 等），對 **legacy 參考 fixture** 的 contract test 可捕捉「缺漏欄位」「rename」「層級漂移」等新 DTO 單元測試無法覆蓋的缺陷。詳見 [migration-assistant § API Migration Contract Tests](../migration-assistant/SKILL.md#api-migration-contract-tests--api-遷移合約測試)。
 
 ## Next Steps Guidance | 下一步引導
 

package/bundled/skills/deploy-assistant/SKILL.md

@@ -170,6 +170,8 @@ After `/deploy` completes, the AI assistant should suggest:
 
 - Core standard: [no-cicd-deployment.md](../../core/no-cicd-deployment.md)
 - Core standard: [deployment-standards.md](../../core/deployment-standards.md)
+- Core standard: [deployment-standards.md § Defensive Deployment Ordering](../../core/deployment-standards.md#defensive-deployment-ordering) — **MANDATORY** extract-verify-then-delete sequence for destructive updates / **強制**遵循 extract-verify-then-delete 順序
+- Core standard: [packaging-standards.md § Archive Format Integrity](../../core/packaging-standards.md#archive-format-integrity) — verify archive format before consuming / 消費 archive 前先驗證格式
 - Related: [ci-cd-assistant](../ci-cd-assistant/SKILL.md) — For environments WITH CI/CD
 
 ## Version History | 版本歷史

package/bundled/skills/logging-guide/SKILL.md

@@ -11,8 +11,8 @@ description: |
 
 > **Language**: English | [繁體中文](../../locales/zh-TW/skills/logging-guide/SKILL.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2025-12-30
+**Version**: 1.1.0
+**Last Updated**: 2026-05-26
 **Applicability**: Claude Code Skills
 
 ---
@@ -206,6 +206,21 @@ logger.error('Failed to process order', {
 - Aggregate metrics instead of individual logs
 - Use separate log streams
 
+## Log File Rotation
+
+File-based log sinks **MUST** set **both** rotation triggers — time-based **and** size-based. Default size caps in popular libraries (Serilog 1 GB, log4j/Winston/Python `RotatingFileHandler` no cap) cause silent data loss in production.
+
+```
+✓ rollingInterval: Day                    # time-based
+✓ fileSizeLimitBytes: 104857600 (100 MB)  # size-based
+✓ rollOnFileSizeLimit: true               # roll, do NOT drop
+✓ retainedFileCountLimit: ≥ N*7           # N = max rolls/day
+```
+
+When a log file reaches **≥ 90% of `fileSizeLimitBytes`** at expected end-of-day, **investigate the noise root cause** (noisy retry loop / unbounded debug logging / stack-trace flood) before raising the cap.
+
+> Full specification with per-language recipes (.NET Serilog / Python / Java log4j2 / Node Winston) and the real-incident failure-mode reference: see [Log File Rotation Policy](../../core/logging-standards.md#log-file-rotation-policy) in the core standard.
+
 ## Checklist
 
 ### Required Fields
@@ -224,6 +239,13 @@ logger.error('Failed to process order', {
 - [ ] Credit cards never logged
 - [ ] Retention policies configured
 
+### Rotation
+
+- [ ] Time-based rotation set (`rollingInterval: Day` or equivalent)
+- [ ] Size-based rotation set (`fileSizeLimitBytes` + `rollOnFileSizeLimit: true`)
+- [ ] `retainedFileCountLimit` ≥ N×7 (N = max rolls/day)
+- [ ] 90% size SOP defined (investigate noise, do not just raise cap)
+
 ---
 
 ## Configuration Detection
@@ -283,6 +305,7 @@ After `/logging` completes, the AI assistant should suggest:
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1.0 | 2026-05-26 | Added: Log File Rotation section with cross-link to core standard rotation policy; Rotation checklist (XSPEC-232) |
 | 1.0.0 | 2025-12-30 | Initial release |
 
 ---