universal-dev-standards 5.7.3 → 5.10.0

package/bundled/ai/standards/mock-boundary.ai.yaml

@@ -3,12 +3,86 @@
 
 id: mock-boundary
 meta:
-  version: "1.0.0"
-  updated: "2026-05-04"
+  version: "1.1.0"
+  updated: "2026-05-13"
   source: core/mock-boundary.md
   description: >
     Rules defining what can and cannot be mocked to prevent hollow tests —
     tests that pass while the real system is broken.
+    v1.1.0: Added Level 1/Level 2 mock layer distinction and external
+    dependency testability matrix template (XSPEC-204).
+
+# ─────────────────────────────────────────────────────────
+# Mock Levels (v1.1.0)
+# ─────────────────────────────────────────────────────────
+mock_levels:
+  description: >
+    Two distinct levels of test doubles with separate governance rules.
+    Conflating them leads to the "STUB blocked ∩ real service unavailable = untestable"
+    deadlock in UAT environments.
+
+  level_1:
+    name: Code-level Mock
+    description: >
+      Test doubles within test code — jest.mock(), Moq.Mock<T>(), vi.fn(), etc.
+    governance: "Regulated by STUB marker rules (full-coverage-testing)"
+    examples:
+      - "vi.mock('../../src/services/sms-service.js')"
+      - "new Mock<ISmsService>()"
+      - "httpClient.Setup(x => x.PostAsync(...)).ReturnsAsync(...)"
+    rules:
+      - "Subject to // WARNING: STUB deployment-blocking rules"
+      - "Not allowed in flow/integration/E2E tests (see forbidden section)"
+      - "STUB marker must be placed at usage site"
+
+  level_2:
+    name: Infrastructure-level Stub Server
+    description: >
+      Independently running test-double services — WireMock, MockSoap, stub-server, json-server, etc.
+      These run as separate processes alongside the application under test.
+    governance: "Regulated by environment stratification rules (multi-environment-e2e-testing)"
+    examples:
+      - "WireMock running on port 9999, app configured via env var to hit it"
+      - "MockSoap sidecar for SOAP gateway simulation"
+      - "json-server for external REST API simulation"
+    rules:
+      - "NOT subject to STUB deployment-blocking rules (they are infrastructure, not code)"
+      - "MAY be used in UAT environment when real external service is unavailable"
+      - "MUST be documented in the external-dependency-testability-matrix as ⚠️"
+      - "MUST list dimensions NOT verifiable through the stub"
+      - "MUST NOT be deployed to or accessible from PRD environment"
+      - "MUST be deployed as sidecar (not bundled in production artifact)"
+
+  level_2_rationale: >
+    When full-coverage-testing blocks STUB markers AND the real external service
+    is unavailable in UAT (e.g., SMS gateway requires billing setup), Level 2
+    stub servers are the correct solution. They allow the flow to execute in UAT
+    while clearly documenting which verification dimensions are deferred to PRD.
+
+# ─────────────────────────────────────────────────────────
+# External Dependency Testability Matrix Template
+# ─────────────────────────────────────────────────────────
+external_dependency_testability_matrix:
+  rule: >
+    Projects with external service dependencies MUST maintain this matrix.
+    It answers: "In this environment, can we fully verify this service integration?"
+  location: "docs/testing/dependency-testability-matrix.md"
+  when_required: "Any project with SMS, payment, IdP, messaging, or external SOAP/REST dependencies"
+
+  template: |
+    ## External Dependency Testability Matrix
+
+    | External Service | local-dev | UAT | PRD | Unverifiable Dimensions in UAT |
+    |-----------------|:---------:|:---:|:---:|-------------------------------|
+    | SMS Gateway     | ⚠️ L2-stub | ⚠️ L2-stub / ❌ | ✅ | Billing correctness, DR reporting, carrier delivery |
+    | Payment SOAP    | ⚠️ L2-stub | ⚠️/❌ | ✅ | Real debit/credit, bank reconciliation, card validation |
+    | LDAP / AD       | ⚠️ container | ⚠️ AD LDS | ✅ | Enterprise AD tree, group sync, GPO policies |
+    | Push Notification | ⚠️ mock | ⚠️ sandbox | ✅ | Production delivery rates, carrier-specific behavior |
+
+    Legend:
+    ✅ Full verification | ⚠️ Flow passes via stub (real-world dimensions deferred) | ❌ Cannot test
+
+  note: "L2-stub = Level 2 infrastructure stub server. Refer to mock-boundary Level 2 rules."
 
 # ─────────────────────────────────────────────────────────
 # Core Problem
