universal-dev-standards 5.3.2 → 5.5.0

package/bundled/ai/standards/release-quality-manifest.ai.yaml

@@ -0,0 +1,135 @@
+# Release Quality Manifest Standards - AI Optimized
+# Source: core/release-quality-manifest.md
+
+id: release-quality-manifest
+meta:
+  version: "1.0.0"
+  updated: "2026-05-05"
+  source: core/release-quality-manifest.md
+  description: Automated per-release Quality Manifest that aggregates all quality gate results into a single machine-readable artifact
+
+requirements:
+  REQ-1:
+    id: REQ-RQM-001
+    title: Machine-Readable Format
+    rule: >
+      Every release MUST produce a Quality Manifest in YAML or JSON format that
+      aggregates the results of all defined quality gates. The manifest MUST be
+      committed to source control or attached to the release artifact.
+    rationale: >
+      Machine-readable manifests enable automated release gates and customer audits;
+      prose-only release notes cannot be parsed by downstream tooling.
+
+  REQ-2:
+    id: REQ-RQM-002
+    title: Gate Coverage
+    rule: >
+      The Quality Manifest MUST include at minimum: unit test coverage %, mutation
+      score %, SCA CVE counts (critical/high), SAST finding counts (high/medium),
+      E2E pass rate %, container CVE scan status, image signature status, SBOM
+      presence, and (if applicable) LLM hallucination rate and prompt injection
+      resistance score.
+    rationale: >
+      Partial manifests create false confidence; a complete manifest proves end-to-end
+      quality rather than cherry-picked metrics.
+
+  REQ-3:
+    id: REQ-RQM-003
+    title: Pass/Warn/Fail Status per Gate
+    rule: >
+      Each gate entry MUST carry a status field: "pass" (meets target), "warn"
+      (within acceptable deviation from target), or "fail" (blocks release).
+      The manifest MUST have an overall status field derived from the worst gate.
+    rationale: >
+      Binary pass/fail per gate plus an aggregate status enables release go/no-go
+      automation without human judgment on individual metrics.
+
+  REQ-4:
+    id: REQ-RQM-004
+    title: Automated Generation in CI
+    rule: >
+      The Quality Manifest MUST be generated automatically by CI (not manually
+      authored). Each gate's value MUST be extracted from the corresponding tool
+      output (vitest coverage JSON, stryker JSON, trivy SARIF, etc.).
+    rationale: >
+      Manually authored manifests are unreliable; CI-generated manifests are the
+      only form of evidence that meets audit requirements.
+
+  REQ-5:
+    id: REQ-RQM-005
+    title: Customer-Facing Summary
+    rule: >
+      A human-readable summary of the Quality Manifest (e.g., Markdown table)
+      MUST be generated alongside the machine-readable format and included in
+      the release notes or documentation.
+    rationale: >
+      Customers and auditors need a scannable summary; the machine-readable format
+      alone does not satisfy human review requirements.
+
+manifest_schema:
+  release: "string — semver tag e.g. v1.2.0"
+  generated_at: "ISO 8601 timestamp"
+  commit: "git SHA"
+  gates:
+    unit_coverage:
+      actual: "percentage string e.g. '73%'"
+      target: "threshold e.g. '80%'"
+      status: "pass | warn | fail"
+    mutation_score:
+      actual: "percentage string"
+      target: "threshold"
+      status: "pass | warn | fail"
+    sca_critical_cve:
+      actual: "integer"
+      target: "0"
+      status: "pass | fail"
+    sca_high_cve:
+      actual: "integer"
+      target: "0"
+      status: "pass | warn | fail"
+    sast_high:
+      actual: "integer"
+      target: "0"
+      status: "pass | warn | fail"
+    e2e_pass_rate:
+      actual: "percentage string"
+      target: "threshold"
+      status: "pass | warn | fail"
+    container_cve_critical:
+      actual: "integer"
+      target: "0"
+      status: "pass | fail"
+    image_signed:
+      actual: "boolean"
+      target: "true"
+      status: "pass | fail"
+    sbom_present:
+      actual: "boolean"
+      target: "true"
+      status: "pass | fail"
+  overall: "PASS | WARN | FAIL"
+
+generation_guidance: >
+  Extract coverage from vitest --coverage --reporter=json (summary.total.lines.pct).
+  Extract mutation score from stryker's mutation-testing-report.json (metrics.mutationScore).
+  Extract CVE counts from trivy JSON output (Results[].Vulnerabilities filtered by Severity).
+  Extract SAST from CodeQL SARIF (runs[].results filtered by level=error).
+  Combine into manifest YAML via a CI shell script or Node.js release script.
+
+anti_patterns:
+  - description: >
+      Generating the manifest after all gates have passed — gates should use
+      the manifest values, not precede them.
+  - description: >
+      Hardcoding metric values in the manifest generation script — all values
+      MUST be extracted from tool outputs to remain accurate.
+  - description: >
+      Using 'warn' status for critical security gates (sca_critical_cve,
+      container_cve_critical) — critical security gates are binary pass/fail.
+
+related_standards:
+  - testing
+  - security-testing
+  - supply-chain-attestation
+  - verification-evidence
+  - deployment-standards

