universal-dev-standards 5.5.0 → 5.6.0

package/bundled/core/browser-compatibility-standards.md

@@ -0,0 +1,220 @@
+# Browser Compatibility Standards
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/browser-compatibility-standards.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-05-05
+**Applicability**: Frontend projects (web apps, progressive web apps, web components)
+**Scope**: universal
+**Industry Standards**: Browserslist, W3C WebDriver, WebDriver BiDi
+**References**: [caniuse.com](https://caniuse.com/), [Playwright browser support matrix](https://playwright.dev/docs/browsers)
+
+---
+
+## Purpose
+
+This standard defines supported browser and device matrices, testing automation strategies, and the release gate for browser compatibility (Dimension 9 in `release-readiness-gate.md`, Tier-3).
+
+Browser compatibility issues are among the most user-visible defects, yet they are systematically under-tested because teams assume "it works in Chrome." Without an explicit supported matrix and automated verification, regressions slip to production and affect large user segments.
+
+---
+
+## Support Tier Definitions
+
+| Tier | Definition | Release Gate |
+|------|-----------|--------------|
+| **Tier-1** (Supported) | Full feature parity + automated test coverage | 100% pass — blocks release if any test fails |
+| **Tier-2** (Partial support) | Best-effort; major flows must work | ≥ 95% pass — WARN if below, FAIL if < 90% |
+| **Tier-3** (Best effort) | Not officially supported; defects logged but not blocking | Advisory only |
+
+---
+
+## Default Browser Matrix
+
+Teams MUST declare their supported matrix explicitly. The defaults below cover the majority of web traffic (2025–2026 data):
+
+### Tier-1 (Default)
+
+| Browser | Versions | Platform |
+|---------|----------|---------|
+| Chrome | latest, latest-1 | Windows, macOS, Linux, Android |
+| Safari | latest, latest-1 | macOS, iOS |
+| Firefox | latest | Windows, macOS, Linux |
+| Edge | latest | Windows, macOS |
+
+### Tier-2 (Default)
+
+| Browser | Versions | Platform |
+|---------|----------|---------|
+| Chrome | latest-2, latest-3 | Desktop |
+| Safari | latest-2 | macOS, iOS |
+| Samsung Internet | latest | Android |
+| Opera | latest | Desktop |
+
+### Tier-3 (Default)
+
+| Browser | Notes |
+|---------|-------|
+| IE 11 | EOL; only if contractually required |
+| Chrome < latest-3 | Tracked as known limitation |
+
+### Device / Viewport Matrix
+
+| Category | Min Width | Representative Device |
+|----------|-----------|-----------------------|
+| Mobile (small) | 360px | Android (small) |
+| Mobile (standard) | 390px | iPhone 14 |
+| Tablet (portrait) | 768px | iPad |
+| Tablet (landscape) | 1024px | iPad landscape |
+| Desktop (small) | 1280px | Laptop 13" |
+| Desktop (standard) | 1440px | Laptop 15" / External monitor |
+| Desktop (wide) | 1920px | Full HD monitor |
+
+Minimum: test at **360px, 768px, 1280px** (mobile / tablet / desktop breakpoints).
+
+---
+
+## Automated Testing
+
+### Playwright Matrix Configuration
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  projects: [
+    // Tier-1 browsers
+    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
+    { name: "webkit", use: { ...devices["Desktop Safari"] } },
+    { name: "edge", use: { ...devices["Desktop Edge"] } },
+    // Mobile Tier-1
+    { name: "mobile-chrome", use: { ...devices["Pixel 7"] } },
+    { name: "mobile-safari", use: { ...devices["iPhone 14"] } },
+    // Viewport coverage
+    { name: "tablet", use: { ...devices["iPad Pro 11"] } },
+  ],
+  // Tier-1 failure = build failure
+  reporter: [["html"], ["junit", { outputFile: "results/browser-compat.xml" }]],
+});
+```
+
+### CI Execution Strategy
+
+```bash
+# Run full Tier-1 matrix on release candidate
+npx playwright test --project=chromium,firefox,webkit,edge,mobile-chrome,mobile-safari,tablet
+
+# Run Tier-1 only on every PR (fast feedback)
+npx playwright test --project=chromium,firefox,webkit
+
+# Run Tier-2 on release candidate (results feed into sign-off as WARN/PASS)
+npx playwright test --project=samsung,opera
+```
+
+### Cloud Browser Testing
+
+For Tier-1 cross-OS testing (e.g., Safari on Windows-hosted CI), use cloud services:
+
+| Service | Use Case |
+|---------|---------|
+| BrowserStack Automate | Commercial projects; widest OS+browser matrix |
+| Sauce Labs | Enterprises with existing contract |
+| LambdaTest | Open-source / cost-sensitive projects |
+
+**Minimum cloud testing**: Safari latest + latest-1 on real iOS devices (Simulator is insufficient for WebKit bugs).
+
+---
+
+## Visual Regression (Optional but Recommended)
+
+Pixel-diff testing detects layout regressions across browsers:
+
+```bash
+# Using Playwright visual comparisons
+npx playwright test --update-snapshots  # update baseline
+npx playwright test                     # compare against baseline; fail if diff > threshold
+```
+
+Threshold recommendation: < 0.5% pixel diff for layout components; < 2% for complex interactive components.
+
+---
+
+## Release Gate Criteria
+
+This is **Dimension 9** in `release-readiness-gate.md` (Tier-3: required for frontend/web projects; `N/A` for CLI/backend-only).
+
+| Gate | Pass | Warn | Fail |
+|------|------|------|------|
+| Tier-1 browser matrix | 100% tests pass | — | Any test fails |
+| Tier-2 browser matrix | ≥ 95% pass | 90–95% | < 90% |
+| Viewport coverage (360/768/1280) | No layout breaks on any Tier-1 browser | — | Any critical flow unusable |
+
+### Evidence for Sign-off
+
+```
+| 9 | Browser / Device Compat | PASS | Playwright: 6 browsers × 7 viewports, 100% Tier-1; Tier-2: 97%; [junit report link] | QA Lead |
+```
+
+### `N/A` Criteria
+
+Mark as `N/A` when:
+- Project is CLI-only, pure backend API, or mobile native (not web)
+- Document rationale: `"N/A — backend API service, no browser UI"`
+
+---
+
+## Browserslist Configuration
+
+Commit a `.browserslistrc` to the repo root to ensure build tools (Babel, PostCSS, Autoprefixer) target the same browsers:
+
+```
+# .browserslistrc
+# Tier-1: production targets
+last 2 Chrome versions
+last 2 Firefox versions
+last 2 Safari versions
+last 2 Edge versions
+last 2 iOS versions
+last 2 ChromeAndroid versions
+
+# Tier-2: for reference (not in build targets by default)
+# last 4 Chrome versions
+# Samsung Internet >= 14
+```
+
+---
+
+## Anti-Patterns
+
+- **Testing only Chrome** — Chrome represents ~65% of desktop traffic; the remaining 35% is Safari/Firefox/Edge users who will find your bugs
+- **Using browser simulators for iOS Safari testing** — WebKit on Simulator diverges from real device WebKit; always test on real iOS for release candidates
+- **Not specifying a matrix** — implicit assumption of "all browsers" is impossible to test; an explicit Tier-1 matrix is better than implicit coverage of none
+- **Treating Tier-3 browser failures as blockers** — Tier-3 is best-effort; logging the issue is appropriate, not blocking the release
+- **Skipping mobile viewport testing** — mobile-first is standard; missing 360px tests will produce broken UX for the majority of mobile users
+
+---
+
+## Relationship to Other Standards
+
+- **`accessibility-standards.md`** — keyboard nav and screen reader tests run across Tier-1 browsers
+- **`e2e-testing.md`** — Playwright matrix config extends E2E tests to multi-browser
+- **`release-readiness-gate.md`** — Dimension 9 (Tier-3)
+- **`performance-standards.md`** — Core Web Vitals targets apply per Tier-1 browser
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-05-05 | Initial release: Tier-1/2/3 matrix, Playwright config, cloud testing, release gate criteria |
+
+---
+
+## License
+
+This standard is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/core/checkin-standards.md

@@ -1121,6 +1121,7 @@ auto_fix:
 - [Acceptance Criteria Traceability](acceptance-criteria-traceability.md) - AC coverage verification
 - [Change Batching Standards](change-batching-standards.md) - Batch threshold triggers
 - [Pipeline Integration Standards](pipeline-integration-standards.md) - Automated check-in
+- [Release Readiness Gate](release-readiness-gate.md) - **Check-in ≠ release readiness**: passing per-commit gates is necessary but not sufficient for production; see the 16-dimension release gate for what "done" means at release time
 
 ---
 

package/bundled/core/contract-testing-standards.md

@@ -0,0 +1,182 @@
+# Contract Testing Standards
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/contract-testing-standards.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-05-05
+**Applicability**: Projects with API consumers (service-to-service, frontend-to-backend, public API)
+**Scope**: universal
+**Industry Standards**: Consumer-Driven Contract Testing (CDCT), Pact Specification v3
+**References**: [pact.io](https://docs.pact.io/), [Spring Cloud Contract](https://spring.io/projects/spring-cloud-contract)
+
+---
+
+## Purpose
+
+Contract testing verifies that a provider (API server) and its consumers (clients) agree on the exact interface — request format, response schema, and status codes — without requiring both sides to be deployed simultaneously.
+
+Without contract testing:
+- Provider changes silently break consumers in production
+- Integration tests between services require full environments
+- API versioning decisions are made without evidence of actual usage
+
+This standard formalizes consumer-driven contract testing as a **release gate** (Dimension 4 in `release-readiness-gate.md`, Tier-3).
+
+---
+
+## Consumer-Driven Contract Flow
+
+```
+Consumer writes interaction expectations
+        ↓
+Consumer publishes contract to Pact Broker
+        ↓
+Provider CI fetches consumer contracts
+        ↓
+Provider verifies it can fulfill each interaction
+        ↓
+Pact Broker records: can-i-deploy result
+        ↓
+Release gate: ALL consumer contracts GREEN before provider deploy
+```
+
+---
+
+## Contract Scope
+
+A contract covers:
+
+| Element | Must Specify | Notes |
+|---------|-------------|-------|
+| Request method | Yes | GET / POST / PUT / PATCH / DELETE |
+| Request path | Yes | Including path params |
+| Request headers | Required only | Do not over-specify optional headers |
+| Request body schema | Yes (for write operations) | Schema-level, not literal values |
+| Response status | Yes | All expected status codes |
+| Response body schema | Yes | Schema-level; use matchers not literals |
+| Response headers | Required only | e.g., `Content-Type` |
+
+**Under-specification is preferred over over-specification.** Only assert what the consumer actually uses.
+
+---
+
+## Backward Compatibility Window
+
+| Release Type | Compatibility Requirement |
+|-------------|--------------------------|
+| Patch | 100% backward compatible; no contract changes expected |
+| Minor | N-1 consumer contract version must still pass |
+| Major | Deprecation period required; consumers notified; old contract archived |
+
+**Breaking change policy**: A provider MAY NOT deploy if any active consumer contract is red. Breaking changes require:
+1. New provider version with additive-only changes
+2. Consumer migration to new version
+3. Old contract explicitly deprecated and archived
+
+---
+
+## Release Gate Criteria
+
+| Criterion | Hard Minimum | Warn Band |
+|-----------|-------------|-----------|
+| All active consumer contracts | 100% green | — (binary: all or nothing) |
+| N-1 backward compatibility | 100% green | — |
+| Deprecated contract cleanup | Old contracts archived within 30 days | > 30 days = WARN |
+
+The `can-i-deploy` command in the Pact Broker encapsulates this gate:
+
+```bash
+pact-broker can-i-deploy \
+  --pacticipant <provider-service> \
+  --version <version> \
+  --to-environment production
+```
+
+Exit code 0 = PASS; non-zero = FAIL (blocks release).
+
+---
+
+## Implementation Guidelines
+
+### Consumer Side
+
+```typescript
+// Pact consumer test (TypeScript example)
+const interaction = {
+  state: "user 42 exists",
+  uponReceiving: "a request for user 42",
+  withRequest: {
+    method: "GET",
+    path: "/users/42",
+    headers: { Accept: "application/json" },
+  },
+  willRespondWith: {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+    body: like({           // schema matcher, not literal
+      id: integer(),
+      name: string(),
+      email: email(),
+    }),
+  },
+};
+```
+
+### Provider Side
+
+```bash
+# Provider verification in CI
+PACT_BROKER_BASE_URL=https://pact-broker.internal \
+PACT_PROVIDER_VERSION=$GIT_SHA \
+npm run test:pact:provider
+```
+
+### Pact Broker Tags
+
+| Tag | Meaning |
+|-----|---------|
+| `main` | Latest from main branch |
+| `production` | Currently deployed to production |
+| `<feature-branch>` | Feature branch contracts (transient) |
+
+---
+
+## Anti-Patterns
+
+- **Testing the full API surface** — test only what consumers actually consume; over-specification causes unnecessary contract breaks
+- **Literal value matching** — use schema matchers (`like()`, `eachLike()`, `integer()`) not exact values; contracts should tolerate realistic data variation
+- **Skipping provider verification** — publishing a consumer contract without provider verification means the contract has no enforcement value
+- **Not running `can-i-deploy`** — checking individual contract status is insufficient; `can-i-deploy` evaluates the entire deployment matrix
+
+---
+
+## Relationship to Other Standards
+
+- **`api-design-standards.md`** — contract testing enforces backwards-compat guarantees stated in API design
+- **`release-readiness-gate.md`** — Dimension 4 (Tier-3: applies when API consumers exist)
+- **`integration-testing.md`** — contract tests complement but do not replace integration tests
+- **`versioning.md`** — semantic versioning interacts with backward compatibility window above
+
+---
+
+## See Also
+
+- [Pact Documentation](https://docs.pact.io/)
+- [Can I Deploy](https://docs.pact.io/pact_broker/can_i_deploy)
+- [Consumer-Driven Contracts](https://martinfowler.com/articles/consumerDrivenContracts.html) — Martin Fowler
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-05-05 | Initial release: consumer-driven contract flow, backward compat window, release gate criteria |
+
+---
+
+## License
+
+This standard is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/core/cross-flow-regression.md

@@ -0,0 +1,190 @@
+# Cross-Flow Regression
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/cross-flow-regression.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-05-05
+**Applicability**: All software projects with multiple user flows or business processes
+**Scope**: universal
+**Industry Standards**: ISTQB Advanced Test Analyst (Regression Test Strategy)
+**References**: `core/flow-based-testing.md`, `core/testing-standards.md`
+
+---
+
+## Purpose
+
+This standard defines cross-flow regression testing — verifying that changes to one flow do not break other flows, and that **combinations of flows** behave correctly when executed in sequence.
+
+### Boundary with `flow-based-testing.md`
+
+| Standard | Scope | What It Catches |
+|----------|-------|----------------|
+| `flow-based-testing.md` (Multi-Gate Model) | Single flow: Decision Points, Terminal States, Decision Table | Intra-flow branch coverage gaps |
+| **This standard** | Multiple flows: interaction, shared state, sequential composition | Inter-flow contamination, accumulated-state bugs, regression across flows |
+
+These are complementary, not overlapping. A project needs both.
+
+---
+
+## Why Cross-Flow Bugs Are Distinct
+
+Intra-flow testing (Multi-Gate) proves that "Login" handles all 7 terminal states. But it cannot detect:
+
+- **State contamination**: after a failed "Create Order" (FAIL_QUOTA_EXCEEDED), the quota counter is corrupted → next "Create Order" attempt fails even after quota resets
+- **Shared resource conflicts**: "Report Generation" and "Data Export" running concurrently corrupt a shared temp directory
+- **Sequential dependency**: "Cancel Subscription" succeeds, but the subsequent "Reactivate" flow assumes subscription still exists → NullPointerException
+
+---
+
+## Cross-Flow Test Suite Definition
+
+### Tier-1: Critical User Journeys (CUJ)
+
+Critical User Journeys are end-to-end sequences spanning ≥ 2 flows that represent core business value paths. Every release must include a CUJ regression suite.
+
+**CUJ identification**:
+1. List all flows (from requirement-template §2.4)
+2. Identify pairs/triples that share state or are commonly executed in sequence
+3. Tag business-critical combinations (purchase, onboarding, authentication + downstream)
+
+**CUJ Coverage Requirement**:
+
+| Metric | Tier-2 Threshold (default) | Tier-1 Critical Path |
+|--------|--------------------------|---------------------|
+| CUJ pass rate | ≥ 95% | 100% |
+| Business-critical flow combos | 100% | 100% |
+
+### Tier-2: Regression on Flow Change
+
+When any flow's §2.4 (Decision Points, Terminal States) is modified, the full CUJ suite must re-run — not just the tests for the changed flow. The triggering logic:
+
+```bash
+# In CI: detect flow spec changes
+changed_flows=$(git diff origin/main... --name-only | grep -E "requirement-template|SPEC.*\.md")
+if [ -n "$changed_flows" ]; then
+  npm run test:cross-flow-regression
+fi
+```
+
+### Tier-3: Concurrency and Shared Resource Tests
+
+For projects with concurrent user operations:
+- Two users executing the same flow simultaneously
+- Flow A and Flow B sharing a write resource
+- Long-running Flow (async) interacting with a short Flow result
+
+---
+
+## Test Structure
+
+Cross-flow regression tests use **sequential state threading** across flows (extending the `ctx` pattern from `flow-based-testing.md`):
+
+```typescript
+describe("CUJ: Register → Verify Email → Create First Order", () => {
+  const ctx: {
+    userId?: string
+    token?: string
+    orderId?: string
+  } = {}
+
+  // Flow 1: Register
+  it("Flow-1 Step 1: Register new user", async () => {
+    ctx.userId = await registerUser({ email: testEmail, plan: "trial" })
+    expect(ctx.userId).toBeDefined()
+  })
+
+  // Flow 2: Email Verification (depends on Flow 1 output)
+  it("Flow-2 Step 1: Verify email token", async () => {
+    const token = await getEmailToken(ctx.userId!)
+    ctx.token = await verifyEmail(token)
+    expect(ctx.token).toBeDefined()
+  })
+
+  // Flow 3: Create Order (depends on Flow 2 auth token)
+  it("Flow-3 Step 1: Create first order", async () => {
+    ctx.orderId = await createOrder(ctx.token!, orderPayload)
+    expect(ctx.orderId).toMatch(/^ord-/)
+  })
+
+  // Cross-flow verification: order state reflects trial plan limits
+  it("Cross-flow: Trial plan quota enforced on first order", async () => {
+    const order = await getOrder(ctx.token!, ctx.orderId!)
+    expect(order.quota_applied).toBe("trial")
+  })
+})
+```
+
+### Cross-Flow Failure Isolation
+
+When a cross-flow test fails, the failure message must identify **which flow** introduced the state corruption:
+
+```typescript
+// BAD: generic assertion
+expect(result).toBe("success")
+
+// GOOD: includes flow context
+expect(result).toBe("success")  // Flow-3 depends on Flow-2 token being valid
+                                 // If this fails, check Flow-2 email verification output
+```
+
+---
+
+## Release Gate Integration
+
+Cross-flow regression is **Dimension 6** in `release-readiness-gate.md` (Tier-2).
+
+### Trigger Conditions
+
+| Trigger | Scope |
+|---------|-------|
+| Every release candidate | Full CUJ suite |
+| PR modifying any flow §2.4 | Full CUJ suite (pre-merge) |
+| Post-deploy to staging | Smoke subset of CUJ |
+| Post-deploy to production | Critical path CUJ only (canary) |
+
+### Evidence for Sign-off
+
+```
+| 6 | Cross-flow Regression | PASS | CUJ suite: 47/47 passed; 0 flow-interaction failures | QA Lead |
+```
+
+### WARN Threshold
+
+- ≥ 95% CUJ pass rate but < 100% → WARN with specific failed CUJ documented and root-caused
+- < 95% CUJ pass rate → FAIL (release blocked)
+- Business-critical combo fails → FAIL regardless of overall rate
+
+---
+
+## Anti-Patterns
+
+- **Running cross-flow tests only when CI is slow** — they must run on every release candidate by definition
+- **Testing each flow in isolation and calling it "regression"** — flow isolation is covered by Multi-Gate; cross-flow must have inter-flow state dependencies
+- **Reusing the same `ctx` object across unrelated `describe` blocks** — each CUJ needs a clean, isolated `ctx`; contamination between CUJs masks bugs
+- **No flow attribution in failure messages** — cross-flow failures are hard to debug; always indicate which upstream flow produced the corrupted state
+- **Treating CUJ failures as flaky** — cross-flow state bugs are deterministic; "flaky" cross-flow tests are almost always a symptom of shared state corruption
+
+---
+
+## Relationship to Other Standards
+
+- **`flow-based-testing.md`** — intra-flow gate (prerequisite for cross-flow)
+- **`testing-standards.md`** — regression layer in the testing pyramid
+- **`release-readiness-gate.md`** — Dimension 6 (Tier-2)
+- **`e2e-testing.md`** — CUJ tests typically run at E2E or System Test level
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-05-05 | Initial release: CUJ definition, sequential state threading, release gate criteria, Tier-1/2/3 classification |
+
+---
+
+## License
+
+This standard is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)