universal-dev-standards 5.17.0 → 6.1.0

package/bundled/ai/standards/user-journey-testing.ai.yaml

@@ -0,0 +1,107 @@
+# User Journey Testing Standard - AI Optimized
+# 使用者旅程測試標準：定義 TESTPLAN 格式，讓跨 Story 的連貫使用者旅程成為測試一等公民
+
+standard:
+  id: user-journey-testing
+  name: User Journey Testing Standard
+  description: Defines TESTPLAN format for connected, sequential user journey tests
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-05-03"
+    source: core/user-journey-testing.md
+    description: TESTPLAN format for connected, sequential user journey tests
+
+  guidelines:
+    - "Every project MUST have at least one TESTPLAN-NNN.md documenting the main user journey"
+    - "TESTPLAN steps MUST be sequential and stateful — each step depends on prior state"
+    - "Every TESTPLAN MUST define personas before test steps"
+    - "TESTPLAN and automated E2E tests MUST use the same T-NNN identifiers"
+    - "Journey E2E tests MUST skip gracefully when environment is unavailable"
+    - "Journey tests cover what AC tests cannot: cross-story state continuity"
+
+  testplan_format:
+    file_naming: "TESTPLAN-NNN-<project-slug>.md"
+    location: "test-plans/"
+    sections:
+      personas:
+        required: true
+        description: "Define all test actors with their role and permissions"
+        format: "| Actor | Role | Key Permissions |"
+      environment:
+        required: true
+        description: "List environment prerequisites and verification commands"
+      test_groups:
+        required: true
+        description: "T-NNN numbered test groups with sequential dependency chain"
+      execution_order:
+        required: true
+        description: "Dependency diagram showing T-NNN → T-NNN relationships"
+
+  step_markers:
+    "[UI]": "Browser-based action, verify visually"
+    "[API]": "curl / API client verification"
+    "[CHECK]": "Expected result to confirm"
+    "[SKIP-if]": "Conditional skip with reason"
+    "★": "High-risk step requiring confirmation"
+
+  step_format:
+    fields:
+      - step_id: "T-NNN-M (group-step format)"
+      - operation: "What to do, with [MARKER]"
+      - expected_result: "What should happen"
+    precondition: "State from previous T-NNN that must be satisfied"
+    depends_on: "Comma-separated T-NNN identifiers"
+
+  automation_mapping:
+    principle: "Every T-NNN group maps to a describe() block; every step maps to an it()"
+    file_pattern: "*.journey.spec.ts or *.journey.e2e.test.ts"
+    shared_state: "Journey tests MUST use shared let variables across it() blocks"
+    skip_strategy: "Use describe.skipIf(!BASE_URL) for environment-dependent tests"
+
+  journey_categories:
+    - id: platform-admin-journey
+      description: "Platform admin setup: login → org → project → pipeline"
+      required_for: ["enterprise", "saas"]
+    - id: member-journey
+      description: "Org member: join → project access → pipeline view"
+      required_for: ["enterprise", "saas"]
+    - id: dev-journey
+      description: "Developer: new project → spec → pipeline → artifact"
+      required_for: ["all"]
+
+  rules:
+    - id: testplan-required
+      trigger: creating a new project
+      instruction: Generate TESTPLAN-001.md with personas, environment, and main journey steps before writing code
+      priority: required
+
+    - id: journey-before-code
+      trigger: starting project implementation
+      instruction: Define the user journey test plan first; journey tests act as living acceptance criteria
+      priority: recommended
+
+    - id: sequential-state
+      trigger: writing journey E2E tests
+      instruction: Use shared state variables (let token, orgSlug, projectSlug) so each test step builds on previous results
+      priority: required
+
+    - id: graceful-skip
+      trigger: writing journey E2E tests
+      instruction: Guard with describe.skipIf(!process.env.JOURNEY_BASE_URL) so tests are skipped in unit CI
+      priority: required
+
+    - id: t-nnn-alignment
+      trigger: writing any E2E test
+      instruction: Reference T-NNN identifiers from TESTPLAN in test descriptions for traceability
+      priority: recommended
+
+    - id: persona-first
+      trigger: writing TESTPLAN
+      instruction: Define all user personas before writing any test steps
+      priority: required
+
+    - id: dependency-chain
+      trigger: writing TESTPLAN
+      instruction: Each test group must declare its depends_on list so execution order is explicit
+      priority: required

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/ai/standards/verification-oracle.ai.yaml