@@ -223,6 +297,23 @@ rules:
       If any hollow test indicator triggers, rewrite the mocking strategy.
     priority: required
 
+  - id: level-2-stub-server-rules
+    trigger: UAT environment lacks a real external service (SMS, payment, IdP)
+    instruction: >
+      Use a Level 2 infrastructure stub server (WireMock, MockSoap, etc.) deployed
+      as a sidecar — not Level 1 code mocks, which are blocked in UAT by STUB rules.
+      Document the stub server in the external-dependency-testability-matrix as ⚠️
+      and list which verification dimensions are deferred to PRD.
+    priority: required
+
+  - id: no-stub-server-in-prd
+    trigger: deploying to production
+    instruction: >
+      Production artifact MUST NOT include stub server code.
+      Stub servers MUST NOT be running or accessible in PRD environment.
+      See deployment-standards for CI/CD exclusion rules.
+    priority: required
+
 # ─────────────────────────────────────────────────────────
 # Quick Reference
 # ─────────────────────────────────────────────────────────

package/bundled/ai/standards/multi-environment-e2e-testing.ai.yaml

@@ -0,0 +1,250 @@
+# Multi-Environment E2E Testing Standards - AI Optimized
+# Source: XSPEC-204 (UDS Issue #94, #95)
+
+id: multi-environment-e2e-testing
+meta:
+  version: "1.0.0"
+  updated: "2026-05-13"
+  description: >
+    Standards for E2E test configuration across multiple deployment targets.
+    Core principle: The run command IS the documentation.
+    Each environment has one entry-point script that self-checks prerequisites
+    and runs the correct test subset.
+
+# ─────────────────────────────────────────────────────────
+# Core Principle
+# ─────────────────────────────────────────────────────────
+core_principle:
+  name: Executable Environment Documentation
+  statement: "The run command IS the documentation."
+  rationale: >
+    Developers repeatedly ask "how do I run tests against environment X?"
+    because the answer is scattered across README, wiki, and verbal knowledge.
+    When the run script self-checks prerequisites and sets the correct BASE_URL,
+    the script itself becomes the authoritative environment setup guide.
+  anti_pattern: >
+    Manually changing BASE_URL in .env before test runs — breaks other
+    developers' configs and cannot be committed without affecting everyone.
+
+# ─────────────────────────────────────────────────────────
+# Test Framework Multi-Environment Config
+# ─────────────────────────────────────────────────────────
+test_framework_config:
+  rule: "BASE_URL is baked into test project config, not read from .env"
+  rationale: >
+    If BASE_URL comes from .env, developers must modify .env before running
+    against a specific environment, creating race conditions in teams and
+    accidental commits of wrong URLs.
+
+  playwright_pattern: |
+    // playwright.config.ts
+    const ENVS = {
+      'local-iis':         'http://localhost/corp',
+      'local-iis-express': 'http://localhost:18080/lotest',
+      'uat':               'http://portal_uat.example.com/app',
+      'prd':               'https://app.example.com',
+    } as const;
+
+    export default defineConfig({
+      projects: Object.entries(ENVS).map(([name, url]) => ({
+        name,
+        use: { browserName: 'chromium', baseURL: url },
+      })),
+    });
+
+  cypress_pattern: |
+    // cypress.config.ts
+    const ENVS = {
+      'local':  { baseUrl: 'http://localhost:3000' },
+      'uat':    { baseUrl: 'http://uat.example.com' },
+      'prd':    { baseUrl: 'https://app.example.com' },
+    };
+    // Pass via --env target=uat; default to local
+
+  rules:
+    - "One test config file; environment distinction via project name or --project flag"
+    - "No environment-specific playwright/cypress.config.*.ts files"
+    - "BASE_URL never in .env for E2E test configs"
+
+# ─────────────────────────────────────────────────────────
+# Runner Script Pattern
+# ─────────────────────────────────────────────────────────
+runner_script_pattern:
+  rule: "Each environment has one entry-point script that self-checks prerequisites"
+  location: "scripts/run-tests-<env>.(ps1|sh)"
+  template_powershell: |
+    # scripts/run-tests-local-iis.ps1
+    # Self-check prerequisites before running tests
+
+    # 1. Check Docker
+    if (-not (Get-Process "com.docker.backend" -ErrorAction SilentlyContinue)) {
+      Write-Error "Docker is not running. Start Docker Desktop first."
+      exit 1
+    }
+
+    # 2. Check App is responding
+    try {
+      $resp = Invoke-WebRequest "http://localhost/corp/health" -UseBasicParsing -TimeoutSec 5
+    } catch {
+      Write-Error "App not responding at http://localhost/corp. Start IIS site first."
+      exit 1
+    }
+
+    # 3. Run tests
+    npx playwright test --project=local-iis @args
+
+  template_bash: |
+    #!/bin/bash
+    # scripts/run-tests-local.sh
+
+    # 1. Check Docker
+    if ! docker info > /dev/null 2>&1; then
+      echo "ERROR: Docker is not running." >&2
+      exit 1
+    fi
+
+    # 2. Check App
+    if ! curl -s -f http://localhost:3000/health > /dev/null 2>&1; then
+      echo "ERROR: App not responding at http://localhost:3000" >&2
+      exit 1
+    fi
+
+    npx playwright test --project=local "$@"
+
+  prerequisite_checks:
+    - "Docker / container runtime"
+    - "Application health endpoint"
+    - "Database connectivity (if separate from app)"
+    - "Required environment-specific services"
+
+# ─────────────────────────────────────────────────────────
+# Environment Capability Matrix
+# ─────────────────────────────────────────────────────────
+capability_matrix:
+  rule: >
+    Projects with external dependencies MUST maintain an environment capability
+    matrix committed to the repository (docs/testing/environment-capability-matrix.md
+    or inline in testing README).
+  when_required: "Any project with external HTTP services, IdP, payment, messaging"
+
+  template: |
+    ## Environment Capability Matrix
+
+    | Service / Feature | local-dev | local-iis | UAT | PRD |
+    |-------------------|:---------:|:---------:|:---:|:---:|
+    | Auth / SAML       | ⚠️ Keycloak stub | ✅ Keycloak local | ✅ Keycloak UAT | ✅ Enterprise IdP |
+    | SMS Gateway       | ⚠️ stub-server | ⚠️ stub-server | ⚠️ stub-server / ❌ | ✅ Real Gateway + billing |
+    | Payment / Finance | ⚠️ stub-server | ⚠️ stub-server | ⚠️ partial | ✅ Real + reconciliation |
+    | Background Jobs   | ✅ in-process | ✅ in-process | ✅ | ✅ |
+    | File Storage      | ✅ local | ✅ local | ✅ blob | ✅ blob |
+
+    Legend:
+    ✅ Full verification possible
+    ⚠️ Flow passes but through stub (real-world dimensions NOT verified)
+    ❌ Cannot test in this environment
+
+    ### Dimensions NOT verifiable in UAT (must defer to PRD smoke)
+    - SMS: Billing correctness, carrier delivery confirmation, DR reporting
+    - Payment: Real debit/credit, bank reconciliation, card validation
+
+  when_to_update: "Update matrix when adding any new external service dependency"
+
+# ─────────────────────────────────────────────────────────
+# CI Gate Mapping
+# ─────────────────────────────────────────────────────────
+ci_gate_mapping:
+  rule: "Map environments to CI/CD stages; document which gate must pass before each deployment stage"
+
+  pattern: |
+    # .github/workflows/ci.yml or .gitlab-ci.yml
+
+    e2e-smoke-gate:       # Must pass → any deployment
+      runs-on: ubuntu-latest
+      script: scripts/run-tests-local.sh --grep smoke
+
+    e2e-uat-gate:         # Must pass → PRD deployment
+      environment: uat
+      script: scripts/run-tests-uat.sh
+      only: [tags, release-branches]
+
+    e2e-prd-smoke:        # Must pass → mark release as stable
+      environment: prd
+      script: scripts/run-tests-prd-smoke.sh
+      only: [tags]
+
+  gate_requirements:
+    before_staging_deploy: ["unit tests", "integration tests", "e2e-smoke-gate"]
+    before_uat_deploy:     ["all staging gates", "e2e-uat-gate (if UAT environment available)"]
+    before_prd_deploy:     ["e2e-uat-gate", "sign-off from capability matrix review"]
+    after_prd_deploy:      ["e2e-prd-smoke within 10 min of deploy"]
+
+# ─────────────────────────────────────────────────────────
+# Credential Handling
+# ─────────────────────────────────────────────────────────
+credential_handling:
+  rule: "Separate what goes in git from what stays gitignored"
+
+  commit_to_git:
+    - "Base URLs per environment (non-secret, team needs to share)"
+    - "Test usernames for non-PRD environments"
+    - "Feature flags and test configuration"
+    - "Self-check scripts (no credentials embedded)"
+
+  gitignore:
+    - "Passwords and secrets"
+    - "API keys and tokens"
+    - ".env.test.local (personal overrides)"
+
+  ci_secrets: "Pass PRD test passwords via CI secret variables (GitHub Secrets / GitLab CI Variables)"
+
+  example_gitignore: |
+    # Test credentials
+    .env.test.local
+    tests/fixtures/auth-secrets.json
+    # Base URLs and non-secrets are committed; see playwright.config.ts
+
+# ─────────────────────────────────────────────────────────
+# Rules
+# ─────────────────────────────────────────────────────────
+rules:
+  - id: base-url-in-config
+    trigger: setting up E2E tests for a project with multiple environments
+    instruction: >
+      Define all environment BASE_URLs in the test framework config (playwright.config.ts /
+      cypress.config.ts) as named projects. Do not rely on .env for BASE_URL.
+    priority: required
+
+  - id: one-runner-per-env
+    trigger: adding a new deployment target
+    instruction: >
+      Create scripts/run-tests-<env>.(ps1|sh) with self-checking prerequisite steps.
+      The script must verify all required services before invoking the test runner.
+    priority: required
+
+  - id: capability-matrix-required
+    trigger: feature has external service dependencies (SMS, payment, IdP, file storage)
+    instruction: >
+      Create or update the environment capability matrix in docs/testing/.
+      Clearly mark ✅/⚠️/❌ for each service × environment combination.
+      List dimensions NOT verifiable in UAT; mark these as "PRD-only smoke" items.
+    priority: required
+
+  - id: ci-gate-mapping
+    trigger: defining CI/CD pipeline stages
+    instruction: >
+      Map each CI gate to the environments it must pass.
+      E2E gate must specify which environment it targets.
+    priority: required
+
+# ─────────────────────────────────────────────────────────
+# Relationship to Other Standards
+# ─────────────────────────────────────────────────────────
+related_standards:
+  - id: deployment-standards
+    relationship: "Extends — adds environment dimension to CI gates and deployment readiness"
+  - id: test-completeness-dimensions
+    relationship: "Complements — adds dimension 11: Environment Verifiability"
+  - id: verification-evidence
+    relationship: "Complements — evidence must specify which environment it was collected from"
+  - id: mock-boundary
+    relationship: "Complements — capability matrix references Level 2 stub server usage"

