universal-dev-standards 5.3.2 → 5.5.0

package/bundled/ai/standards/container-security.ai.yaml

@@ -0,0 +1,331 @@
+# Container Security Standard - AI Optimized
+# Source: core/container-security.md
+
+id: container-security
+meta:
+  version: "1.0.0"
+  updated: "2026-05-04"
+  source: core/container-security.md
+  description: >
+    Container and Kubernetes security covering image hardening, registry security,
+    runtime protection, secrets management, network policy, and supply chain
+    integrity for AI Agent production environments.
+
+# ─────────────────────────────────────────────────────────
+# Core Categories
+# ─────────────────────────────────────────────────────────
+categories:
+  - id: image_hardening
+    name: Image Hardening
+    description: Container images must be minimal, non-root, and built with multi-stage patterns
+    base_image:
+      preferred:
+        - distroless (gcr.io/distroless/*)
+        - alpine (< 10 MB)
+      prohibited:
+        - ubuntu/debian as final layer with full package manager
+        - latest tag on base image
+    dockerfile_rules:
+      - rule: Use multi-stage build; only copy artifacts to final stage
+      - rule: Final stage must set non-root USER (UID 1000)
+      - rule: No RUN apt-get / apk add in final layer (use builder stage only)
+      - rule: Only COPY specific files; never COPY . . in final stage
+      - rule: Pin base image by digest, not tag
+    security_context_k8s:
+      required:
+        - runAsNonRoot: true
+        - runAsUser: 1000
+        - allowPrivilegeEscalation: false
+        - readOnlyRootFilesystem: true
+      seccomp:
+        profile: RuntimeDefault
+      capabilities:
+        drop: [ALL]
+        add: explicit allowlist only (e.g., NET_BIND_SERVICE if needed)
+    ai_agent_specific:
+      - rule: AI Agent container must run as UID 1000 (non-root)
+      - rule: LLM call process must not have CAP_NET_RAW or CAP_SYS_ADMIN
+    iso_mapping:
+      - "ISO/IEC 27001:2022 A.8.9 Configuration Management"
+      - "NIST SP 800-190 §4.1 Image Vulnerabilities"
+      - "CIS Docker Benchmark v1.6 §4 Container Images"
+
+  - id: registry_security
+    name: Registry Security
+    description: All container images must be stored in private registries with signing and vulnerability scanning
+    registry:
+      type: private (GHCR, ECR, GCR, Harbor)
+      public_registry: prohibited for production images
+    tagging:
+      immutable_tag: required (semver or git SHA)
+      latest_tag: prohibited in production deployments
+      pinned_digest: required for supply chain integrity
+    signing:
+      tools: [Cosign, Notary v2]
+      policy: All production images must be signed before push
+      verification: Admission controller (Kyverno/Gatekeeper) verifies signature on deploy
+    vulnerability_scan:
+      tool: Trivy
+      gate:
+        critical: 0 (block push if any critical CVE)
+        high: 0 (block push if any high CVE)
+      frequency: On every build + weekly re-scan of deployed images
+      editions:
+        trial: Trivy gate mandatory
+        community: Trivy gate mandatory
+        commercial: Trivy gate mandatory
+    ai_agent_specific:
+      - rule: Guardian OPA Sidecar image must also pass Trivy gate
+      - rule: Trial/Community edition images enforce Trivy gate to avoid supply chain compromise
+    iso_mapping:
+      - "ISO/IEC 27001:2022 A.8.8 Management of Technical Vulnerabilities"
+      - "NIST SP 800-190 §4.2 Image Configuration Defects"
+      - "CIS Docker Benchmark v1.6 §2 Docker daemon configuration"
+
+  - id: runtime_security
+    name: Runtime Security
+    description: Running containers must have minimal capabilities and access; privileged mode is prohibited
+    prohibitions:
+      - privileged: true in securityContext
+      - hostNetwork: true (unless explicitly required and documented)
+      - hostPID: true
+      - hostIPC: true
+    required_settings:
+      - readOnlyRootFilesystem: true
+      - allowPrivilegeEscalation: false
+      - drop: [ALL] capabilities
+    seccomp:
+      profile: RuntimeDefault (or custom restricted profile)
+      audit_mode: allowed for profiling only; not for production
+    apparmor_selinux:
+      apparmor: docker-default (Kubernetes annotation)
+      selinux: enforcing mode on RHEL/CentOS hosts
+    writable_volumes:
+      pattern: Mount named volumes or PersistentVolumeClaims for writable data
+      tmpfs: allowed for /tmp when truly ephemeral
+    ai_agent_specific:
+      - rule: Audit log volume must be readOnly:false but backed by append-only partition
+      - rule: Agent working directory may use emptyDir; audit log must not
+    iso_mapping:
+      - "ISO/IEC 27001:2022 A.8.9 Configuration Management"
+      - "NIST SP 800-190 §4.3 Container Runtime Vulnerabilities"
+      - "CIS Docker Benchmark v1.6 §5 Container Runtime"
+
+  - id: secrets_management
+    name: Secrets Management
+    description: Secrets must never be embedded in images or passed via environment variables from plain text
+    prohibited:
+      - Hardcoded secrets in Dockerfile (ENV SECRET=...)
+      - Secrets in docker-compose.yml env: section as plain text
+      - ConfigMap storing sensitive values in K8s
+      - Git-tracked .env files containing real credentials
+    allowed:
+      staging:
+        - K8s Secrets (base64) + RBAC restriction
+        - Sealed Secrets (Bitnami) for GitOps
+      production:
+        - HashiCorp Vault (dynamic secrets)
+        - AWS Secrets Manager / GCP Secret Manager
+        - Azure Key Vault
+    injection_patterns:
+      - pattern: Mounted volume (/run/secrets/)
+        preferred: true
+      - pattern: Init container fetches secret and writes to shared emptyDir
+        acceptable: true
+      - pattern: Environment variable from K8s Secret reference
+        acceptable: true (better than plain text, but volume preferred)
+    ai_agent_specific:
+      - rule: LLM API keys must be injected via mounted secret volume, not ENV
+      - rule: Guardian OPA policy files are not secrets; use ConfigMap
+    iso_mapping:
+      - "ISO/IEC 27001:2022 A.8.12 Data Leakage Prevention"
+      - "ISO/IEC 27001:2022 A.8.24 Use of Cryptography"
+      - "NIST SP 800-190 §4.4 Container Image and Registry Vulnerabilities"
+
+  - id: network_policy
+    name: Network Policy
+    description: K8s NetworkPolicy must default-deny; only necessary ingress/egress is permitted
+    default_policy:
+      ingress: deny-all (explicit allow per service)
+      egress: deny-all (explicit allow per service)
+    required_allow:
+      dns: "kube-dns (UDP/TCP 53) must be allowed for all pods"
+      health_checks: "kubelet health check endpoints"
+    ai_agent_outbound_allowlist:
+      - host: api.anthropic.com
+        port: 443
+        protocol: HTTPS
+      - host: api.openai.com
+        port: 443
+        protocol: HTTPS
+      - host: "bedrock.*.amazonaws.com"
+        port: 443
+        protocol: HTTPS
+      - host: registry.npmjs.org
+        port: 443
+        protocol: HTTPS
+        note: Only during build phase; not at runtime
+    guardian_sidecar:
+      placement:
+        - same Pod as AI Agent (sidecar container)
+        - same K8s namespace minimum
+      communication: localhost (sidecar) or ClusterIP service (same namespace)
+    tools:
+      policy_enforcement: [Calico, Cilium, Kubernetes NetworkPolicy]
+      validation: [kubectl describe networkpolicy, Kyverno policy report]
+    ai_agent_specific:
+      - rule: AI Agent pod egress must be restricted to outbound allowlist
+      - rule: Guardian OPA Sidecar must be same Pod or same namespace
+      - rule: Any new LLM provider endpoint must be added to allowlist and reviewed
+    iso_mapping:
+      - "ISO/IEC 27001:2022 A.8.20 Networks Security"
+      - "ISO/IEC 27001:2022 A.8.22 Web Filtering"
+      - "CIS Kubernetes Benchmark v1.8 §5.3 Network Policies and CNI"
+
+  - id: supply_chain
+    name: Supply Chain Security
+    description: Container build process must be reproducible, auditable, and signed
+    sbom:
+      formats: [CycloneDX, SPDX]
+      generation:
+        tool: Syft or trivy sbom
+        trigger: Every image build
+        storage: Attached to registry as OCI artifact
+    image_pinning:
+      rule: All FROM directives must use digest (sha256:...), not floating tag
+      example: "FROM gcr.io/distroless/static-debian12@sha256:<digest>"
+    signing:
+      tool: Sigstore (keyless signing via GitHub Actions OIDC)
+      verification: Cosign verify --certificate-identity-regexp
+    reproducible_build:
+      - Set SOURCE_DATE_EPOCH for deterministic timestamps
+      - Use --no-cache in CI; never rely on layer cache across builds
+    lockfile_verification:
+      nodejs:
+        file: package-lock.json or yarn.lock
+        command: "npm ci (not npm install)"
+      python:
+        file: requirements.txt with pinned versions or Pipfile.lock
+        command: "pip install --require-hashes -r requirements.txt"
+      golang:
+        file: go.sum
+        command: "go mod verify"
+    ai_agent_specific:
+      - rule: SBOM must be generated for every AI Agent image release
+      - rule: Third-party AI SDK (anthropic, openai) versions must be pinned in lockfile
+    iso_mapping:
+      - "ISO/IEC 27001:2022 A.8.8 Management of Technical Vulnerabilities"
+      - "NIST SP 800-190 §4.5 Host OS Vulnerabilities"
+      - "SLSA Framework Level 2+ (provenance attestation)"
+
+# ─────────────────────────────────────────────────────────
+# Quality Gates
+# ─────────────────────────────────────────────────────────
+quality_gates:
+  pre_build:
+    - base_image_pinned_by_digest: required
+    - multi_stage_build: required
+    - no_secrets_in_dockerfile: required
+  pre_push:
+    - trivy_critical_count: 0
+    - trivy_high_count: 0
+    - image_signed: required (cosign or notary)
+    - sbom_generated: required
+  pre_deploy:
+    - image_tag_immutable: required (no 'latest')
+    - k8s_security_context:
+        runAsNonRoot: true
+        readOnlyRootFilesystem: true
+        allowPrivilegeEscalation: false
+    - network_policy_applied: required
+    - secrets_from_vault_or_k8s_secret: required
+  ai_agent_specific:
+    - agent_uid: 1000
+    - guardian_sidecar: same_pod_or_namespace
+    - outbound_allowlist: configured
+    - audit_log_volume: append_only_partition
+
+# ─────────────────────────────────────────────────────────
+# Rules
+# ─────────────────────────────────────────────────────────
+rules:
+  - id: non-root-container
+    trigger: writing any Dockerfile or K8s Pod spec
+    instruction: >
+      Set USER 1000 in Dockerfile final stage.
+      Set runAsNonRoot: true and runAsUser: 1000 in securityContext.
+      Verify: docker inspect --format='{{.Config.User}}' <image>
+    priority: required
+
+  - id: no-latest-tag
+    trigger: tagging or pulling container images
+    instruction: >
+      Never use 'latest' tag in production. Use semver (v1.2.3) or git SHA.
+      For base images, pin by digest: FROM image@sha256:<digest>
+    priority: required
+
+  - id: trivy-gate-before-push
+    trigger: building container image for any environment
+    instruction: >
+      Run: trivy image --exit-code 1 --severity CRITICAL,HIGH <image>
+      Block push if exit code is non-zero. Fix all critical/high CVEs first.
+    priority: required
+
+  - id: drop-all-capabilities
+    trigger: writing K8s Pod or Deployment spec
+    instruction: >
+      Set capabilities.drop: [ALL] in securityContext.
+      Only add specific capabilities if explicitly required (document justification).
+    priority: required
+
+  - id: default-deny-network-policy
+    trigger: deploying any service to Kubernetes
+    instruction: >
+      Apply default-deny NetworkPolicy to namespace before deploying services.
+      Then add explicit allow policies per service communication requirement.
+    priority: required
+
+  - id: no-env-secrets
+    trigger: any Dockerfile ENV or K8s env[] with sensitive values
+    instruction: >
+      Never pass secrets via ENV. Use K8s Secret + volume mount or Vault agent injector.
+      Check: grep -r "ENV.*KEY\|ENV.*SECRET\|ENV.*TOKEN" Dockerfile
+    priority: required
+
+  - id: sign-and-sbom
+    trigger: releasing container image to production
+    instruction: >
+      Generate SBOM: syft <image> -o cyclonedx-json > sbom.json
+      Sign image: cosign sign <image>@<digest>
+      Attach SBOM: cosign attach sbom --sbom sbom.json <image>@<digest>
+    priority: required
+
+anti_patterns:
+  - FROM ubuntu:latest (floating tag, large attack surface)
+  - RUN apt-get update && apt-get install in final Dockerfile stage
+  - Running container as root (USER root or no USER directive)
+  - ENV API_KEY=<real_key> in Dockerfile
+  - privileged: true in K8s securityContext
+  - No NetworkPolicy (allow all egress by default)
+  - Skipping Trivy scan on "quick" builds
+  - Using 'latest' image tag in Kubernetes Deployment
+  - SBOM not generated for production releases
+
+quick_reference:
+  container_security_checklist: |
+    □ Base image pinned by digest (not tag)
+    □ Multi-stage build; only COPY artifacts to final stage
+    □ Final stage: USER 1000 (non-root)
+    □ securityContext: runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation:false
+    □ capabilities.drop: [ALL]
+    □ seccompProfile: RuntimeDefault
+    □ Trivy scan: 0 critical, 0 high before push
+    □ Image signed (Cosign / Notary v2)
+    □ SBOM generated (CycloneDX or SPDX)
+    □ No secrets in Dockerfile ENV or image layers
+    □ K8s Secrets or Vault for secret injection
+    □ NetworkPolicy: default-deny + explicit allow
+    □ AI Agent egress: allowlist (Anthropic, OpenAI, Bedrock)
+    □ Guardian OPA Sidecar: same Pod or same namespace
+    □ Audit log volume: append-only partition (not emptyDir)
+    □ Lockfile pinned (npm ci / pip --require-hashes / go mod verify)

package/bundled/ai/standards/cost-budget-test.ai.yaml

@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: MIT
+name: Cost Budget Test Standards
+nameZh: 成本預算測試標準
+id: cost-budget-test
+version: "1.0.0"
+category: testing
+scope: ai-agent-systems
+summary: >
+  Unit and integration tests that verify token budget zone classification,
+  pipeline cost thresholds, and runaway-loop prevention for AI agent systems.
+
+requirements:
+  - id: REQ-01
+    title: Zone Classification Boundary Tests
+    titleZh: 區間分類邊界測試
+    level: MUST
+    description: >
+      The token budget zone classifier MUST have unit tests covering all four
+      zones (safe/warning/danger/blocking) and every boundary value (the exact
+      threshold values, one below, and one above). This ensures that threshold
+      drift is caught by the test suite.
+    implementation: |
+      // Test all boundaries:
+      classifyTokenZone(0.84) → "safe"
+      classifyTokenZone(0.85) → "warning"   // WARNING_THRESHOLD
+      classifyTokenZone(0.89) → "warning"
+      classifyTokenZone(0.90) → "danger"    // DANGER_THRESHOLD
+      classifyTokenZone(0.94) → "danger"
+      classifyTokenZone(0.95) → "blocking"  // BLOCKING_THRESHOLD
+      classifyTokenZone(1.00) → "blocking"
+
+  - id: REQ-02
+    title: Pipeline Budget Config Validation Tests
+    titleZh: Pipeline 預算設定驗證測試
+    level: MUST
+    description: >
+      Tests MUST verify that PipelineBudgetConfig properties (maxCostPerRun,
+      maxCostPerDay, warningThreshold, autoDowngrade) have correct semantics.
+      At minimum: verify that exceeding maxCostPerRun triggers the expected
+      budget-exceeded behaviour.
+
+  - id: REQ-03
+    title: Overflow and Runaway Detection
+    titleZh: 溢位與失控偵測測試
+    level: MUST
+    description: >
+      Tests MUST include edge cases for budget overflow: usageRatio > 1.0
+      (over-budget), exactly 0.0 (no tokens used), and NaN/Infinity to verify
+      that the classifier does not silently return an unexpected zone.
+
+  - id: REQ-04
+    title: Cost Threshold Gate Integration Test
+    titleZh: 成本閾值閘門整合測試
+    level: SHOULD
+    description: >
+      Where a cost gate (e.g. CostTracker.isOverBudget) exists, integration
+      tests SHOULD verify that the gate blocks further LLM calls when the
+      daily cost limit is exceeded.
+
+  - id: REQ-05
+    title: Coverage of All Budget Constants
+    titleZh: 全預算常數覆蓋
+    level: MUST
+    description: >
+      All numeric constants in the budget configuration MUST appear in at least
+      one test. Constants that appear only in production code but never in tests
+      are a mutation survival risk.
+
+examples:
+  - name: "Zone boundary tests in Vitest"
+    code: |
+      import { classifyTokenZone, TOKEN_BUDGET } from "../types/index.js"
+
+      it.each([
+        [0.0,   "safe"],
+        [0.84,  "safe"],
+        [TOKEN_BUDGET.WARNING_THRESHOLD,  "warning"],
+        [TOKEN_BUDGET.DANGER_THRESHOLD,   "danger"],
+        [TOKEN_BUDGET.BLOCKING_THRESHOLD, "blocking"],
+        [1.0,   "blocking"],
+      ])("classifyTokenZone(%f) → %s", (ratio, expected) => {
+        expect(classifyTokenZone(ratio)).toBe(expected)
+      })
+
+anti_patterns:
+  - description: >
+      Testing only happy-path ratios like 0.5 or 0.75 — boundary values
+      (WARNING/DANGER/BLOCKING thresholds) are where off-by-one errors hide.
+  - description: >
+      Using magic numbers instead of TOKEN_BUDGET.* constants in tests —
+      if the constant changes, the test should fail, not silently pass.
+
+related_standards:
+  - testing
+  - mutation-testing
+  - llm-output-validation

package/bundled/ai/standards/data-contract.ai.yaml

@@ -0,0 +1,110 @@
+# Data Contract Standards - AI Optimized
+# Source: XSPEC-068 Wave 3 Data Engineering Pack
+
+id: data-contract
+title: Data Contract Standards
+version: "1.0.0"
+status: Active
+tags: [data-engineering, data-contract, data-quality, api, interoperability]
+summary: |
+  Defines how data contracts are established, versioned, and enforced between
+  data producers and consumers. A data contract is a formal agreement
+  specifying the schema, quality guarantees, SLAs, and ownership of a dataset
+  or data stream. Covers contract specification format, freshness and quality
+  SLOs, breaking-change governance, consumer notification, and automated
+  contract testing. Reduces data pipeline failures caused by undiscovered
+  upstream changes.
+
+requirements:
+  - id: REQ-001
+    title: Data Contract Specification Format
+    description: |
+      Every shared dataset or data stream MUST have a data contract specified
+      in a machine-readable YAML file (data-contract.yaml) committed to
+      version control alongside the producer code. The contract MUST include:
+      contract_id, version, owner (team + contact), description, schema
+      (field names, types, nullability), data_quality SLOs (completeness,
+      freshness, uniqueness), SLA (delivery time), and consumer list.
+    level: MUST
+    examples:
+      - "File: datasets/orders/data-contract.yaml committed in producer repo"
+      - "Required fields: contract_id, version, owner.team, owner.email, schema, sla.freshness_minutes"
+      - "Schema entry: {field: order_amount, type: DECIMAL(12,2), nullable: false, description: 'Order total in USD'}"
+
+  - id: REQ-002
+    title: Data Quality SLOs
+    description: |
+      Every data contract MUST define explicit data quality SLOs for the
+      dataset. Required quality dimensions: completeness (% of non-null
+      values for required fields ≥ threshold), freshness (data updated
+      within N minutes/hours of source event), uniqueness (% of distinct
+      values for key fields), and validity (% of values conforming to
+      defined format/range). Quality SLO violations MUST trigger alerts
+      to both producer and registered consumers.
+    level: MUST
+    examples:
+      - "completeness_slo: {field: order_id, min_pct_non_null: 99.99}"
+      - "freshness_slo: {max_lag_minutes: 15, alert_on_breach: true}"
+      - "uniqueness_slo: {field: order_id, min_pct_unique: 100.0}"
+
+  - id: REQ-003
+    title: Contract Versioning and Breaking-Change Governance
+    description: |
+      Data contracts MUST be versioned using semantic versioning. PATCH
+      version changes (backward-compatible additions, documentation updates)
+      require only producer team approval. MINOR version changes (new
+      optional fields, relaxed constraints) require notification to consumers
+      with 7-day notice. MAJOR version changes (field removal, type changes,
+      semantic changes) require consumer approval and MUST NOT be deployed
+      without all registered consumers confirming readiness.
+    level: MUST
+    examples:
+      - "v1.0.0 → v1.1.0: added optional field shipping_method, consumers notified via email 7 days prior"
+      - "v1.1.0 → v2.0.0: dropped legacy_order_id field, consumer sign-off required in tracking issue"
+      - "Breaking change gate: CI blocks deployment until all consumers in data-contract.yaml have approved"
+
+  - id: REQ-004
+    title: Automated Contract Testing
+    description: |
+      Data contract compliance MUST be verified automatically. Producers
+      MUST run contract tests on every data pipeline execution, validating
+      output against the declared schema and quality SLOs. Tests MUST
+      check: schema conformance (no unexpected nulls, correct types),
+      freshness within SLO window, uniqueness of key fields, and row count
+      within expected range. Contract test failures MUST halt the pipeline
+      and page the data owner.
+    level: MUST
+    examples:
+      - "Contract test: `great_expectations checkpoint run orders-contract-checkpoint`"
+      - "Test assertion: expect_column_values_to_not_be_null('order_id', mostly=0.9999)"
+      - "Pipeline halt: contract test failure triggers SNS alert to #data-oncall, job aborted"
+
+  - id: REQ-005
+    title: Consumer Registration and Notification
+    description: |
+      Teams consuming a shared dataset MUST register as consumers in the
+      producer's data-contract.yaml file. Registration must include: consumer
+      team name, contact email/Slack, use case description, and fields
+      consumed. Registered consumers MUST receive automated notifications
+      when: the contract is modified, quality SLO breaches occur, the
+      dataset is deprecated, or planned maintenance will affect availability.
+    level: MUST
+    examples:
+      - "consumers entry: {team: analytics, contact: '#data-analytics', use_case: 'revenue reporting', fields: [order_id, amount, created_at]}"
+      - "Automated Slack notification: 'Data contract orders/v1 SLO breached: freshness 42min (SLO: 15min)'"
+      - "Deprecation notice sent 90 days before v1 end-of-life to all registered consumers"
+
+  - id: REQ-006
+    title: Contract Discoverability
+    description: |
+      All data contracts in an organization SHOULD be discoverable through
+      a central data catalog. The catalog SHOULD provide: searchable index
+      of all contracts by team/domain, current health status (quality SLO
+      compliance), schema browsing, lineage visualization (which pipelines
+      produce/consume each dataset), and a self-service consumer registration
+      workflow.
+    level: SHOULD
+    examples:
+      - "Data catalog: DataHub or Amundsen with all contract YAML files indexed"
+      - "Catalog entry includes: SLO compliance badge (green/yellow/red), last updated, consumer count"
+      - "Self-service: 'Subscribe to dataset' button generates PR adding consumer to data-contract.yaml"

package/bundled/ai/standards/data-migration-testing.ai.yaml

@@ -0,0 +1,96 @@
+# Data Migration Testing Standards - AI Optimized
+# Source: core/data-migration-testing.md
+
+id: data-migration-testing
+meta:
+  version: "1.0.0"
+  updated: "2026-05-05"
+  source: core/data-migration-testing.md
+  description: Database migration up/down/idempotency testing standards for schema changes
+
+requirements:
+  REQ-1:
+    id: REQ-DMT-001
+    title: Up Migration Test
+    rule: >
+      Every schema migration MUST have an automated test that applies it to a clean
+      baseline schema and verifies the expected post-state (table names, columns,
+      indexes, constraints).
+    rationale: >
+      Unverified migrations silently corrupt production schema; up tests catch
+      incompatible changes before deployment.
+
+  REQ-2:
+    id: REQ-DMT-002
+    title: Down Migration (Rollback) Test
+    rule: >
+      Every migration that has a down/rollback function MUST have a test that
+      applies up, then down, and verifies the schema returns to its exact pre-state.
+      Zero data loss is the acceptance criterion.
+    rationale: >
+      Rollback is only reliable if it is tested; untested rollbacks fail at the worst
+      possible moment — during a production incident.
+
+  REQ-3:
+    id: REQ-DMT-003
+    title: Idempotency Test
+    rule: >
+      Migration runners MUST be tested to ensure applying the same migration twice
+      does not fail or cause side effects (e.g., duplicate columns, duplicate indexes).
+    rationale: >
+      CI retries and operator mistakes can trigger double-apply; idempotent migrations
+      prevent partial state corruption.
+
+  REQ-4:
+    id: REQ-DMT-004
+    title: Data Preservation Test
+    rule: >
+      Migrations that ALTER or DROP columns MUST include a test that seeds representative
+      data before the migration and verifies data integrity or expected transformation
+      after the migration.
+    rationale: >
+      Schema correctness does not imply data correctness; a column rename can silently
+      null-out existing data if the migration omits a data transform step.
+
+  REQ-5:
+    id: REQ-DMT-005
+    title: Migration History Integrity
+    rule: >
+      The migration runner's applied-migrations table/ledger MUST be validated:
+      each test run uses an isolated in-memory or temporary database so migrations
+      do not interfere with each other or with production state.
+    rationale: >
+      Shared migration state between tests causes non-deterministic failures that are
+      extremely difficult to diagnose.
+
+test_structure:
+  isolation: "Each migration test MUST run against an isolated in-memory or temp DB"
+  baseline: "Start from the schema state immediately before the migration under test"
+  assertions:
+    up: "Assert table/column/index existence and types"
+    down: "Assert schema returns to pre-migration state"
+    idempotency: "Apply migration twice; second apply must succeed without error"
+    data: "Seed rows before migration; assert row count and values after"
+
+tooling_guidance:
+  sqlite: "Use ':memory:' DSN; apply migrations via ORM migrate() or raw SQL"
+  postgres: "Use pgmock or test containers; run migrate up/down in a transaction"
+  drizzle_orm: >
+    Call db.run(sql`...`) with raw DDL, or use drizzle-kit's migrate() function
+    against a fresh :memory: SQLite database for each test file.
+
+anti_patterns:
+  - description: >
+      Testing migrations against a shared development database — causes cross-test
+      pollution and non-repeatable results.
+  - description: >
+      Skipping down migration tests because "we never rollback" — rollbacks happen
+      during incidents; the worst time to discover they are broken.
+  - description: >
+      Writing migration tests after the fact without seeding data — misses the
+      data preservation class of bugs entirely.
+
+related_standards:
+  - testing
+  - database-standards
+  - verification-evidence