universal-dev-standards 6.0.0 → 6.1.0

package/bundled/ai/options/commit-message/bilingual.ai.yaml

@@ -4,7 +4,7 @@
 id: bilingual
 meta:
   parent: commit-message
-  version: "1.0.0"
+  version: "1.1.0"
   description: Bilingual format for mixed teams
 
 best_for:
@@ -92,6 +92,15 @@ rules:
       Never omit the Chinese body section.
     priority: required
 
+  - id: mid-conversation-language-drift-check
+    trigger: AI assistant switching from heavy non-target-language content (code, logs, English docs) back to user-facing prose in a long conversation
+    instruction: |
+      Before writing the next user-facing paragraph, confirm it will be in
+      the target bilingual language without waiting for the user to point
+      out drift. If the user has already flagged drift, correct immediately
+      in the next response — do not repeat apologies or delay the fix.
+    priority: recommended
+
 anti_patterns:
   - id: mixed-language-body
     description: Mixing English and Chinese in the same paragraph
@@ -119,6 +128,15 @@ anti_patterns:
 
       Closes #123
 
+  - id: language-drift-unnoticed
+    description: AI assistant keeps replying in a non-target language after processing heavy non-target-language content, only correcting after repeated user complaints
+    bad_example: |
+      [long conversation with heavy English code/log excerpts]
+      Assistant: "Let's proceed to the next 단계..." (drifted, no self-check)
+    good_example: |
+      [long conversation with heavy English code/log excerpts]
+      Assistant self-checks before replying, then continues in the target language without being asked: "接下來我們處理下一步驟..."
+
 examples:
   simple: "feat(auth): Add login form. 新增登入表單."
   with_body: |

package/bundled/ai/standards/checkin-standards.ai.yaml

@@ -12,8 +12,8 @@ standard:
     - "Documentation: docs updated, CHANGELOG updated"
 
   meta:
-    version: "2.1.0"
-    updated: "2026-06-18"
+    version: "2.2.0"
+    updated: "2026-07-09"
     source: core/checkin-standards.md
     description: Quality gates that must be passed before committing code
 
@@ -128,7 +128,7 @@ standard:
       priority: required
     - id: test-before-commit
       trigger: before committing
-      instruction: Run all test suites locally, review coverage
+      instruction: Run all relevant tests locally (directly exercised code plus tests affected by the change; use test impact analysis tooling if the project has it), review coverage. When scope is unclear or the change touches shared/core paths, run the full suite instead.
       priority: required
     - id: no-wip-commits
       trigger: writing commit message

package/bundled/ai/standards/documentation-writing-standards.ai.yaml

@@ -3,7 +3,7 @@
 
 id: documentation-writing-standards
 meta:
-  version: "1.1.0"
+  version: "1.2.0"
   updated: "2026-03-17"
   source: core/documentation-writing-standards.md
   description: Documentation requirements based on project types (enhanced ADR, LLM writing, quality metrics, translation-friendly)

package/bundled/ai/standards/frontend-design-standards.ai.yaml

@@ -1,17 +1,20 @@
 # Frontend Design Standards - AI Optimized
 # Source: core/frontend-design-standards.md
 # Based on: DEC-029 (awesome-design-md, MIT), DEC-030 (OpenAI Frontend Guide)
-# Version: 1.0.0
+# Version: 1.1.0
 
 id: frontend-design-standards
 meta:
-  version: "1.0.0"
-  updated: "2026-04-13"
+  version: "1.1.0"
+  updated: "2026-07-10"
   source: core/frontend-design-standards.md
   description: |
     DESIGN.md 前端設計標準：9 段結構、語義色彩 token、字體角色、
     間距比例、UI 硬性約束與 anti-pattern 清單。
     適用所有含前端介面的專案。
+    v1.1.0 新增選填擴充：YAML frontmatter token 註冊表 +
+    {category.token} 內插語法 + components 結構化綁定
+    （借鑑 DEC-029 上游演化，Trial，不影響既有 5-token 治理收斂）。
 
 # DESIGN.md 必填 9 段結構
 design_md_sections:
@@ -78,6 +81,24 @@ design_md_sections:
     description: "AI Agent 快速讀取的設計意圖摘要"
     required_fields: [style_summary, key_constraints, tone]
 