package/bundled/ai/standards/test-completeness-dimensions.ai.yaml

@@ -3,10 +3,12 @@
 
 id: test-completeness-dimensions
 meta:
-  version: "1.2.0"
-  updated: "2026-05-04"
+  version: "1.3.0"
+  updated: "2026-05-13"
   source: core/test-completeness-dimensions.md
-  description: Framework for evaluating test completeness across 10 dimensions (v1.2.0 adds Flow Completeness and Branch Coverage)
+  description: >
+    Framework for evaluating test completeness across 11 dimensions.
+    v1.3.0 adds Dimension 11: Environment Verifiability (XSPEC-204).
 
 dimensions:
   - id: 1
@@ -114,6 +116,21 @@ dimensions:
     when_required: When flow has any conditional logic or decision points
     note: Use decision_table_expansion from flow-based-testing.ai.yaml to enumerate scenarios
 
+  - id: 11
+    name: Environment Verifiability
+    description: >
+      For each AC with external service dependencies, document which environment layer
+      can fully verify it, and plan PRD-smoke coverage for items that cannot be verified in UAT.
+    test_items:
+      - Environment stratification responsibility matrix exists for features with external dependencies
+      - Each AC is tagged with its minimum verifiable environment layer (local / UAT / PRD)
+      - ACs that are PRD-only are explicitly tracked and have a PRD smoke test plan
+      - Evidence for externally-dependent ACs includes environment_layer field
+    when_required: >
+      Any feature with external service dependencies (SMS, payment, IdP, email,
+      SOAP integrations, external REST APIs)
+    note: See multi-environment-e2e-testing.ai.yaml and deployment-standards.ai.yaml for environment capability matrix templates
+
 feature_type_mapping:
   note: "Dimension 8 (AI Generation Quality) applies when tests are AI-generated"
   types:
@@ -138,8 +155,9 @@ feature_type_mapping:
       with_ai: [1, 3, 5, 8]
 
     - type: External Integration
-      dimensions: [1, 3, 7]
-      with_ai: [1, 3, 7, 8]
+      dimensions: [1, 3, 7, 11]
+      with_ai: [1, 3, 7, 8, 11]
+      note: Dimension 11 required for any external service dependency
 
     - type: Workflow / Multi-step Process
       dimensions: [1, 3, 4, 5, 9, 10]
@@ -147,6 +165,11 @@ feature_type_mapping:
       required_pattern: journey-chained-test
       note: Apply flow-based-testing standard; use shared ctx; Each-Choice minimum branch coverage
 
+    - type: External-Dependent Workflow
+      dimensions: [1, 3, 4, 5, 9, 10, 11]
+      with_ai: [1, 3, 4, 5, 9, 10, 8, 11]
+      note: Combines Workflow + External Integration; Dimension 11 mandatory
+
 error_code_coverage:
   - code: 200
     meaning: Success
@@ -198,7 +221,7 @@ anti_patterns:
 rules:
   - id: use-checklist
     trigger: designing tests for a feature
-    instruction: Use the 10 dimensions checklist to ensure completeness (dim 8 for AI-generated tests; dim 9/10 for multi-step workflows)
+    instruction: Use the 11 dimensions checklist to ensure completeness (dim 8 for AI-generated tests; dim 9/10 for multi-step workflows; dim 11 for external dependencies)
     priority: required
 
   - id: authorization-matrix
