universal-dev-standards 5.5.0 → 5.7.0

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)

package/bundled/core/disaster-recovery-drill.md

@@ -8,7 +8,7 @@ An untested DR plan is a false sense of security. Teams that have never executed
 
 Define these before writing the runbook:
 
-| Metric | Definition | VibeOps Commercial Target |
+| Metric | Definition | Commercial-grade Target |
 |--------|-----------|--------------------------|
 | RTO (Recovery Time Objective) | Max acceptable downtime | < 1 hour |
 | RPO (Recovery Point Objective) | Max acceptable data loss | < 24 hours (daily backup) |
@@ -20,9 +20,9 @@ Define these before writing the runbook:
 # scripts/backup-restore.sh — DR drill backup restore verification
 set -euo pipefail
 
-BACKUP_DIR="${BACKUP_DIR:-/var/backups/vibeops}"
+BACKUP_DIR="${BACKUP_DIR:-/var/backups/app}"
 RESTORE_DIR="${RESTORE_DIR:-/tmp/dr-restore}"
-DB_FILE="${DB_FILE:-vibeops.db}"
+DB_FILE="${DB_FILE:-app.db}"
 
 echo "=== DR Drill: Backup Restore Verification ==="
 echo "Source: ${BACKUP_DIR}/${DB_FILE}.backup"

package/bundled/core/dual-phase-output.md

@@ -47,7 +47,7 @@ Applications may add fields inside `<summary>` but must not remove core fields:
 |----------|---------|
 | Single review | 1000–3500 tokens |
 | Fix Loop (3× retries) | 3000–10500 tokens |
-| VibeOps pipeline (evaluator + guardian) | 2000–7000 tokens per run |
+| Multi-agent pipeline (evaluator + guardian; adoption layer) | 2000–7000 tokens per run |
 
 ## References
 

package/bundled/core/failure-source-taxonomy.md