@@ -0,0 +1,278 @@
+# Verification Oracle Standards - AI Optimized
+# Sources:
+#   v1.0.0 — XSPEC-256 Verification Oracle (correctness as a maintained invariant)
+#            DEC-077 (mother decision: "correct" is a maintained invariant, the moat axis)
+
+id: verification-oracle
+title: Verification Oracle Standards (Ground-Truth Correctness as a Maintained Invariant)
+version: "1.0.0"
+status: Active
+tags: [correctness, oracle, ground-truth, verification, governance-gate, fail-closed, audit, regression, re-verification, ci-invariant]
+created: 2026-06-17
+updated: 2026-06-17
+
+spec_ref: XSPEC-256   # Verification Oracle complete spec
+
+references:
+  - XSPEC-256   # v1.0.0 source — Verification Oracle
+  - DEC-077     # Mother decision — correctness as a maintained invariant
+  - DEC-075     # Domain-neutral mechanism (oracle content belongs to customer)
+  - DEC-076     # Self-serve north star — oracle = self-serve ceiling
+  - DEC-063     # Legal & compliance — customer-owned output / high-stakes
+  - DEC-066     # Telemetry-driven evolution — audit/telemetry allowlist
+  - DEC-064     # Customer IP isolation (per-customer registry salt)
+  - XSPEC-193   # Sibling governance-gate profile — licensing
+  - XSPEC-255   # Sibling governance-gate profile — provenance
+  - XSPEC-252   # Oracle manufacturing (Tier-4 hand-off)
+  - XSPEC-188   # UAT ship-decision dashboard (business-level UAT anchors)
+  - XSPEC-201   # Behavior-snapshot = an oracle instance
+
+summary: |
+  A test oracle is the source of truth that decides whether software output is correct.
+  Software without an oracle cannot be said to be "right". This standard makes the
+  ground-truth oracle a first-class artifact and turns "correct" from a one-time
+  acceptance state into a maintained invariant re-verified on every change (DEC-077).
+
+  It is the CORRECTNESS member of the governance-gate family — alongside license-compliance
+  (XSPEC-193, licensing) and model-provenance (XSPEC-255, provenance) — sharing the same
+  shape: registry/check -> fail-closed gate -> audit evidence -> human-escalation ceiling.
+  The three are profiles of one mechanism over three axes: licensing / provenance / correctness.
+
+  REQ-001~007: ground-truth registry bound to AC; oracle-ability grading (Tier 1-4); a
+  fail-closed pre-ship verification gate; sustained re-verification on every change with
+  drift detection; auditable evidence (N/N reproduced + no-drift + trace); a self-serve
+  frontier ceiling that escalates unverifiable high-stakes paths to a human; and oracle
+  content sovereignty (mechanism neutral, correct answers owned by the customer).
+
+scope:
+  applies_to:
+    - High-stakes features where correctness is verifiable against a ground-truth oracle
+      (billing / calculation / compliance / rules / data transformation)
+    - Generated or refactored systems that must reproduce known-correct outputs
+    - Acceptance evidence and audit reports proving correctness over time
+  excludes:
+    - Low-stakes software with no oracle and no correctness stake (over-design; see DEC-077)
+    - The oracle CONTENT itself (correct answers) — owned by the customer, not this standard
+    - Enforcement-engine wiring (e.g. VibeOps pipeline gate) — downstream adoption concern
+
+oracle_ability_spectrum:
+  description: |
+    Grade each high-stakes feature by how readily its oracle exists. Drives cost,
+    beachhead selection, and the Tier-4 hand-off to oracle manufacturing (XSPEC-252).
+  tiers:
+    - tier: 1
+      shape: Known-correct output of a legacy system
+      readiness: Most ready, cheapest (parity-provable)
+    - tier: 2
+      shape: A batch of hand-computed / existing correct outputs
+      readiness: Ready (reproduce + scale)
+    - tier: 3
+      shape: Regulation / formula (rules exist, examples missing)
+      readiness: Needs co-derived worked examples + sign-off (ATDD)
+    - tier: 4
+      shape: Vague requirement (oracle must be mined from interviews)
+      readiness: Most expensive — the translation problem (XSPEC-252 pulls toward 1-2)
+
+principles:
+  - id: P-1
+    name: Oracle First
+    description: |
+      No oracle, no "correct". Every claim of correctness MUST be grounded in an oracle,
+      and every high-stakes feature MUST be graded for oracle-ability before correctness
+      is asserted. Where no oracle exists, escalate (P-5) rather than guess.
+
+  - id: P-2
+    name: Maintained Invariant
+    description: |
+      "Correct" is not a one-time acceptance state but an invariant re-verified on every
+      change (DEC-077). Drift (was-correct, now-wrong) is a blocking event, not a warning.
+
+  - id: P-3
+    name: Fail-Closed
+    description: |
+      Non-reproduction of any ground-truth case MUST block ship or escalate. The gate MUST
+      NOT silently pass — mirroring the license-compliance blocklist and model-provenance
+      denylist behaviour.
+
+  - id: P-4
+    name: Evidence-Based
+    description: |
+      Every verdict MUST carry a reproducible trace: cases reproduced (N/N), per-case
+      input -> expected vs actual diff, content hash, and an audit-trail id. Verdicts
+      without evidence are prohibited.
+
+  - id: P-5
+    name: Human Ceiling
+    description: |
+      Defining correctness and signing off acceptance are human judgments (customer /
+      legal / regulator). Unverifiable high-stakes paths MUST escalate to a human
+      (DEC-076 ceiling) — a product-enforced governance gate, not a consultant trap.
+
+  - id: P-6
+    name: Content Sovereignty
+    description: |
+      The verification mechanism is domain-neutral (DEC-075); the correct answers are
+      owned by the customer (DEC-063). Registries SHOULD be customer-scoped and isolated
+      (DEC-064 salt).
+
+requirements:
+  - id: REQ-001
+    title: Ground-Truth Registry (first-class artifact)
+    description: |
+      Customer-provided correct answers become a first-class artifact. Each case carries
+      an input scenario + expected correct output and is bound to the acceptance criterion
+      it proves (acceptance-criteria-traceability). At minimum the mechanism MUST support
+      numeric and structured-output comparison, with per-field exemptions (ignore_fields).
+      The expected output is the CORRECT result, not merely "endpoint returned HTTP 200".
+    level: MUST
+    examples:
+      - "Billing case: given {orders, org_state} -> expected correct charge $0 (no double-charge)"
+      - "Case bound to AC-7 'no duplicate charge on retry' via acceptance-criteria-traceability"
+      - "Structured compare with ignore_fields:[created_at,request_id] to exclude volatile fields"
+
+  - id: REQ-002
+    title: Oracle-ability Grading (Tier 1-4)
+    description: |
+      Every high-stakes feature MUST be tagged with its oracle Tier (1-4). A Tier-4
+      (must-mine) feature MUST have a defined hand-off point to an oracle-manufacturing
+      flow (interview / Prototype Probe, XSPEC-252) that pulls the expensive end toward
+      Tier 1-2. Beachhead selection SHOULD prefer Tier 1-2.
+    level: MUST
+    examples:
+      - "Feature 'legacy billing parity' graded Tier 1 (legacy known-correct outputs exist)"
+      - "Feature 'discretionary discount policy' graded Tier 4 -> XSPEC-252 manufacturing hand-off"
+
+  - id: REQ-003
+    title: Fail-Closed Verification Gate (pre-ship)
+    description: |
+      Before entering UAT/ship, the system MUST exactly reproduce every registered
+      ground-truth case. A non-reproduction MUST block ship or escalate — never silently
+      pass. The gate plugs into existing reviewer/QA gates and the audit logger.
+    level: MUST
+    checks:
+      - "All registry cases must reproduce (N/N) before ship is allowed"
+      - "Any non-reproduction -> block ship OR escalate_to_human; never silent pass"
+      - "Injection test: deliberately corrupt one expected value -> gate blocks"
+
+  - id: REQ-004
+    title: Sustained Re-Verification (correctness as CI invariant)
+    description: |
+      On every change/regeneration the full oracle suite MUST be re-run, making correct a
+      CI-grade invariant. Drift (was-correct, now-wrong) MUST be detected and blocked.
+      This mechanizes DEC-077 ("changed and still correct, provably correct throughout").
+    level: MUST
+    checks:
+      - "Change/regeneration triggers a full re-run of the oracle suite"
+      - "Drift (previously reproduced case now failing) -> detect and block (regression oracle)"
+      - "Regression test: introduce drift -> detected and blocked"
+
+  - id: REQ-005
+    title: Audit Evidence
+    description: |
+      Each run MUST emit an auditable report: reproduced N/N, no drift, trace attached.
+      It plugs into the audit logger / hash chain, model-provenance source evidence
+      (XSPEC-255), and the telemetry allowlist (DEC-066). This report is the outward proof
+      of the correctness/governance moat and a customer compliance artifact.
+    level: MUST
+    evidence_required:
+      - "cases reproduced count (N/N)"
+      - "per-case: scenario, input, expected, actual, diff on mismatch"
+      - "drift status (none / list of drifted case ids)"
+      - "content hash (sha256) of the report"
+      - "audit-trail id (hash-chain entry)"
+
+  - id: REQ-006
+    title: Self-Serve Frontier Ceiling
+    description: |
+      Where no oracle exists (correctness not decidable) or a high-stakes path is
+      unverifiable, self-serve MUST NOT silently pass. The system MUST flag "human must
+      decide / oracle must be supplied" and escalate (DEC-076 ceiling).
+    level: MUST
+    checks:
+      - "Feature with no oracle MUST NOT auto-ship — flag needs-human and escalate"
+      - "Injection test: an oracle-less high-stakes feature is not auto-shipped"
+
+  - id: REQ-007
+    title: Oracle Content Sovereignty
+    description: |
+      The mechanism is domain-neutral (DEC-075); the correct answers are customer-owned
+      (DEC-063). Registries SHOULD be customer-scoped and isolated (DEC-064 salt).
+    level: SHOULD
+    checks:
+      - "Registry scoping is per-customer; correctness verdicts attribute content to the customer"
+      - "Mechanism carries no domain-specific correctness logic baked in"
+
+# ─────────────────────────────────────────────────────────────
+# Governance-gate family (shared shape with XSPEC-193 / XSPEC-255)
+# ─────────────────────────────────────────────────────────────
+
+governance_gate_family:
+  description: |
+    verification-oracle is the CORRECTNESS profile of one governance-gate mechanism.
+    All profiles share: registry/check -> fail-closed gate -> audit evidence ->
+    customer-override-telemetered -> human-escalation ceiling.
+  profiles:
+    - profile: licensing
+      standard: license-compliance
+      spec: XSPEC-193
+      registry: blocklist/allowlist/greylist
+      block_trigger: prohibited license
+    - profile: provenance
+      standard: model-provenance (planned sibling)
+      spec: XSPEC-255
+      registry: model source policy
+      block_trigger: denied source
+    - profile: correctness
+      standard: verification-oracle
+      spec: XSPEC-256
+      registry: ground-truth registry
+      block_trigger: non-reproduction / drift
+
+# ─────────────────────────────────────────────────────────────
+# Gate timing
+# ─────────────────────────────────────────────────────────────
+
+gate_timing:
+  pre_ship: REQ-003 fail-closed gate — reproduce all ground-truth before UAT/ship
+  on_every_change: REQ-004 re-run full oracle suite — drift blocks
+  after_run: REQ-005 emit audit evidence report (outward moat proof)
+  on_unverifiable: REQ-006 escalate to human (no silent pass)
+
+# ─────────────────────────────────────────────────────────────
+# Telemetry (DEC-066 / XSPEC-189 v2 envelope)
+# ─────────────────────────────────────────────────────────────
+
+telemetry:
+  required_events:
+    - oracle_verification_result   # N/N reproduction outcome per run
+    - oracle_drift_detected        # was-correct, now-wrong (REQ-004)
+    - oracle_gate_block            # fail-closed block detail (REQ-003)
+    - oracle_escalation            # unverifiable high-stakes escalated (REQ-006)
+    - human_override_block         # human override of a block (requires reason)
+  envelope_reference: XSPEC-189    # Telemetry Schema v2 envelope
+  event_type: quality
+  event_subtype_examples:
+    - oracle_verification_result
+    - gate_pass / gate_fail        # when the oracle gate acts as a ship gate
+
+# ─────────────────────────────────────────────────────────────
+# Integration with existing standards
+# ─────────────────────────────────────────────────────────────
+
+integration:
+  acceptance-criteria-traceability: oracle cases bind to AC; reproduction is a form of AC coverage
+  verification-evidence: the oracle report is a kind of verification evidence (N/N + no-drift + trace)
+  test-governance: the oracle suite is governed test policy; the gate is a governed gate
+  behavior-snapshot: parity/snapshot gate = REQ-003/REQ-004 for the refactor/migration case (a snapshot is an oracle)
+
+# ─────────────────────────────────────────────────────────────
+# Adoption guidance
+# ─────────────────────────────────────────────────────────────
+
+adoption_guidance:
+  uds_install_path: ai/standards/verification-oracle.ai.yaml
+  notes:
+    - "v1.0.0 defines the correctness oracle mechanism and acceptance evidence. Oracle content (correct answers) is customer-owned (DEC-075/DEC-063)."
+    - "Adopters MAY enforce the gate via CI (reproduce ground-truth on every change) without a bespoke engine."
+    - "Tier-4 (must-mine) features need an oracle-manufacturing hand-off (XSPEC-252) before correctness can be claimed."
+    - "Group with license-compliance and model-provenance as one governance-gate subsystem (three profiles)."