@@ -278,6 +301,12 @@ checklist_template: |
     □ Each distinct error branch has its own describe block
     □ Critical flows (auth/payment/security) use All-Combinations
 
+  □ Environment Verifiability (for features with external dependencies)
+    □ Environment stratification matrix created/updated
+    □ Each AC tagged with minimum verifiable environment layer
+    □ PRD-only ACs documented with smoke test plan
+    □ Evidence includes environment_layer field for externally-dependent ACs
+
 quick_reference:
   dimensions:
     columns: [ID, Dimension, Key Focus]
@@ -292,9 +321,10 @@ quick_reference:
       - [8, AI Generation, AI-generated test quality]
       - [9, Flow Completeness, Complete path to each terminal state]
       - [10, Branch Coverage, All decision-point branches covered]
+      - [11, Environment Verifiability, External-dep ACs tagged with environment layer]
 
   feature_dimensions:
-    note: "*Dimension 8 applies when tests are AI-generated; †Dimensions 9/10 apply to multi-step workflows"
+    note: "*Dimension 8 applies when tests are AI-generated; †Dimensions 9/10 apply to multi-step workflows; ‡Dimension 11 applies to features with external service dependencies"
     columns: [Feature Type, Required Dimensions]
     rows:
       - [CRUD API, "1,2,3,4,6,7,8*"]
