universal-dev-standards 5.17.0 → 6.1.0

package/bundled/core/multi-environment-e2e-testing.md

@@ -0,0 +1,195 @@
+# Multi-Environment E2E Testing Standards
+
+> **Version**: 1.0.0 | **Status**: Active | **Updated**: 2026-05-13
+> **AI-optimized version**: `ai/standards/multi-environment-e2e-testing.ai.yaml`
+> **Spec**: XSPEC-204 (UDS Issue #94, #95)
+
+**Scope**: universal
+**Applicability**: Any project whose E2E tests must run against more than one deployment
+target (local, local-IIS, UAT, PRD, etc.)
+
+## Overview
+
+This standard defines how to configure E2E tests across multiple deployment targets. Its
+core principle is **Executable Environment Documentation**: *the run command IS the
+documentation*. Each environment gets one entry-point script that self-checks its own
+prerequisites and runs the correct test subset — so the script itself becomes the
+authoritative environment setup guide, instead of scattered knowledge in a README, a
+wiki page, and verbal tribal knowledge.
+
+> **Anti-pattern**: manually editing `BASE_URL` in `.env` before test runs. This breaks
+> other developers' configs and cannot be committed without affecting everyone.
+
+## Test Framework Multi-Environment Config
+
+**Rule**: `BASE_URL` is baked into the test-project config, not read from `.env`. If
+`BASE_URL` comes from `.env`, developers must edit `.env` before running against a
+specific environment — a race condition in teams, and a source of accidental commits of
+the wrong URL.
+
+Playwright — one config, one project per environment:
+
+```ts
+// 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 — pass the target via `--env target=uat`, defaulting to `local`:
+
+```ts
+// cypress.config.ts
+const ENVS = {
+  'local':  { baseUrl: 'http://localhost:3000' },
+  'uat':    { baseUrl: 'http://uat.example.com' },
+  'prd':    { baseUrl: 'https://app.example.com' },
+};
+```
+
+Rules:
+
+- One test config file; distinguish environments via project name or a `--project` /
+  `--env` flag.
+- No environment-specific `playwright.config.*.ts` / `cypress.config.*.ts` files.
+- `BASE_URL` is never sourced from `.env` for E2E test configs.
+
+## Runner Script Pattern
+
+**Rule**: each environment has one entry-point script,
+`scripts/run-tests-<env>.(ps1|sh)`, that self-checks prerequisites before invoking the
+test runner. Prerequisite checks typically cover: Docker/container runtime, application
+health endpoint, database connectivity (if separate from the app), and any other
+required environment-specific services.
+
+```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 "$@"
+```
+
+(The PowerShell equivalent follows the same three steps: check Docker, check the app
+health endpoint, then run `npx playwright test --project=<env>`.)
+
+## Environment Capability Matrix
+
+**Rule**: projects with external dependencies (HTTP services, IdP, payment, messaging)
+MUST maintain an environment capability matrix committed to the repository —
+`docs/testing/environment-capability-matrix.md` or inline in the testing README. Update
+it whenever a new external service dependency is added.
+
+```
+## 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 a 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
+```
+
+## CI Gate Mapping
+
+**Rule**: map each CI/CD stage to the environment(s) it must pass, and document which
+gate must pass before each deployment stage.
+
+```yaml
+# .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]
+```
+
+| Deployment Stage | Required Gates |
+|-------------------|-----------------|
+| Before staging deploy | unit tests, integration tests, e2e-smoke-gate |
+| Before UAT deploy | all staging gates, e2e-uat-gate (if a UAT environment is available) |
+| Before PRD deploy | e2e-uat-gate, sign-off from capability-matrix review |
+| After PRD deploy | e2e-prd-smoke, within 10 minutes of deploy |
+
+## Credential Handling
+
+**Rule**: separate what goes into git from what stays gitignored.
+
+- **Commit to git**: base URLs per environment (non-secret, team-shared), test
+  usernames for non-PRD environments, feature flags and test configuration,
+  self-check scripts with no credentials embedded.
+- **Gitignore**: passwords and secrets, API keys and tokens, `.env.test.local`
+  (personal overrides).
+- **CI secrets**: PRD test passwords are passed via CI secret variables (GitHub
+  Secrets / GitLab CI Variables) — never committed.
+
+```
+# Test credentials
+.env.test.local
+tests/fixtures/auth-secrets.json
+# Base URLs and non-secrets are committed; see playwright.config.ts
+```
+
+## Rules
+
+| Rule | Trigger | Instruction | Priority |
+|------|---------|--------------|----------|
+| `base-url-in-config` | Setting up E2E tests for a project with multiple environments | Define all environment `BASE_URL`s in the test framework config as named projects; do not rely on `.env` for `BASE_URL` | required |
+| `one-runner-per-env` | Adding a new deployment target | Create `scripts/run-tests-<env>.(ps1\|sh)` with self-checking prerequisite steps; verify all required services before invoking the test runner | required |
+| `capability-matrix-required` | Feature has external service dependencies (SMS, payment, IdP, file storage) | Create or update the environment capability matrix; mark ✅/⚠️/❌ per service × environment; list dimensions not verifiable in UAT as "PRD-only smoke" | required |
+| `ci-gate-mapping` | Defining CI/CD pipeline stages | Map each CI gate to the environment(s) it must pass; the E2E gate must specify which environment it targets | required |
+
+## Relationship to Other Standards
+
+- **`deployment-standards`** — extends: adds the environment dimension to CI gates and
+  deployment readiness.
+- **`test-completeness-dimensions`** — complements: adds dimension 11, Environment
+  Verifiability.
+- **`verification-evidence`** — complements: evidence must specify which environment it
+  was collected from.
+- **`mock-boundary`** — complements: the capability matrix references Level 2 stub-server
+  usage.
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-05-13 | Initial — executable environment documentation principle, framework config, runner scripts, capability matrix, CI gate mapping, credential handling (XSPEC-204) |

package/bundled/core/packaging-standards.md

@@ -269,6 +269,7 @@ The combination of (a) producer using auto-extension tar and (b) consumer not ve
 - [Pipeline Integration Standards](pipeline-integration-standards.md) — CI/CD pipeline configuration
 - [Checkin Standards](checkin-standards.md) — Quality gates before packaging
 - [Versioning Standards](versioning.md) — Version numbers used in package artifacts
+- [Supply Chain Attestation](supply-chain-attestation.md) — SBOM / SLSA provenance / signing of the packaged artifact (format integrity here is archive-level; attestation adds source-to-artifact provenance)
 
 ---
 

package/bundled/core/performance-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/performance-standards.md)
 
-**Version**: 1.1.0
-**Last Updated**: 2026-01-29
+**Version**: 1.2.0
+**Last Updated**: 2026-06-17
 **Applicability**: All software projects
 **Scope**: universal
 **Industry Standards**: ISO/IEC 25010 Performance Efficiency
@@ -323,6 +323,97 @@ Analogous to the SRE Error Budget concept, a Performance Budget defines the tole
 
 ---
 
+## Migration Non-Functional Parity (XSPEC-286)
+
+> Part of the [XSPEC-284](https://github.com/AsiaOstrich/universal-dev-standards) 9-axis migration completeness matrix (**axis ⑥ — non-functional**). Covers the omission class "function is correct, data is correct, but **it runs differently**" during a legacy refactor / rewrite. This section adds **migration-specific** before/after semantics on top of the general baseline/drift machinery above; it does NOT replace the general performance framework.
+
+### Why this is a real gap
+
+The general Baseline Management above answers "did *this version* regress vs *its own* prior baseline". It does NOT answer "does the **new** system match the **legacy** system it replaces". In a rewrite (e.g. PHP single-request → .NET shared-state threads) the latency/throughput/isolation characteristics of legacy are **implicit and undocumented**, so per-request functional parity and behavior-snapshot parity both pass while the system silently runs slower, exhausts a smaller pool, or loses a lock semantic.
+
+### Differential oracle, not absolute threshold
+
+Migration parity uses **legacy as the baseline** and a **declared tolerance**, not the absolute targets in the tables above. The legacy system's measured behavior is the oracle; "no regression beyond the declared tolerance" is the pass criterion. This makes divergence self-report instead of relying on someone remembering to enumerate every hot path.
+
+### Step 1 — Mechanized non-functional baseline capture (R3)
+
+Legacy non-functional characteristics are mostly implicit. Derive the baseline **mechanically** (not from memory) from legacy artifacts:
+
+| Source | Derived baseline item |
+|--------|----------------------|
+| Key routes / controllers | p50 / p95 / p99 latency per critical path |
+| Hot queries / slow-query log | Per-query latency, rows scanned |
+| Background jobs / cron | Job duration, throughput (records/min) |
+| Connection pool config | Min/max connections, idle/connection timeout |
+| Timeout / rate-limit config | Per-endpoint timeout, requests/min, burst |
+| Transaction config | Isolation level (READ COMMITTED / REPEATABLE READ / SERIALIZABLE) |
+
+The captured set is **both** the comparison baseline for the regression gate **and** the to-verify checklist for resource/limit parity (Step 4).
+
+### Step 2 — Performance regression differential gate (R1)
+
+For each baseline path, measure the corresponding path in the new system and compare against the **legacy baseline** within a declared tolerance.
+
+| Metric | Default migration tolerance | Block when |
+|--------|----------------------------|-----------|
+| p50 latency | ≤ +10% vs legacy | > +10% |
+| p95 latency | ≤ +15% vs legacy | > +15% |
+| p99 latency | ≤ +20% vs legacy | > +20% |
+| Throughput | ≤ -10% vs legacy | > -10% decrease |
+
+Tolerances are **per-path configurable** (a batch job and an interactive endpoint differ). Start in **shadow** (measure-only, do not block) to collect samples and calibrate per-path tolerances, then promote to blocking.
+
+**Gate timing**: pre-UAT (catch regression before sign-off) **and** post-cutover (catch regression that only appears under real production load).
+
+```markdown
+## Migration Performance Parity Report — <path>
+
+| Metric | Legacy baseline | New system | Δ | Tolerance | Status |
+|--------|-----------------|------------|---|-----------|--------|
+| p50 | [X]ms | [Y]ms | +[Z]% | +10% | PASS/FAIL |
+| p95 | [X]ms | [Y]ms | +[Z]% | +15% | PASS/FAIL |
+| p99 | [X]ms | [Y]ms | +[Z]% | +20% | PASS/FAIL |
+| Throughput | [X] rps | [Y] rps | -[Z]% | -10% | PASS/FAIL |
+
+**Mode**: shadow (measure-only) / blocking
+**Overall**: PASS / FAIL
+```
+
+### Step 3 — Concurrency isolation verification (R2)
+
+The same resource (same record / same account balance / same sequence number) may be accessed by multiple concurrent operations. Legacy lock / transaction-isolation / ordering guarantees are **implicit behavior** and are routinely changed by a rewrite — and **neither functional tests nor behavior-snapshot parity catch this** (per-request parity ≠ concurrency parity, the same blind spot class as "per-request ≠ data-at-rest").
+
+**Method**: drive a race with concurrent stress, then assert **domain invariants** rather than checking outputs one-at-a-time.
+
+| Invariant class | Example assertion |
+|-----------------|-------------------|
+| Conservation | `SUM(balance)` unchanged after N concurrent transfers |
+| Uniqueness | no duplicate sequence number under concurrent allocation |
+| No lost update | last-writer-wins not silently replacing a committed write |
+| Ordering | events applied in a guaranteed order under concurrency |
+
+Detecting an **isolation downgrade** (e.g. legacy SERIALIZABLE → new READ COMMITTED, or a removed row lock) blocks. The invariants themselves are domain-defined; where a concurrency case overlaps a state-transition or temporal invariant, **the state-machine / temporal concern is owned by XSPEC-287** (axis ⑧) and concurrency race is owned here (axis ⑥) — see XSPEC-287 §boundary.
+
+**Gate timing**: pre-UAT.
+
+### Step 4 — Resource / limit parity (R4)
+
+Verify that legacy resource limits are not **unintentionally** changed by the rewrite (a timeout silently dropping from 30s to 5s fails long jobs; a smaller pool serializes traffic). Add to the non-functional reconciliation checklist:
+
+- [ ] Request / operation **timeouts** match legacy (or change is declared)
+- [ ] **Rate limits** (requests/min, burst) match legacy
+- [ ] **Connection pool** min/max and idle/connection timeout match legacy
+- [ ] **Batch sizes** match legacy
+- [ ] **Transaction isolation level** matches legacy (cross-check with Step 3)
+
+Each item is either matched or has a **declared, justified** delta. An undeclared delta is a known regression risk and blocks cutover.
+
+### Completeness declaration (matrix alignment)
+
+Axis ⑥ of the migration completeness matrix is satisfied when this section declares all three: **derive** (Step 1 mechanized baseline), **oracle** (Step 2 regression differential + Step 3 invariant assertions), and **gate timing** (pre-UAT + post-cutover). Reuse the general baseline/drift and `observability-assistant` measurement machinery — this section adds only the migration before/after and concurrency-isolation semantics, it does not rebuild a general performance framework.
+
+---
+
 ## Per-Release Capacity Sign-off
 
 This section defines the **capacity gate** that must be satisfied before production release (Dimension 10 in `release-readiness-gate.md`, Tier-3).
@@ -395,6 +486,8 @@ The capacity sign-off is `N/A` (with documented rationale) when:
 - [Code Review Checklist](code-review-checklist.md) - Performance review
 - [Deployment Standards](deployment-standards.md) - Performance validation pre-deployment
 - [Release Readiness Gate](release-readiness-gate.md) - Dimension 1 (load) and Dimension 10 (capacity)
+- [Behavior Snapshot](behavior-snapshot.md) - Functional parity oracle (complements migration non-functional parity)
+- [Full Coverage Testing](full-coverage-testing.md) - Concurrency dimension cross-reference
 
 ---
 
@@ -402,6 +495,7 @@ The capacity sign-off is `N/A` (with documented rationale) when:
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.2.0 | 2026-06-17 | Added Migration Non-Functional Parity (XSPEC-286, axis ⑥): before/after differential regression gate, concurrency isolation verification, resource/limit parity, mechanized baseline capture |
 | 1.1.0 | 2026-01-29 | Refactored: Split into Rules + Guide, moved explanations to guide |
 | 1.0.0 | 2026-01-29 | Initial release |
 

package/bundled/core/pii-classification.md

@@ -0,0 +1,148 @@
+# PII Classification and Handling Standards
+
+> **Version**: 1.1.0 | **Status**: Active | **Updated**: 2026-06-19
+> **AI-optimized version**: `ai/standards/pii-classification.ai.yaml`
+> **Spec**: XSPEC-066 (cross-project/specs/XSPEC-066-uds-compliance-audit-pack.md)
+
+**Scope**: universal
+
+## Overview
+
+This standard defines how **Personally Identifiable Information (PII)** and
+sensitive personal data is classified, labeled, stored, transmitted, and disposed
+of. It covers a three-tier data-sensitivity classification, mandatory handling
+controls per tier, data-minimization principles, consent-management requirements,
+retention/deletion schedules, and cross-border transfer restrictions. It is
+aligned with GDPR Article 9, CCPA, and general privacy-by-design principles.
+
+It is part of the **compliance & audit pack** (XSPEC-066). The PII tiers it
+defines drive the masking rules executed by `logging-standards` and the
+mandatory data-access events recorded by `audit-trail`.
+
+> **Scope.** This standard defines the *classification tiers* and the *handling
+> controls* per tier. The concrete masking/tokenization library, the secrets
+> store for encryption keys, and the PIA workflow tool are adoption choices.
+
+## Requirements
+
+| ID | Rule | Level |
+|----|------|-------|
+| REQ-001 | PII data-sensitivity classification (TIER-1/2/3) | MUST |
+| REQ-002 | Data minimization and purpose limitation | MUST |
+| REQ-003 | PII masking and anonymization in non-production | MUST |
+| REQ-004 | Data retention and deletion schedule | MUST |
+| REQ-005 | Cross-border data-transfer controls | MUST |
+| REQ-006 | PII impact assessment (PIA) for new features | SHOULD |
+
+### REQ-001 — PII Data Sensitivity Classification
+
+All data fields containing personal information MUST be classified into one of
+three tiers before storage or processing:
+
+| Tier | Examples | Required controls |
+|------|----------|-------------------|
+| **TIER-1** (Highly sensitive) | Health data, financial account numbers, government IDs, biometrics, passwords, SSNs | Encryption at rest and in transit, access logging, no caching |
+| **TIER-2** (Sensitive) | Full name + contact-info combination, location history, behavioral profiles, IP addresses | Encryption in transit, access controls |
+| **TIER-3** (General PII) | First name only, country-level location, general demographics | Standard access controls |
+
+### REQ-002 — Data Minimization and Purpose Limitation
+
+Systems MUST collect only the minimum PII necessary for the explicitly stated
+purpose. Each PII field in the data model MUST have a documented business purpose
+and legal basis (consent, contract, legitimate interest, legal obligation).
+Collecting PII without a documented purpose is **PROHIBITED**. Purpose limitation
+MUST be enforced: data collected for purpose A MUST NOT be used for an unrelated
+purpose B without separate consent.
+
+### REQ-003 — PII Masking and Anonymization in Non-Production
+
+PII MUST NOT exist in non-production environments (development, staging, test)
+unless explicitly required and approved. Test/staging databases MUST use
+anonymized or synthetic data. Any approved exception MUST be time-limited,
+access-controlled, and documented. PII MUST be masked in application logs:
+email as `u***@domain.com`, phone as `+1-XXX-XXX-1234`, card numbers as
+`****-****-****-1234`.
+
+### REQ-004 — Data Retention and Deletion Schedule
+
+Every data category containing PII MUST have a documented retention schedule with
+a maximum retention period aligned to legal requirements and business need.
+Automated deletion MUST be implemented for data past its retention period.
+Deletion MUST be verifiable (deletion receipts or audit logs). Users exercising
+the right to erasure MUST receive deletion confirmation within 30 days (GDPR) or
+45 days (CCPA).
+
+### REQ-005 — Cross-Border Data Transfer Controls
+
+Transfers of TIER-1 or TIER-2 PII across national borders MUST comply with
+applicable transfer mechanisms. EU → non-adequate-country transfers MUST use
+Standard Contractual Clauses (SCCs) or Binding Corporate Rules. Data-residency
+requirements MUST be documented in the system design. Cross-border transfers MUST
+be logged with destination country and legal basis.
+
+### REQ-006 — PII Impact Assessment for New Features
+
+Any new feature or system change that introduces new PII collection or processing
+SHOULD undergo a Privacy Impact Assessment (PIA) before implementation. The PIA
+MUST document what PII is collected, the purpose, legal basis, retention period,
+third-party sharing, and risk mitigations. Features with TIER-1 PII require a
+mandatory PIA; TIER-2 is recommended.
+
+## Integration with Existing Standards
+
+- **`audit-trail`** — TIER-1/TIER-2 PII reads, exports, and erasure requests are
+  mandatory audit events.
+- **`logging-standards`** — executes the masking rules this standard mandates.
+- **`security-standards`** — encryption-at-rest/in-transit controls for TIER-1
+  reference the project's security baseline.
+- **`database-standards`** — data-dictionary fields carry the PII tier and the
+  documented purpose/legal basis from REQ-002.
+
+## PII Discovery & Hand-Off Contract
+
+The integrations above name the consumers, but a hand-off needs a defined
+**trigger, interface, owner, and state** — otherwise "drives the masking rules"
+is a claim, not a contract. This reuses the `data-contract` REQ-005
+consumer-registration model and the `agent-communication-protocol` §3
+structured-handoff shape.
+
+### Trigger — when classification fires
+
+| When | What happens |
+|------|--------------|
+| New feature design | REQ-006 PII Impact Assessment classifies every new PII field **before** implementation |
+| PR / scan time | A field carrying PII with no tier is a **blocking** finding (CI) |
+| Data-dictionary change | A `database-standards` field gains/loses a PII tier → consumers are re-notified |
+
+### Interface — what crosses
+
+The producer artifact is a **PII classification registry** entry per field:
+`{ field, tier (TIER-1/2/3), purpose, legal_basis, masking_rule, retention }`.
+Consumers register against it (per `data-contract` REQ-005) and are notified on change.
+
+### Owners & registered consumers
+
+| Party | Responsibility |
+|-------|----------------|
+| Data owner / feature author | **Produces** the classification (REQ-001 / REQ-006) |
+| `logging-standards` (consumer) | Applies `masking_rule` to TIER-1/2 in non-prod and logs |
+| `audit-trail` (consumer) | Records mandatory access / export / erasure events |
+| `security-standards` (consumer) | Enforces encryption-at-rest/in-transit for TIER-1 |
+| Privacy / compliance owner | **Notified** on any new TIER-1 field or classification change |
+
+### State transition
+
+`Found → Classified (tier assigned) → Handled (masked / encrypted / retention set) → Verified (consumer confirms the rule is applied)`.
+A field stuck in `Found` (PII with no tier) **blocks release** (REQ-001 + the PR-time trigger above).
+
+## Related Specs
+
+- XSPEC-066 — UDS compliance & audit pack (this standard's source)
+- DEC-041 — EU AI Act 2026 compliance (PII handling as a compliance pillar)
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.1.0 | 2026-06-19 | Added: PII Discovery & Hand-Off Contract (trigger / interface / owners / state) so the claimed hand-off to logging-standards / audit-trail is a defined contract, not a claim (XSPEC-292 T16) |
+| v1.0.0 | 2026-06-17 | Initial — REQ-001~006: PII tiers, data minimization, non-prod masking, retention/deletion, cross-border transfer, PIA (XSPEC-066) |

package/bundled/core/pipeline-security-gates.md

@@ -2,7 +2,7 @@
 
 ## 概述
 
-本標準定義嵌入 CI pipeline 各階段的安全檢查點，涵蓋 SAST、DAST、SCA（含 SBOM）和機密掃描，並明確規定各類發現的阻斷（Block）、警告（Warn）、記錄（Log）行為。
+本標準定義嵌入 CI pipeline 各階段的安全檢查點，涵蓋 SAST、DAST、SCA（含 SBOM）、機密掃描，以及發布前的供應鏈簽章驗證，並明確規定各類發現的阻斷（Block）、警告（Warn）、記錄（Log）行為。
 
 ---
 
@@ -11,6 +11,7 @@
 - **機密掃描在 pre-commit**：所有包含機密的提交都必須被阻擋，不得例外
 - **SAST 在建置後**：Critical 和 High 等級發現阻斷 pipeline
 - **SCA + SBOM 在封包階段**：追蹤相依套件風險並產生物料清單
+- **Attestation 驗證在發布前**：封包後、部署前 MUST 驗證 artifact 的 checksum、簽章與 SLSA provenance（消費 supply-chain-attestation 標準的產出，不得「產生 SBOM 卻不驗」）
 - **DAST 在 staging 部署後**：對運行中的應用進行動態掃描
 - **安全閘門失敗 = pipeline 失敗**：不得視為可忽略的警告
 - **任何繞過都需審計軌跡**：禁止靜默跳過安全閘門
@@ -58,7 +59,24 @@
 
 ---
 
-### 4. Post-Staging Deploy — DAST（動態應用安全測試）
+### 4. Pre-Deploy — Artifact Attestation Verification（供應鏈簽章驗證）
+
+| 項目 | 說明 |
+|------|------|
+| 驗證範圍 | 已封包的發布 artifact（檔案壓縮檔 / 容器映像）|
+| 推薦工具 | cosign（`verify-blob` / `verify`）、sha256sum、slsa-verifier |
+| 阻斷條件 | 簽章驗證失敗、checksum 不符、SLSA provenance 缺失 |
+| 警告條件 | SLSA 等級低於目標（公開發布建議 ≥ L2）|
+
+封包階段（gate 3）產生 SBOM 後，**部署/發布前 MUST 驗證** artifact 的完整性與來源證明，
+避免「產生了 SBOM/簽章卻從不驗證」的假保證：比對 `checksums.txt` 的 SHA256、以
+`cosign verify-blob` 驗 SBOM 與 provenance 簽章、確認 SLSA provenance 存在。完整的
+產生與驗證指令、Release Bundle 結構見
+[supply-chain-attestation.md](supply-chain-attestation.md)。
+
+---
+
+### 5. Post-Staging Deploy — DAST（動態應用安全測試）
 
 | 項目 | 說明 |
 |------|------|
@@ -97,6 +115,7 @@
 |---------|------|
 | 機密管理 | 整合 HashiCorp Vault 或 AWS Secrets Manager 進行機密注入 |
 | SBOM 註冊表 | 上傳 SBOM 至 dependency-track 或 grype-db 持續監控 |
+| Artifact 簽章 | 發布前以 cosign 驗證 SBOM/provenance 簽章與 checksum（見 supply-chain-attestation）|
 | 事故回應 | Critical 發現自動建立事故單 |
 
 ---
@@ -106,6 +125,7 @@
 - [security-standards.md](security-standards.md) — 應用安全基礎標準
 - [pipeline-integration-standards.md](pipeline-integration-standards.md) — CI 管線整合標準
 - [deployment-standards.md](deployment-standards.md) — 部署基礎原則
+- [supply-chain-attestation.md](supply-chain-attestation.md) — SBOM / SLSA provenance / cosign 簽章的產生與驗證（gate 4 消費）
 - AI 格式：[../ai/standards/pipeline-security-gates.ai.yaml](../ai/standards/pipeline-security-gates.ai.yaml)
 
 

package/bundled/core/postmortem-standards.md

@@ -255,6 +255,8 @@ For lower-severity or recurring incidents that don't warrant a full postmortem:
 | **Mitigate** | Reduce impact scope and duration | Implement automatic circuit breaker |
 | **Process** | Improve response procedures | Update on-call handoff checklist |
 
+> **Hand-off to tech-debt tracking**: a Prevent/Mitigate action item that is a long-lived design/architecture remediation (not a quick fix that closes with the incident) MUST be registered in the tech-debt registry per [tech-debt-standards](tech-debt-standards.md) with `Source = postmortem PM-<id>` — so it is budgeted and tracked rather than lost once the incident closes.
+
 ### Status Tracking
 
 ```

package/bundled/core/prd-standards.md

@@ -0,0 +1,91 @@
+# Product Requirements Document Standards
+
+> **Version**: 1.0.0 | **Status**: Active | **Updated**: 2026-06-17
+> **AI-optimized version**: `ai/standards/prd-standards.ai.yaml`
+> **Spec**: XSPEC-069 (cross-project/specs/XSPEC-069-uds-product-layer-pack.md)
+
+**Scope**: universal
+
+## Overview
+
+This standard defines the structure, content requirements, and lifecycle
+governance for **Product Requirements Documents (PRDs)**. It covers the five
+mandatory PRD sections, the bridge from PRD requirements to traceable user
+stories, and the revision policy for changes after kickoff. It ensures product
+intent is clearly communicable to engineering, design, and stakeholders with
+measurable success criteria.
+
+It is part of the **product-layer pack** (XSPEC-069). The PRD is the *upstream*
+of engineering requirements: PRD → user story → requirement. It bridges to
+`requirement-engineering` (the engineering view of requirements) and consumes
+`product-metrics-standards` for success metrics.
+
+> **Scope.** This standard defines the *PRD artifact* (sections, traceability,
+> revision policy). It is a product-layer edge of UDS (per XSPEC-070
+> `standard-admission-criteria`) — the engineering requirement view stays in
+> `requirement-engineering`.
+
+## Requirements
+
+| ID | Rule | Level |
+|----|------|-------|
+| REQ-001 | PRD five sections (Problem, Persona, Success Metrics, Scope, Constraints) | MUST |
+| REQ-002 | PRD → user-story bridge (INVEST, traceable to a success metric) | MUST |
+| REQ-003 | Revision policy (formal change process after kickoff) | MUST |
+
+### REQ-001 — PRD Five Sections
+
+Every PRD MUST contain five sections in order: (1) **Problem Statement** — the
+user pain/opportunity in observable terms, with quantitative data where
+available; (2) **Target User / Persona** — who is affected, referencing named
+personas (≥1 primary, ≥1 secondary) with role, context, and goals;
+(3) **Success Metrics** — 2–4 measurable outcomes, each with current baseline,
+target value, and measurement method; (4) **Scope In / Out** — explicit
+inclusions and exclusions (out-of-scope may reference future PRDs);
+(5) **Constraints** — technical, regulatory, time, budget, or dependency bounds.
+
+### REQ-002 — PRD to User Story Bridge
+
+Each PRD requirement MUST be broken into one or more user stories following the
+INVEST criteria from `requirement-engineering`. Every story derived from a PRD
+MUST be traceable to at least one PRD success metric; stories that cannot be
+linked MUST be flagged for PM review before entering the backlog. The
+traceability link (PRD section ID → user-story ID → success metric) MUST be
+maintained in the backlog tool or as a matrix in the PRD.
+
+### REQ-003 — Revision Policy
+
+PRD changes requested after the development kickoff meeting MUST follow a formal
+process: (1) the proposed change is documented with rationale and impact
+assessment; (2) stakeholder sign-off is obtained from PM, Tech Lead, and Design
+Lead; (3) scope impact is assessed — added scope must move a corresponding item
+out of scope or adjust the timeline; (4) version history is updated with date,
+author, change summary, and approver. PRDs modified after kickoff without version
+history are non-compliant. Minor editorial changes (typos, formatting) are exempt
+from sign-off.
+
+## Anti-Patterns
+
+- PRD without measurable success metrics (qualitative goals only, e.g. "improve UX").
+- Scope creep without a change log: adding requirements mid-sprint without documented approval.
+- Solution-first PRD: implementation details before the user problem is established.
+- No explicit out-of-scope section, causing boundary disputes during development.
+- Success metrics defined after development starts, making them unverifiable.
+
+## Integration with Existing Standards
+
+- **`requirement-engineering`** — PRD requirements decompose into INVEST user stories.
+- **`product-metrics-standards`** — PRD success metrics draw from the metric hierarchy.
+- **`user-story-mapping`** — PRD scope is realized as a story map and MVP slice.
+- **`acceptance-criteria-traceability`** — stories carry AC traceable back to PRD metrics.
+
+## Related Specs
+
+- XSPEC-069 — UDS product-layer pack (this standard's source)
+- XSPEC-070 — Governance meta-standards (`standard-admission-criteria` edge review)
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-06-17 | Initial — REQ-001~003: five sections, PRD→story bridge, revision policy (XSPEC-069) |