package/bundled/ai/standards/versioning.ai.yaml

@@ -13,8 +13,8 @@ standard:
     - "Use pre-release identifiers (alpha, beta, rc)"
 
   meta:
-    version: "2.0.0"
-    updated: "2026-02-04"
+    version: "2.2.0"
+    updated: "2026-07-01"
     source: core/versioning.md
     description: Semantic Versioning (SemVer) for software releases
 
@@ -82,42 +82,14 @@ standard:
         - Breaking changes allowed in MINOR versions
         - Move to 1.0.0 when API is stable
 
-  deprecation:
-    timeline:
-      internal_api: 1 minor version
-      partner_api: 2 minor versions + 3 months
-      public_api: 2 minor versions + 6 months
-      critical_infrastructure: 1 year minimum
-    backward_compatibility:
-      breaking_changes:
-        - Remove public API endpoints
-        - Remove required request fields
-        - Add required request fields
-        - Change response field types
-        - Change error code meanings
-        - Remove response fields consumers depend on
-      safe_changes:
-        - Add optional request fields
-        - Add new response fields
-        - Add new endpoints
-        - Add new error codes
-        - Improve error messages
-        - Performance improvements
-
-  api_versioning_strategies:
-    - strategy: URL Path
-      format: "/api/v1/users"
-      pros: Clear, easy routing
-      cons: URL pollution
-      recommended: true
-    - strategy: Query Parameter
-      format: "/api/users?version=1"
-      pros: Optional versioning
-      cons: Cache issues
-    - strategy: Header
-      format: "Accept: application/vnd.api.v1+json"
-      pros: Clean URLs
-      cons: Less visible
+  # API versioning strategies, the backward-compatibility checklist, deprecation
+  # timeline + per-tier periods, and the migration-guide template were moved to
+  # their single sources of truth (XSPEC-298 R8, UDS #126):
+  #   - api-design.ai.yaml  → versioning_strategies.backward_compatibility
+  #   - deprecation-standards.ai.yaml → api_deprecation.minimum_period_by_tier
+  cross_references:
+    api_contract: "core/api-design-standards.md#api-versioning-strategies"
+    deprecation_lifecycle: "core/deprecation-standards.md#api-deprecation"
 
   release_process:
     phases:
@@ -149,6 +121,7 @@ standard:
         check_items:
           - Service running normally
           - API returns correct version
+          - "Build-identity endpoint (/version or /health) returns commit sha matching the deployed artifact (not just version)"
           - No fatal errors in logs
           - Functionality verification passed
 
@@ -177,6 +150,27 @@ standard:
       trigger: deploying upgrade
       instruction: Must not skip dry-run test
       priority: required
+    - id: git-height-versioning-polyglot
+      trigger: choosing version automation for a polyglot / .NET / JVM project
+      instruction: >
+        Use git-height-derived versioning (MinVer / Nerdbank.GitVersioning / GitVersion)
+        so the version is derived from git tag + commit height and collisions are
+        structurally impossible; reserve semantic-release / standard-version for Node/npm
+        projects
+      priority: recommended
+    - id: build-identity-must-expose-sha
+      trigger: deploying a service
+      instruction: >
+        Deployed services MUST expose build identity (version + commit sha + build time)
+        via a queryable endpoint (/version or embedded in /health); the sha MUST be
+        verifiable against the deployed artifact, not self-reported
+      priority: required
+    - id: verify-sha-post-release
+      trigger: post-release verification
+      instruction: >
+        Assert the build-identity endpoint returns a commit sha matching the deployed
+        artifact, not merely the correct version number
+      priority: required
 
 physical_spec:
   type: custom_script