@@ -304,3 +334,5 @@ quick_reference:
       - [Background Job, "1,3,5,8*"]
       - [External Integration, "1,3,7,8*"]
       - [Workflow / Multi-step Process, "1,3,4,5,9†,10†,8*"]
+      - [External Integration, "1,3,7,11‡,8*"]
+      - [External-Dependent Workflow, "1,3,4,5,9†,10†,11‡,8*"]

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

@@ -8,15 +8,19 @@ standard:
   description: 驗證證據標準，強化 anti-hallucination
 
   meta:
-    version: "1.0.0"
-    updated: "2026-03-20"
+    version: "1.1.0"
+    updated: "2026-05-13"
     source: core/verification-evidence.md
-    description: 驗證證據標準 — Iron Law: 無驗證證據不可聲稱完成
+    description: >
+      驗證證據標準 — Iron Law: 無驗證證據不可聲稱完成。
+      v1.1.0: Evidence must specify which environment layer it was collected from (XSPEC-204).
     inspired_by: superpowers/verification-before-completion
 
   guidelines:
     - "Iron Law：無驗證證據 = 不可聲稱完成"
     - "每次驗證必須記錄 command + exitCode + output + timestamp"
+    - "Iron Law（Environment）：驗收前必須確認「此環境層次能驗證此流程的哪些維度」"
+    - "驗收證據必須標明收集自哪個環境層次（local / UAT / PRD）"
     - "回歸測試必須展示 RED → GREEN 循環"
     - "代理報告 success ≠ 實際 success，需獨立驗證"
     - "驗證輸出截斷至合理長度（2000 字元）但保留關鍵資訊"
@@ -39,6 +43,13 @@ standard:
         type: string
         required: true
         description: "執行時間（ISO 8601 格式）"
+      - name: environment_layer
+        type: string
+        required: false
+        description: >
+          收集證據的環境層次（local / uat / prd）。
+          對有外部服務依賴的功能為必填——缺少此欄位時，該 AC 的驗收等級視為 local-only。
+        example: "uat"
 
   red_green_cycle:
     description: "回歸測試的 RED → GREEN 驗證"
@@ -72,13 +83,28 @@ standard:
       action: "截斷但保留錯誤訊息與摘要行"
       priority: medium
 
+  environment_rules:
+    - id: VE-005
+      trigger: "AC 涉及外部服務依賴（SMS、金流、IdP）"
+      action: >
+        驗收證據必須標明 environment_layer。
+        local-only 證據對此類 AC 不足——需確認 UAT 或 PRD 層次的驗證計畫。
+      priority: required
+    - id: VE-006
+      trigger: "有外部服務依賴的 AC 標記為 done，但無 environment_layer"
+      action: >
+        降級為 done_with_concerns。
+        要求補充環境層次聲明，或在 environment-stratification-matrix 中標記為 ⚠️/❌。
+      priority: high
+
 physical_spec:
   type: checklist
   validator:
     type: ai_review