package/bundled/ai/standards/replay-test.ai.yaml

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: MIT
+name: Replay Test Standards
+nameZh: 回放測試標準
+id: replay-test
+version: "1.0.0"
+category: testing
+scope: ai-agent-systems
+summary: >
+  Golden fixture recording and deterministic replay for AI agent pipelines.
+  Enables customer bug reproduction, verdict regression detection, and
+  on-site incident investigation without requiring a live LLM.
+
+requirements:
+  - id: REQ-01
+    title: Golden Fixture Format
+    titleZh: 黃金 fixture 格式
+    level: MUST
+    description: >
+      Each replay fixture MUST be a JSON file containing: (1) the exact input
+      that triggered the behaviour, (2) the expected output (decision/verdict),
+      (3) metadata (date recorded, source — customer report / CI regression /
+      incident, description). Fixtures MUST be deterministic (same input always
+      produces same output for pure-function components).
+
+  - id: REQ-02
+    title: Replay Test Suite
+    titleZh: 回放測試套件
+    level: MUST
+    description: >
+      A dedicated replay test file MUST load each fixture and assert that
+      re-running the component under test produces the recorded expected output.
+      For AI components with LLM dependencies, replay MUST mock the LLM layer
+      and test only the deterministic logic (scoring, routing, policy evaluation).
+
+  - id: REQ-03
+    title: Bug Regression Capture
+    titleZh: Bug 回歸捕捉
+    level: MUST
+    description: >
+      When a production bug is reported, a fixture MUST be created from the
+      failing input within the same PR that fixes the bug. The fixture prevents
+      the bug from being reintroduced silently.
+
+  - id: REQ-04
+    title: Fixture Coverage
+    titleZh: Fixture 覆蓋
+    level: SHOULD
+    description: >
+      The fixture set SHOULD include at least one representative for each
+      decision outcome (e.g. ALLOW / REQUIRE_HITL / DENY for Guardian).
+      Edge cases reported by customers or from red-team exercises SHOULD be
+      added as separate fixtures.
+
+  - id: REQ-05
+    title: Fixture Naming Convention
+    titleZh: Fixture 命名規範
+    level: MUST
+    description: >
+      Fixture files MUST follow the pattern:
+      `<component>-<outcome>-<short-description>.json`
+      e.g. `guardian-deny-prod-drop-table.json`,
+           `guardian-allow-dev-npm-install.json`
+
+examples:
+  - name: "Guardian replay fixture file"
+    code: |
+      {
+        "meta": {
+          "recorded": "2026-05-05",
+          "source": "red-team-exercise",
+          "description": "DROP TABLE in prod should DENY"
+        },
+        "input": {
+          "session_id": "replay-001",
+          "source_agent": "operator",
+          "intent": "Clean up test data",
+          "plan": [{"command": "DROP TABLE users;", "command_type": "mutate", "target_resource": "db_schema", "reversible": false}],
+          "target_env": "prod",
+          "reversible": false
+        },
+        "expected": {
+          "decision": "DENY"
+        }
+      }
+
+  - name: "Replay test loading fixtures"
+    code: |
+      const fixtures = readdirSync('src/guardian/__fixtures__')
+        .filter(f => f.endsWith('.json'))
+        .map(f => JSON.parse(readFileSync(join('src/guardian/__fixtures__', f), 'utf-8')))
+
+      for (const { meta, input, expected } of fixtures) {
+        it(meta.description, () => {
+          const result = scoreReviewable(input)
+          const decision = deriveDecision(result.score)
+          expect(decision).toBe(expected.decision)
+        })
+      }
+
+anti_patterns:
+  - description: >
+      Fixtures without metadata fields — without source and date, it's
+      impossible to know why a fixture exists or when it was added.
+  - description: >
+      Creating fixtures only for the happy path — the most valuable fixtures
+      are customer-reported failures and red-team findings.
+
+related_standards:
+  - adversarial-test
+  - testing
+  - verification-evidence