@@ -55,12 +55,12 @@ interface FailureDetail {
 - `failureSource` is an **optional** field — must not break existing code without this field
 - Select the most fundamental source as `failureSource` in a single failure event
 - `failureSource` should be set by the component that detects the failure
-- DevAP and VibeOps each define `FailureSource` type independently (AGPL isolation)
+- Adoption layers each define their own `FailureSource` type independently (license isolation)
 
 ## Applicable Scenarios
 
-- DevAP QualityGate failure result enrichment
-- VibeOps PipelineRunner `agent:error` event payload
+- Quality Gate (adoption layer) failure result enrichment
+- Pipeline Runner (adoption layer) `agent:error` event payload
 - Recovery Recipe Registry (XSPEC-046) match key
 - Telemetry failure analytics dimension
 

package/bundled/core/flow-based-testing.md

@@ -1,7 +1,7 @@
 # Flow-Based Testing
 
-**Version**: 1.0.0
-**Last Updated**: 2026-05-04
+**Version**: 1.3.0
+**Last Updated**: 2026-05-05
 **Applicability**: All software projects with multi-step workflows
 **Scope**: universal
 **Industry Standards**: ISO/IEC/IEEE 29119-4 (Test Techniques), ISTQB Foundation Syllabus
@@ -118,6 +118,139 @@ describe("Flow Branch: Quota exceeded path", () => {
 
 ---
 
+## Multi-Gate Flow Verification Model
+
+Flow coverage is not a single pre-release check — it is a **progressive verification chain** across the entire SDLC. There are two fundamentally different questions that must be answered at different stages:
+
+| Verification Type | Question | Executor | Timing |
+|------------------|----------|----------|--------|
+| **Coverage** | Are all terminal states tested? | Automated CI | Dev → Staging → Pre-UAT |
+| **Correctness** | Are the terminal state definitions right? | Human UAT | UAT phase |
+
+Confusing the two wastes UAT cycles on technical coverage issues that CI should have caught.
+
+### Gate 0 — PRD Sign-off (Before Implementation Starts)
+
+The three testability elements MUST be written into the PRD before a single line of code is written. Use `templates/requirement-template.md` §2.4 and §9.4:
+
+| Element | PRD Section | When Required |
+|---------|-------------|---------------|
+| Preconditions + Ordered Steps | §2.4 | Flows with ≥ 3 steps |
+| Decision Points list | §2.4 | Every branch condition |
+| Terminal States list | §2.4 | All distinct end states |
+| Decision Table (Each-Choice) | §9.4 | All flows |
+| Upgrade to All-Combinations | §9.4 | Auth / payment / security |
+| UAT acceptance script (pre-filled) | §9.4 | Before PRD approval |
+
+> **Why at PRD stage?** Test engineers cannot derive branch coverage from a spec that only describes the happy path. Discovering missing decision points during test design wastes a full sprint.
+
+### Gate 1 — PR Merge (Per Feature Branch)
+
+Every PR that touches a flow with ≥ 3 steps MUST include automated tests covering the terminal states introduced or modified by that PR. Reviewers block merge if terminal states are added to §2.4 without corresponding tests.
+
+### Gate 3 — Pre-UAT Deployment (Automated + QA Lead Sign-off)
+
+CI must prove coverage completeness **before** UAT begins. UAT is for correctness validation, not technical testing.
+
+Required CI checks:
+- All Decision Table scenarios have a passing automated test
+- Zero terminal states without test coverage
+- Branch coverage ≥ 90% (or project-defined threshold)
+- All-Combinations fully passing for auth / payment / security flows
+
+> Deploying to UAT without Gate 3 forces business stakeholders to act as technical QA — a costly and demoralizing misuse of UAT time.
+
+### Gate 4 — UAT Sign-off (Business Correctness, Pre-Production)
+
+UAT validates that terminal state **definitions are correct** against real business rules, not that they are covered. Use the UAT Acceptance Script in §9.4 (derived directly from the Decision Table — no separate script creation needed):
+
+- Business stakeholders sign off each row (terminal state)
+- If UAT reveals a previously undefined terminal state: add it to §2.4 + Decision Table + automated test, re-run Gate 3, then resume UAT
+- No new terminal states discovered during UAT = strong signal that §2.4 was thorough
+
+### Gate Model Summary
+
+```
+PRD Sign-off
+    │ Gate 0: §2.4 + §9.4 complete (Decision Points, Terminal States,
+    │         Decision Table, UAT script pre-filled)
+    ▼
+Implementation + PR Reviews
+    │ Gate 1: Each PR covering a flow includes terminal state tests
+    ▼
+Staging / Integration
+    │ (no formal gate — CI green is sufficient)
+    ▼
+Pre-UAT Deployment
+    │ Gate 3: CI proves 100% terminal state coverage + branch coverage ≥ 90%
+    ▼
+UAT Execution
+    │ Gate 4: Business sign-off on terminal state correctness
+    │         New terminal states → back to Gate 3 before proceeding
+    ▼
+Production
+```
+
+---
+
+## RQM Integration
+
+Gate 3 (Pre-UAT CI coverage gate) MUST produce a **`flow_gate_report.json`** artifact consumed by the Release Quality Manifest (`release-quality-manifest.md`, field `flow_gate_report`).
+
+### flow_gate_report.json Schema
+
+```json
+{
+  "generated_at": "2026-05-05T04:00:00Z",
+  "commit": "abc1234",
+  "flows": [
+    {
+      "flow_id": "login-authentication",
+      "spec_ref": "docs/specs/SPEC-001.md#2.4",
+      "decision_points": 3,
+      "terminal_states": 7,
+      "gate_0_complete": true,
+      "gate_1_pr_coverage": true,
+      "gate_3": {
+        "all_scenarios_green": true,
+        "terminal_states_covered": 7,
+        "terminal_states_defined": 7,
+        "branch_coverage_pct": 94,
+        "coverage_target": 90,
+        "all_combinations_required": false,
+        "status": "pass"
+      },
+      "gate_4_uat_signoff": true
+    }
+  ],
+  "summary": {
+    "total_flows": 5,
+    "gate_0_complete": true,
+    "gate_1_pr_coverage": true,
+    "gate_3_ci_pass": true,
+    "gate_4_uat_signoff": true,
+    "status": "pass"
+  }
+}
+```
+
+### Generation Script Hook
+
+Add to CI after test run (Gate 3):
+
+```bash
+# scripts/generate-flow-gate-report.sh
+node scripts/generate-flow-gate-report.mjs \
+  --coverage-report coverage/coverage-summary.json \
+  --flow-specs "docs/specs/**/*.md" \
+  --uat-signoffs ".release-readiness/*.md" \
+  --output flow_gate_report.json
+```
+
+The `summary.status` field feeds into `release-quality-manifest.yaml` under `flow_gate_report.status`.
+
+---
+
 ## Quick Reference Checklist
 
 ```