-    rule: "檢查任務完成是否附帶驗證證據（command + exit_code + output + timestamp）"
+    rule: "檢查任務完成是否附帶驗證證據（command + exit_code + output + timestamp + environment_layer）"
   checks:
     - "完成聲明是否附帶 verification_evidence"
     - "evidence 是否包含所有必填欄位"
     - "exit_code 是否為 0（成功）"
     - "Bug fix 是否有 RED → GREEN 循環證據"
+    - "有外部服務依賴的 AC 是否標明 environment_layer"

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

@@ -83,28 +83,60 @@ Scenario: User login with valid credentials
 | **Covered** | ✅ | AC is fully tested | All conditions in AC have corresponding test assertions |
 | **Partial** | ⚠️ | AC is partially tested | Some conditions tested, but edge cases or paths missing |
 | **Uncovered** | ❌ | AC has no tests | No test case references this AC |
+| **Not Implemented** | 🚫 | AC has no corresponding implementation | Feature code does not exist (not a test gap — a code gap) |
+
+### `not_implemented` vs `uncovered` Decision Tree
+
+```
+Q1: Does the corresponding code exist in src/?
+  No → 🚫 not_implemented
+  Yes → Q2: Does any test reference this AC?
+    No → ❌ uncovered
+    Yes → Q3: Are all conditions in the AC tested?
+      Yes → ✅ covered
+      No → ⚠️ partial
+```
+
+Typical signals of `not_implemented`: `throw new NotImplementedException()`, empty stub body, `// FEATURE_STUB:` marker.
 
 ### Coverage Calculation
 
 ```
-AC Coverage % = (covered_count / total_ac_count) × 100
+AC Coverage % = (covered_count + partial_count × 0.5) / (total_ac_count - not_implemented_count) × 100
 
 Where:
   covered_count = count of AC with status "covered"
   total_ac_count = total number of AC in specification
+  not_implemented_count = count of AC with status "not_implemented" (excluded from denominator)
   partial counts as 0.5 for coverage calculation
 ```
 
 ### Example Calculation
 
 ```
-SPEC-001: 8 AC total
-  - 5 covered (✅)
-  - 2 partial (⚠️)
-  - 1 uncovered (❌)
+SPEC-001: 20 AC total
+  - 15 covered (✅)
+  - 0 partial (⚠️)
+  - 2 uncovered (❌)
+  - 3 not_implemented (🚫)
+
+Coverage = (15 + 0) / (20 - 3) × 100 = 88.2%
+Status: BLOCKED by 3 not_implemented AC(s)
+```
+
+### CI Gate for `not_implemented`
+
+`not_implemented` ACs trigger a **blocking** CI gate independent of the coverage percentage gate:
 
-Coverage = (5 + 2×0.5) / 8 = 6/8 = 75%
 ```
+[AC-NOT-IMPL] 3 AC(s) marked not_implemented:
+  🚫 AC-007  OrderCancellation
+  🚫 AC-012  RefundCalculation
+  🚫 AC-019  ExportToPDF
+All not_implemented ACs must be resolved before UAT.
+```
+
+The gate clears only when all `not_implemented` ACs are updated to `uncovered`, `partial`, or `covered`.
 
 ---
 
@@ -273,6 +305,8 @@ Generated spec MUST include:
 | Ignoring uncovered AC | Gaps in verification | Track and plan coverage for all AC |
 | AC without testability | Cannot be verified | Ensure all AC are testable |
 | Coverage without assertions | Tests run but verify nothing | Check for meaningful assertions |
+| Using `uncovered` for missing code | Hides functional completeness gap | Use `not_implemented` when code doesn't exist |
+| Including `not_implemented` in denominator | Inflates coverage metric | Exclude `not_implemented` from denominator |
 
 ---
 
@@ -291,3 +325,4 @@ Generated spec MUST include:
 | Version | Date | Changes |
 |---------|------|---------|
 | 1.0.0 | 2026-03-18 | Initial version — traceability matrix, coverage calculation, spec generation rules |
+| 1.1.0 | 2026-05-12 | Add `not_implemented` 4th status; update CI gate formula; add decision tree (XSPEC-199) |