+# 選填擴充：token 內插語法 + 結構化 components 綁定（v1.1.0，Trial）
+# 不影響上方 5-token/4-role/7-step 治理收斂；是既有 token 的機器可解析層，非新增 token 的許可證。
+optional_extensions:
+  token_interpolation:
+    status: optional_trial
+    description: "DESIGN.md 可選填 YAML frontmatter 宣告 colors/typography/rounded/spacing token 字典，正文用 {category.token} 語法引用"
+    frontmatter_keys: [colors, typography, rounded, spacing]
+    syntax: "{category.token}"
+    rule: "frontmatter 的 colors 必須對應 5 個必要語義 token；引用不存在的 category.token 視為驗證錯誤，非靜默 fallback"
+  structured_components:
+    status: optional_trial
+    description: "Section 4（Component Styling）可選填 components: 區塊，把元件綁定到 {category.token} 引用"
+    rule: "components: 區塊內每個值都必須是 {category.token} 引用，禁止直接寫 hex/px 原始值"
+  not_adopted:
+    - "不隨附 lint CLI（上游有獨立 @google/design.md npm 套件，本標準不綁定特定驗證工具）"
+    - "不做框架專屬匯出格式（React/Vue/CSS-in-JS 產生器）"
+    - "不擴增 5/4/7 token 數量（內插語法讓既有 token 可引用，不是加 token 的理由）"
+
 # 語義色彩 5 個必要 token
 semantic_color_tokens:
   required:
@@ -265,6 +286,15 @@ rules:
       禁止將首頁設計成 Dashboard Grid。
     priority: required
 
+  - id: respect-token-interpolation-if-present
+    trigger: "當 DESIGN.md 含 YAML frontmatter token 註冊表時（v1.1.0 選填擴充）"
+    instruction: |
+      解析 {category.token} 引用時一律對照 frontmatter 實際值，
+      不得憑記憶或猜測填入色值/尺寸。
+      引用不存在的 category.token 視為錯誤，向使用者回報而非靜默略過。
+      若 DESIGN.md 沒有 frontmatter，此規則不適用（擴充為選填，非強制）。
+    priority: recommended
+
 # 快速參考表
 quick_reference:
   semantic_tokens:

package/bundled/ai/standards/push-standards.ai.yaml

@@ -1,7 +1,7 @@
 id: push-standards
 meta:
-  version: "1.0.0"
-  updated: "2026-04-23"
+  version: "1.1.0"
+  updated: "2026-07-09"
   source: skills/push/SKILL.md
   description: "Git push safety gates, protected branch detection, force-push guardrails, and push receipt audit trail"
 
@@ -14,6 +14,14 @@ config:
     default: ["lint", "test"]
     optional: ["ac-coverage", "type-check", "security-scan"]
     description: "Quality gates to run before pushing"
+    test_scope:
+      default: "full"
+      choices: ["full", "changed"]
+      description: >-
+        "changed" runs only the diff-affected test subset via the project's
+        test impact analysis tooling (e.g. `vitest --changed`), if configured.
+        Fast local pre-check only — never a substitute for the project's own
+        CI/full-suite run, which remains the authoritative gate.
 
   receipt:
     output:
@@ -58,7 +66,10 @@ rules:
     instruction: |
       Run all configured push_gates in sequence:
       - lint: run project lint command (from uds.project.yaml or detected)
-      - test: run project test command
+      - test: run project test command, respecting config.push_gates.test_scope —
+        "full" (default) runs the complete suite; "changed" runs only the
+        diff-affected subset via the project's test impact tooling if configured.
+        A "changed" pre-check does not replace the project's CI/full-suite run.
       If any gate fails: abort push, display which gate failed, suggest fix.
       If --skip-gates flag: run push without gates, mark gates_skipped: true in receipt.
 

package/bundled/ai/standards/requirement-engineering.ai.yaml

@@ -3,10 +3,14 @@
 
 id: requirement-engineering
 meta:
-  version: "1.0.0"
-  updated: "2026-01-13"
+  version: "1.1.0"
+  updated: "2026-07-10"
   source: methodologies/guides/requirement-engineering-guide.md