package/bundled/ai/standards/runbook.ai.yaml

@@ -0,0 +1,104 @@
+# Runbook Standards - AI Optimized
+# Source: XSPEC-063 Wave 3 SRE Pack
+
+id: runbook
+title: Runbook Writing Standards
+version: "1.0.0"
+status: Active
+tags: [sre, operations, runbook, incident, oncall]
+summary: |
+  Defines how operational runbooks are written, organized, maintained, and
+  tested. Covers required sections, writing principles (reproducible,
+  unambiguous steps), directory structure, review cadence, and drill
+  frequency. A well-written runbook reduces Mean Time To Repair (MTTR) by
+  ensuring any on-call engineer can execute recovery steps without requiring
+  tribal knowledge.
+
+requirements:
+  - id: REQ-001
+    title: Required Runbook Sections
+    description: |
+      Every runbook MUST include the following sections in order:
+      (1) Overview — alert name, severity, affected services, owner, last
+      updated, last drilled date; (2) Symptoms — observable indicators;
+      (3) Impact Assessment — user-facing effect and blast radius;
+      (4) Diagnostic Steps — ordered steps with copy-pasteable commands;
+      (5) Fix Steps — ordered remediation with verification for each step;
+      (6) Escalation — specific contacts with role and availability;
+      (7) Post-Actions — follow-up tasks, tickets, postmortem triggers.
+    level: MUST
+    examples:
+      - "Overview: Alert=HighErrorRate, Severity=P2, Service=payment-api, Owner=@alice"
+      - "Diagnostic: `kubectl get pods -n payments | grep -v Running`"
+      - "Escalation: If not resolved in 30min, page @payment-lead (PD: pd-payments)"
+
+  - id: REQ-002
+    title: Reproducible and Unambiguous Steps
+    description: |
+      Each step in a runbook MUST be reproducible and unambiguous. Steps
+      MUST use copy-pasteable commands with no placeholders left undefined.
+      Decision points MUST include explicit branch conditions (if X then Y,
+      else Z). Every fix step MUST include a verification command confirming
+      the fix worked before proceeding. Expected output MUST be shown.
+    level: MUST
+    examples:
+      - "Bad: 'Restart the service' — Good: `systemctl restart payment-api && systemctl status payment-api`"
+      - "Branch: If error count > 100/min go to step 5a, else go to step 5b"
+      - "Verify: `curl -s https://api/health | jq .status` should return 'ok'"
+
+  - id: REQ-003
+    title: Runbook Naming and Directory Organization
+    description: |
+      Runbooks MUST use kebab-case names that describe the problem, not the
+      solution. Files MUST be organized into typed directories:
+      alerts/ for alert-response runbooks, operations/ for standard ops,
+      emergency/ for major incident procedures, troubleshooting/ for
+      general investigation guides. Each runbook file MUST declare its type
+      in the front matter.
+    level: MUST
+    examples:
+      - "Good: alerts/payment-api-high-error-rate.md"
+      - "Bad: runbooks/restart-payment-service.md"
+      - "Front matter: type: alert_response, alert: HighErrorRateAlert"
+
+  - id: REQ-004
+    title: Review and Drill Cadence
+    description: |
+      Runbooks MUST be reviewed on schedule based on type: alert-response
+      runbooks quarterly, emergency procedures monthly, standard operation
+      and troubleshooting guides bi-annually, change procedures after each
+      use. Runbooks MUST be drilled: P1 runbooks monthly, P2 quarterly,
+      emergency procedures quarterly. Drill records must be appended to the
+      runbook or linked from it.
+    level: MUST
+    examples:
+      - "Drill record: 2026-03-15, participants: @alice @bob, result: pass, MTTR: 12min"
+      - "Quarterly review: updated diagnostic commands after k8s upgrade"
+      - "Post-change update: change-procedure/db-failover.md updated after March 14 drill"
+
+  - id: REQ-005
+    title: Rollback and Fallback Steps
+    description: |
+      Any runbook describing a change or fix MUST include a clearly labeled
+      rollback section describing how to undo the change if the fix fails
+      or causes additional issues. The rollback section MUST appear before
+      the escalation section and include its own verification steps.
+    level: MUST
+    examples:
+      - "Rollback: `helm rollback payment-api 1 && kubectl rollout status deployment/payment-api`"
+      - "Rollback verify: error rate returns below 1% within 3 minutes"
+      - "If rollback fails: escalate immediately, do not attempt further fixes"
+
+  - id: REQ-006
+    title: Alert Integration Metadata
+    description: |
+      Alert-response runbooks SHOULD include a metadata block linking the
+      runbook to specific alert rules. This enables automatic runbook
+      linking in alerting tools (PagerDuty, Alertmanager). Metadata MUST
+      include the alert name, dashboard URL, and Prometheus/logging query
+      used to investigate.
+    level: SHOULD
+    examples:
+      - "alert_name: PaymentAPIHighErrorRate5xx"
+      - "dashboard: https://grafana/d/payment-api-overview"
+      - "query: sum(rate(http_requests_total{status=~'5..'}[5m])) by (service)"