package/bundled/core/acceptance-criteria-traceability.md

@@ -2,6 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/acceptance-criteria-traceability.md)
 
+**Version**: 1.1.0
+**Last Updated**: 2026-06-19
 **Applicability**: All software projects using specification-driven or test-driven workflows
 **Scope**: universal
 
@@ -45,13 +47,15 @@ Acceptance Criteria Traceability Standards define how to track the relationship
 
 ### Linking Convention
 
-Tests MUST reference their source AC using standard annotations:
+Tests MUST reference their source AC using the **canonical annotation**:
+`@SPEC-<id> @AC-<n>` — a single combined tag, e.g. `@SPEC-001 @AC-1`. Keeping the
+attribution on one line is what forward-derivation and test-runner tag filters
+consume; **do not** split it into separate `@AC` / `@SPEC` lines.
 
 ```typescript
 // TypeScript/JavaScript
 describe('AC-1: User login with valid credentials', () => {
-  // @AC AC-1
-  // @SPEC SPEC-001
+  // @SPEC-001 @AC-1
   it('should redirect to dashboard on successful login', () => { ... });
 });
 ```
@@ -60,8 +64,7 @@ describe('AC-1: User login with valid credentials', () => {
 # Python
 class TestAC1_UserLogin:
     """AC-1: User login with valid credentials
-    @AC AC-1
-    @SPEC SPEC-001
+    @SPEC-001 @AC-1
     """
     def test_redirect_to_dashboard(self): ...
 ```
@@ -72,6 +75,13 @@ class TestAC1_UserLogin:
 Scenario: User login with valid credentials
 ```
 
+> **Key naming (by design, not a conflict).** `acceptance-criteria` (kebab-case)
+> is the human / identifier spelling — doc titles, standard ids, AI-format keys.
+> `acceptance_criteria` (snake_case) is the YAML **serialization** field (e.g.
+> `structured-task-definition`). `acceptanceCriteria` (camelCase) is not used.
+> These are layer-appropriate spellings (see the glossary's field-naming table)
+> and are **not** unified.
+
 ---
 
 ## Coverage Status Definitions