-  description: Requirements engineering lifecycle, elicitation, specification, and validation standards
+  description: |
+    Requirements engineering lifecycle, elicitation, specification, and validation standards.
+    v1.1.0 adds checklist_generation: dynamic per-spec CHK### quality checklist
+    (5 dimensions, source-traceability tags), operationalizing the existing
+    static Validation Checklist / IEEE 830 quality_characteristics below.
 
 # Reference Standards
 references:
@@ -118,6 +122,41 @@ srs_structure:
     - Modifiable (easy to change)
     - Traceable (origin and implementation linkable)
 
+# 需求品質檢核清單生成（spec-kit /checklist 借鑑，2026-07-10 回頭對齊評估新增）
+# 把上方 srs_structure.quality_characteristics（IEEE 830 8 大品質特性）從靜態參考文字
+# 操作化成可對特定 spec 動態產生的逐項檢核清單——不是「作者自我檢查一次」的固定清單，
+# 是「這份 spec 本身夠不夠完整/清楚/一致/可量測/可追溯」的單元測試。
+checklist_generation:
+  format: "CHK### [dimension] <yes/no question about the spec's own quality> [tag(s)]"
+  append_only: true
+  dimensions:
+    - id: completeness
+      maps_to: Complete (IEEE 830)
+      checks_for: "遺漏的情境、未處理的邊界案例、未記載的 NFR"
+    - id: clarity
+      maps_to: Unambiguous (IEEE 830)
+      checks_for: "模糊詞彙（appropriate/fast/user-friendly）、未定義代名詞"
+    - id: consistency
+      maps_to: Consistent (IEEE 830)
+      checks_for: "spec 內部或跨 spec 的矛盾陳述"
+    - id: measurability
+      maps_to: Verifiable (IEEE 830)
+      checks_for: "未量化的 NFR、無法測試的驗收條件"
+    - id: coverage
+      maps_to: Traceable (IEEE 830)
+      checks_for: "無法追溯到來源（利害關係人需求/商業目標）的需求"
+  traceability_tags:
+    "[Spec §X.Y]": "有依據——引用具體 spec 段落"
+    "[Gap]": "spec 沒提到，無段落可引用"
+    "[Ambiguity]": "spec 有提到但用詞允許多種解讀"
+    "[Conflict]": "≥2 個 spec 段落互相矛盾，須都引用"
+    "[Assumption]": "揭露 spec 依賴的未言明假設"
+  rules:
+    - "至少 80% 的產出項目須帶 [Spec §X.Y] 標籤——若多數是 [Gap]/[Assumption]，代表 spec 本身太薄弱，不是產生器的問題"
+    - "產生前最多問 5 個適應性釐清問題（無法從 spec 推斷的領域脈絡）；超過 5 個代表該回 Discuss 階段而非繼續問"
+    - "append-only：對修訂後的 spec 重跑，接續編號新增項目，不重新編號或刪除舊項目；被解決的項目標記 [Resolved: <修訂說明>]，不刪除"
+  boundary: "檢查對象是 spec 本身的品質，非程式碼；不取代/不重疊 acceptance-criteria-traceability 標準的 AC↔測試覆蓋率檢查（那個問「測試有沒有涵蓋 spec」，這個問「spec 本身夠不夠格拿去寫測試」）"
+
 # SMART Requirements
 smart:
   S: { label: Specific, example: "Display 'Invalid email format' error" }

package/bundled/ai/standards/self-review-protocol.ai.yaml

@@ -3,10 +3,10 @@
 
 id: self-review-protocol
 meta:
-  version: "1.0.0"
-  updated: "2026-05-26"
+  version: "1.1.0"
+  updated: "2026-07-09"
   source: core/self-review-protocol.md
-  description: Mandatory self-review pass on large markdown edits before commit; catches 6 categories of internal cross-reference inconsistencies that internal reasoning routinely misses
+  description: Mandatory self-review pass on large markdown edits before commit; catches 7 categories of internal cross-reference inconsistencies that internal reasoning routinely misses
 
 trigger_conditions:
   mandatory:
@@ -44,7 +44,7 @@ inconsistency_categories:
   - id: 3
     name: count_drift
     description: Explicit number in text out of sync with actual count
-    example: "self-audit has 4 questions" but list has 7
+    example: '"self-audit has 4 questions" but list has 7'
     check: grep for "N questions", "N rows", "N items" and verify
   - id: 4
     name: stale_template
@@ -61,6 +61,11 @@ inconsistency_categories:
     description: Example contradicts current rule or latest case experience
     example: example shows D1/D2/D3 but rule says D3 not mandatory
     check: every concrete value in examples consistent with current rules
+  - id: 7
+    name: language_consistency
+    description: Non-target-language contamination, same-paragraph language mixing, or inconsistent project terminology within one document
+    example: a zh-TW paragraph contains Japanese kana or Korean hangul characters; or "XSPEC"/"gate"/"pipeline" spelled inconsistently across the same file
+    check: scan for out-of-place scripts (Japanese kana U+3040-U+30FF, Korean hangul U+AC00-U+D7A3) outside expected sections, same-paragraph language mixing, and inconsistent spelling of established project terms
 
 procedure:
   step_1:
@@ -69,7 +74,7 @@ procedure:
     when: after editing, before committing
   step_2:
     name: walk_categories
-    description: Apply 6 categories above against the file
+    description: Apply 7 categories above against the file
   step_3:
     name: fix_in_same_commit
     description: If issues found, edit in place and include fixes in same commit
@@ -84,13 +89,13 @@ recording_formats:
     format: '> **v{X.Y.(Z+1)} Self-review pass {YYYY-MM-DD}**: {N} issues found, {M} fixed in same commit'
   adr_dec:
     location: '## Follow-up Tracking table'
-    format: '| Self-review pass | This DEC | ✅ YYYY-MM-DD (6 categories, no issues) |'
+    format: '| Self-review pass | This DEC | ✅ YYYY-MM-DD (7 categories, no issues) |'
   xspec_sdd_delta:
     location: after non-modification list section (e.g. §N.6)
-    format: '> Self-review pass: YYYY-MM-DD (6 categories, no issues)'
+    format: '> Self-review pass: YYYY-MM-DD (7 categories, no issues)'
   commit_message_body:
     location: last line of commit body
-    format: 'Self-review (protocol v1.0.0): N issues found, M applied in same commit / 0 found.'
+    format: 'Self-review (protocol v1.1.0): N issues found, M applied in same commit / 0 found.'
 
 distinction_from_other_practices:
   code_review:
@@ -139,6 +144,6 @@ examples_in_the_wild:
     note: first SKILL.md edit to pass self-review pre-commit; 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:
-  date: "2026-05-26"
+  date: "2026-07-09"
   issues_found: 0
-  notes: First draft self-review pass; no internal inconsistencies detected
+  notes: Added category 7 (language_consistency) per XSPEC-324; re-read whole file, no internal inconsistencies detected

package/bundled/ai/standards/verification-evidence.ai.yaml

@@ -8,12 +8,14 @@ standard:
   description: 驗證證據標準，強化 anti-hallucination
 
   meta:
-    version: "1.1.0"
-    updated: "2026-05-13"
+    version: "1.2.0"
+    updated: "2026-07-17"
     source: core/verification-evidence.md
     description: >
       驗證證據標準 — Iron Law: 無驗證證據不可聲稱完成。
       v1.1.0: Evidence must specify which environment layer it was collected from (XSPEC-204).
+      v1.2.0: Evidence itself must be validated — a tool can fail silently and its
+      output is indistinguishable from a real result (XSPEC-340).
     inspired_by: superpowers/verification-before-completion
 
   guidelines:
@@ -23,8 +25,55 @@ standard:
     - "驗收證據必須標明收集自哪個環境層次（local / UAT / PRD）"
     - "回歸測試必須展示 RED → GREEN 循環"
     - "代理報告 success ≠ 實際 success，需獨立驗證"
+    - "**工具回報 success ≠ 實際 success**——驗證指令本身可能沒跑起來，而其輸出與真結果無法區分"
     - "驗證輸出截斷至合理長度（2000 字元）但保留關鍵資訊"
 