package/bundled/ai/standards/sast-advanced.ai.yaml

@@ -0,0 +1,135 @@
+# Advanced SAST Standards - AI Optimized
+# Source: XSPEC-161 SAST Advanced
+
+id: sast-advanced
+title: Advanced SAST Standards
+version: "1.0.0"
+status: Active
+tags: [sast, codeql, gitleaks, trufflehog, secret-scanning, biome, static-analysis, security, typescript, ci]
+summary: |
+  Defines advanced Static Application Security Testing (SAST) practices
+  beyond basic dependency auditing. Covers three complementary layers:
+  (1) CodeQL semantic analysis for TypeScript/JavaScript — detects injection
+  vulnerabilities, path traversal, prototype pollution, and XSS that npm audit
+  misses; (2) Secret scanning with gitleaks or TruffleHog — prevents committing
+  API keys, tokens, and credentials; (3) Biome-based code quality rules used as
+  a security lint layer for projects that adopt Biome instead of ESLint.
+  Specifies CI enforcement thresholds: block merge on any CRITICAL or HIGH
+  severity finding; 0 High findings is the passing gate.
+
+requirements:
+  - id: REQ-001
+    title: CodeQL Semantic Analysis
+    description: |
+      Projects using TypeScript or JavaScript MUST run CodeQL semantic analysis
+      on every push to the default branch and on every pull request targeting
+      the default branch. Additionally, a weekly scheduled scan MUST be
+      configured to catch newly published query packs. Use the
+      `security-extended` query suite rather than the default suite to include
+      injection, path-traversal, prototype-pollution, and XSS queries.
+      CodeQL MUST be configured with `github/codeql-action/init@v3` with
+      `languages: javascript-typescript` and query filters narrowed to
+      `security-extended`. The `autobuild` action MUST be used unless a
+      custom build command is required. Results MUST be uploaded to GitHub
+      Code Scanning so that SARIF findings appear in the Security tab and
+      block PRs when severity >= HIGH.
+    level: MUST
+    examples:
+      - "Workflow trigger: push to main + pull_request targeting main + schedule weekly"
+      - "init step: uses: github/codeql-action/init@v3 with languages: javascript-typescript"
+      - "query-filters: include tags contain security-extended"
+      - "analyze step uploads SARIF; GitHub blocks PR merge when CRITICAL/HIGH found"
+      - "Weekly cron: '0 2 * * 1' catches newly published CodeQL query packs"
+
+  - id: REQ-002
+    title: Secret Scanning on Every Push and PR
+    description: |
+      A secret scanning step MUST run on every push and pull request to detect
+      accidentally committed API keys, tokens, private keys, and credentials
+      before they reach the repository history. The recommended tool is
+      gitleaks (via `gitleaks/gitleaks-action@v2`). Projects MUST maintain a
+      `.gitleaks.toml` configuration file in the repository root to declare
+      custom patterns for project-specific secret formats and to whitelist
+      documented false positives via allowlist rules. The CI step MUST fail
+      with a non-zero exit code when any secret is detected, blocking merge.
+      Baseline false positives MUST be documented and reviewed quarterly.
+    level: MUST
+    examples:
+      - "CI job: uses gitleaks/gitleaks-action@v2 on push and pull_request events"
+      - ".gitleaks.toml defines custom patterns for project-specific tokens"
+      - "Allowlist rule added with documented justification for known false positive"
+      - "Secret detected → CI fails → developer rotates credential before re-pushing"
+
+  - id: REQ-003
+    title: Biome Security Rules as Lint Gate
+    description: |
+      Projects using Biome as their linter MUST enable the security-relevant
+      linting rules as part of the standard lint pass. Biome's `nursery` and
+      `suspicious` rule groups include patterns such as `noConsoleLog` (prevents
+      accidental secret logging), `noGlobalEval` (prevents dynamic code execution),
+      `noWith` (prevents scope pollution), and `noDebugger` (prevents debug
+      breakpoints in production). The `biome check .` command MUST be run in CI
+      as a blocking step. Projects MUST NOT use `--allow-errors` to bypass
+      security-relevant rule failures. Configuration in `biome.json` MUST set
+      `linter.enabled: true` and include the `recommended: true` ruleset plus
+      any additional security rules appropriate to the project.
+    level: MUST
+    examples:
+      - "biome.json: linter.enabled true, rules.suspicious.noGlobalEval error"
+      - "CI step: `npm run lint` maps to `biome check .`; fails on security rule violations"
+      - "noConsoleLog prevents accidental logging of JWT tokens or API keys"
+      - "noGlobalEval prevents eval() usage that could enable code injection"
+
+  - id: REQ-004
+    title: CI Quality Gate Thresholds
+    description: |
+      SAST findings MUST be classified by severity and the following merge-blocking
+      thresholds MUST be enforced: CRITICAL findings — block merge immediately,
+      no exceptions; HIGH findings — block merge; target is 0 HIGH findings in
+      all open PRs; MEDIUM findings — create tracking issue, do not block merge,
+      resolve within 30 days; LOW/INFORMATIONAL findings — optional resolution,
+      logged for visibility. GitHub Code Scanning branch protection rules MUST
+      be configured to require the CodeQL check to pass before merging.
+      The `sast` CI job MUST be listed as a required status check in branch
+      protection settings.
+    level: MUST
+    examples:
+      - "Branch protection: require CodeQL check + sast job to pass before merge"
+      - "CRITICAL finding in CodeQL → PR blocked; developer must fix or accept risk with CISO sign-off"
+      - "HIGH finding threshold: 0 HIGH open on main branch at all times"
+      - "MEDIUM finding: GitHub issue opened automatically via SARIF annotation; 30-day SLA"
+
+  - id: REQ-005
+    title: What CodeQL Finds That npm audit Misses
+    description: |
+      Teams MUST understand that npm audit only checks published CVEs in
+      dependency manifests (package.json lock file). CodeQL performs semantic
+      data-flow analysis on the actual source code and detects:
+      (1) Command injection — user-controlled data flowing into child_process.exec
+      or child_process.spawn with shell:true; (2) Path traversal — user input
+      used in fs.readFile / fs.writeFile without path.resolve + allowlist check;
+      (3) Prototype pollution — assignment to obj[userKey] = value where userKey
+      is unsanitized; (4) XSS via DOM sinks — user data assigned to innerHTML,
+      document.write, or passed to eval; (5) SQL injection via string concatenation
+      in ORM raw queries. These vulnerabilities exist in first-party code and are
+      invisible to dependency scanners.
+    level: SHOULD
+    examples:
+      - "CodeQL flags: exec(`git log ${userInput}`) as command injection"
+      - "CodeQL flags: fs.readFile(path.join(base, req.params.file)) as path traversal"
+      - "CodeQL flags: target[req.body.key] = req.body.value as prototype pollution"
+      - "npm audit shows 0 vulnerabilities; CodeQL finds path traversal in custom route handler"
+
+anti_patterns:
+  - "Running only npm audit and considering security 'done'"
+  - "Disabling CodeQL on PRs to speed up CI — defeats the purpose of shift-left security"
+  - "Adding entire file paths to gitleaks allowlist without reviewing the actual content"
+  - "Ignoring MEDIUM CodeQL findings indefinitely without tracking issues"
+  - "Using biome check --allow-errors to bypass security lint failures"
+  - "Not uploading SARIF results to GitHub Code Scanning (findings invisible in UI)"
+
+related_standards:
+  - security-standards
+  - secret-management-standards
+  - checkin-standards
+  - container-security