+  # 以下不構成驗證證據。原本只存在於 zh-TW 譯文裡（英文來源與本檔皆無）——
+  # v1.2.0 一併升上來源與本檔（XSPEC-340 R4：譯文比來源更完整，且無 gate 會報）。
+  non_evidence_claims:
+    - claim: "「已完成」"
+      why: "無可觀察的輸出"
+    - claim: "「應該可以了」"
+      why: "未執行驗證"
+    - claim: "「我改了程式碼」"
+      why: "修改 ≠ 驗證"
+    - claim: "「測試應該會通過」"
+      why: "預測 ≠ 事實"
+    - claim: "「指令回傳 0」"
+      why: "僅當該指令確實可能量到該主張時才算——見 evidence_validity"
+
+  # ── v1.2.0 證據有效性（XSPEC-340）──
+  # Iron Law 擋的是「沒有證據就宣稱完成」。這一層擋的是相反的失敗：
+  # 證據有、指令跑了、exit_code 是 0，**而那個輸出毫無意義**，因為指令根本沒量到東西。
+  # 這不是幻覺（幻覺是「沒查就編」，anti-hallucination 已涵蓋）——這裡什麼都沒編，
+  # 是**查了，而查詢工具騙了你**。
+  evidence_validity:
+    description: "證據本身是否成立——驗證指令是否真的執行、是否真的量到它宣稱的東西"
+    rules:
+      - name: "exit_code 的語意依工具而定"
+        detail: >
+          exit_code = 0 代表成功，只在「該工具成功時回 0」的前提下成立。
+          當工具在受測狀態下**設計上就會失敗**時，其非 0 不帶有關於受測物的任何資訊——
+          改看輸出內容。反向亦然：非 0 不足以證明受測物壞了。
+      - name: "空輸出 / 查無 / 0 ≠ 不存在"
+        detail: >
+          斷言「不存在」之前，須先確立查詢工具**執行成功**：不是 command not found、
+          不是權限不足、參數沒有被中間的 shell 吃掉。**查無之前，先確認查詢工具有在運作。**
+      - name: "判斷存在與否的指令不得丟棄 stderr"
+        detail: >
+          抑制 stderr（`2>/dev/null` 及等價作法）消掉的正是「這個工具壞了」的那條通道，
+          於是失敗會穿上與真陰性一模一樣的外衣。
+      - name: "管線的 exit code 不屬於其中任何單一階段"
+        detail: >
+          `set -o pipefail` 下 `producer | grep -q pattern` 會繼承 producer 的非 0，
+          grep 中不中都無關。需要依內容決策時：**先接住輸出，再判斷**。
+    provenance: >
+      證據來自 2026-07-17 單一 agent（Claude Opus 4.8）單日的十次實例，
+      記錄於 AsiaOstrich XSPEC-340；其中 exit_code=0 四次為假、exit_code≠0 兩次為真
+      且依 VE-002 行動摧毀了健康的產物。樣本密集但來源單一——然而每個失敗都源自
+      **工具本身的語意**（sudo / gpg / pipefail / POSIX exit code）而非模型的性質，
+      故任何驅動同一批工具的 agent 都暴露在同樣的陷阱下。
+
   evidence_format:
     fields:
       - name: command
@@ -62,7 +111,12 @@ standard:
   trust_rules:
     - "代理聲稱「已完成」→ 檢查 verification_evidence 是否存在"
     - "verification_evidence 為空 → 標記為未驗證"
-    - "exit_code ≠ 0 → 標記為驗證失敗"
+    # v1.2.0 修訂：原文為「exit_code ≠ 0 → 標記為驗證失敗」，無條件成立。
+    # 該規則在 2026-07-17 兩次把**完全正常**的加密備份判為失敗並刪除——
+    # 主機依設計不存私鑰，gpg 對正常檔案必然回非 0。故加上前提。
+    - "exit_code ≠ 0 → 標記為驗證失敗——**除非**該工具在受測狀態下設計上就回非 0（見 VE-007），此時改依輸出內容判斷"
+    - "exit_code = 0 但該指令不可能量到它宣稱的東西 → 標記為未驗證"
+    - "證據斷言「不存在」（0／空／查無）→ 未證明查詢工具執行成功前，標記為未驗證"
     - "多個驗證步驟 → 所有步驟都必須通過"
 
   rules:
@@ -72,7 +126,9 @@ standard:
       priority: critical
     - id: VE-002
       trigger: "exit_code ≠ 0"
-      action: "標記驗證失敗，啟動 fix loop"
+      action: >
+        標記驗證失敗，啟動 fix loop——**前提是已確認該工具在此狀態下成功時回 0**（見 VE-007）。
+        未確認就啟動 fix loop 等於對健康的產物動手。
       priority: high
     - id: VE-003
       trigger: "Bug fix 無 RED-GREEN 循環"
@@ -97,6 +153,28 @@ standard:
         要求補充環境層次聲明，或在 environment-stratification-matrix 中標記為 ⚠️/❌。
       priority: high
 
+  # ── v1.2.0 證據有效性規則（XSPEC-340）──
+  validity_rules:
+    - id: VE-007
+      trigger: "驗證工具在受測狀態下**依設計**回非 0（例：主機刻意不存私鑰時的 gpg --list-packets）"
+      action: >
+        VE-002 不適用。改依輸出內容判斷；**不得對健康的產物啟動 fix loop**。
+      priority: critical
+    - id: VE-008
+      trigger: "證據斷言「不存在」（exit_code 0、輸出為 0／空／查無）"
+      action: >
+        該證據不成立，直到證明查詢工具本身執行成功（非 command not found、非權限失敗、
+        參數未被上游 shell 吃掉）。重跑且不抑制 stderr。
+      priority: high
+    - id: VE-009
+      trigger: "判斷存在與否的驗證指令抑制了 stderr（`2>/dev/null` 或等價作法）"
+      action: "證據不成立。以可見 stderr 重跑。"
+      priority: high
+    - id: VE-010
+      trigger: "證據的 exit_code 來自管線（尤其在 `set -o pipefail` 下）"
+      action: "該 exit code 不歸屬於任何單一階段。先接住輸出，再依內容判斷。"
+      priority: medium
+
 physical_spec:
   type: checklist
   validator:
@@ -105,6 +183,11 @@ physical_spec:
   checks:
     - "完成聲明是否附帶 verification_evidence"
     - "evidence 是否包含所有必填欄位"
-    - "exit_code 是否為 0（成功）"
+    # v1.2.0 修訂：原文為「exit_code 是否為 0（成功）」——它把 0 直接等同於成功，
+    # 正是 XSPEC-340 §A 十個實例中四次誤報的來源。
+    - "exit_code 是否為 0——且**該工具成功時確實回 0**（見 VE-007）"
+    - "證據若斷言「不存在」，是否已證明查詢工具執行成功（VE-008）"
+    - "判斷存在與否的指令是否抑制了 stderr（VE-009）"
+    - "exit_code 是否來自管線而非受測指令本身（VE-010）"
     - "Bug fix 是否有 RED → GREEN 循環證據"
     - "有外部服務依賴的 AC 是否標明 environment_layer"

package/bundled/core/checkin-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/checkin-standards.md)
 
-**Version**: 1.7.0
-**Last Updated**: 2026-06-18
+**Version**: 1.8.0
+**Last Updated**: 2026-07-09
 **Applicability**: All software projects using version control
 **Scope**: partial
 **Industry Standards**: SWEBOK v4.0 Chapter 6
@@ -96,7 +96,7 @@ pytest --cov=src tests/
 ```
 
 **Verification**:
-- Run all test suites locally
+- Run all relevant tests locally (see "All relevant tests pass" above — directly exercised code plus tests affected by the change, via test impact analysis tooling if the project has it); when scope is unclear, or the change touches shared/core paths, run the full suite instead
 - Review test coverage report
 - Ensure new code paths are tested
 

package/bundled/core/documentation-writing-standards.md

@@ -818,7 +818,7 @@ Track translation status in translated document headers:
 ---
 translation_status: current | needs_update | in_progress
 source_version: 1.2.0
-source_hash: abc123
+source_hash: a1b2c3d4e5f6   # first 12 chars of `git hash-object <source>`
 translated_by: human | machine | machine+human-review
 last_synced: 2026-03-17
 ---