package/bundled/ai/standards/schema-evolution.ai.yaml

@@ -0,0 +1,111 @@
+# Schema Evolution Standards - AI Optimized
+# Source: XSPEC-068 Wave 3 Data Engineering Pack
+
+id: schema-evolution
+title: Schema Evolution Standards
+version: "1.0.0"
+status: Active
+tags: [data-engineering, schema, migration, backward-compatibility, database]
+summary: |
+  Defines how database and data store schemas are evolved safely without
+  breaking existing consumers. Covers backward-compatible change patterns,
+  prohibited breaking changes, expand-contract migration strategy, schema
+  versioning, automated compatibility checking in CI/CD, and rollback
+  procedures for schema changes. Applicable to relational databases,
+  document stores, event schemas (Avro/Protobuf), and API request/response
+  schemas.
+
+requirements:
+  - id: REQ-001
+    title: Backward-Compatible Change Patterns
+    description: |
+      All schema changes MUST be backward-compatible unless a formal
+      breaking-change process is followed. Backward-compatible changes
+      include: adding new nullable columns/fields with defaults, adding
+      new tables/collections, adding new optional message fields, adding
+      new enum values (with unknown handling), widening a data type
+      (INT → BIGINT), and adding new indexes. These changes MUST be
+      deployable without coordinating consumer updates.
+    level: MUST
+    examples:
+      - "Add column: ALTER TABLE users ADD COLUMN middle_name VARCHAR(100) DEFAULT NULL"
+      - "Add optional Protobuf field: optional string nickname = 15; — safe, zero default"
+      - "Add index: CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders(user_id)"
+
+  - id: REQ-002
+    title: Prohibited Breaking Changes Without Migration Plan
+    description: |
+      The following schema changes are classified as BREAKING and MUST NOT
+      be deployed without a formal expand-contract migration plan and
+      consumer coordination: renaming or dropping columns/fields, changing
+      data types incompatibly (VARCHAR → INT, widening to narrowing),
+      adding NOT NULL constraints to existing columns without defaults,
+      changing primary or foreign key definitions, removing enum values,
+      and changing field semantics (repurposing a column for different data).
+    level: MUST
+    examples:
+      - "PROHIBITED: ALTER TABLE users DROP COLUMN legacy_id → requires expand-contract"
+      - "PROHIBITED: ALTER TABLE orders ALTER COLUMN amount TYPE BIGINT — evaluate consumer impact first"
+      - "PROHIBITED: adding NOT NULL to existing column with NULL values in production data"
+
+  - id: REQ-003
+    title: Expand-Contract Migration Strategy
+    description: |
+      Breaking schema changes MUST use the expand-contract (parallel change)
+      pattern: Phase 1 (Expand) — add new structure alongside old; Phase 2
+      (Migrate) — backfill data from old to new, update all writers;
+      Phase 3 (Contract) — update all readers to use new structure;
+      Phase 4 (Cleanup) — remove old structure after all consumers updated.
+      Each phase MUST be a separate deployment, verified before proceeding.
+      Minimum wait between phases: 1 full deployment cycle.
+    level: MUST
+    examples:
+      - "Rename column email → contact_email: add contact_email, dual-write for 1 sprint, migrate readers, drop email"
+      - "Phase gate: 'Phase 2 complete when 0 reads of old column seen in query logs over 7 days'"
+      - "Cleanup verified: `SELECT COUNT(*) FROM users WHERE email IS NOT NULL` returns 0 before dropping"
+
+  - id: REQ-004
+    title: Schema Versioning and Registry
+    description: |
+      Event-driven and API schemas (Avro, Protobuf, JSON Schema) MUST be
+      registered in a schema registry with explicit version numbers.
+      Schema versions MUST follow semantic versioning: PATCH for backward-
+      compatible additions, MINOR for new optional fields, MAJOR for
+      breaking changes. Every schema change MUST be reviewed and approved
+      before registration. Consumers MUST specify the schema version they
+      consume.
+    level: MUST
+    examples:
+      - "Confluent Schema Registry: subject 'order-events-value', version 3 registered"
+      - "Schema compatibility: BACKWARD_TRANSITIVE enforced — new schema must be readable by all prior consumers"
+      - "Consumer declaration: {schema_id: 'order-events', version: '>=2.0.0 <3.0.0'}"
+
+  - id: REQ-005
+    title: Automated Schema Compatibility Checking in CI
+    description: |
+      Every PR modifying schema definitions MUST trigger automated
+      compatibility checks in CI. For relational schemas, migration scripts
+      MUST be run against a production-snapshot database in CI to detect
+      errors before merge. For event schemas, compatibility MUST be checked
+      against all registered consumer versions. Compatibility failures MUST
+      block the PR merge.
+    level: MUST
+    examples:
+      - "CI step: `flyway validate -url=jdbc:postgresql://test-db/snapshots` on every migration PR"
+      - "Avro compatibility: `schema-registry-validate --mode BACKWARD_TRANSITIVE new-schema.avsc`"
+      - "Failed check message: 'Schema change removes required field order_id — breaks consumer v2.3'"
+
+  - id: REQ-006
+    title: Schema Change Rollback Procedures
+    description: |
+      Every schema migration script MUST have a corresponding rollback
+      (down) migration script. Rollback scripts MUST be tested in CI
+      alongside the forward migration. For destructive changes (drops,
+      type changes), a data backup MUST be taken and verified before
+      execution. The rollback plan MUST be documented in the migration
+      PR and referenced in the deployment runbook.
+    level: MUST
+    examples:
+      - "V12__add_user_tier.sql paired with V12__add_user_tier.undo.sql tested in CI"
+      - "Pre-migration backup: `pg_dump orders_table > backup-2026-04-30-pre-v12.dump`"
+      - "Rollback PR comment: 'Rollback: run V12.undo.sql, takes ~2min, no data loss'"