> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reflections.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-0012: CI/CD quality and release gates

> Keep release quality high through automated, ordered validation gates.

<Info>**Status:** Accepted **Date:** 2026-02-06 **Deciders:** Reflections Maintainers</Info>

## Context

This repository combines application logic, database migrations, and deployment automation. Regressions can arise from type drift, formatting/lint drift, schema drift, or startup/deployment misconfiguration.

## Decision

Use layered CI/CD gates:

* **PR quality gate:** format check, lint, architecture guard, design guard, typecheck, tests, build.
* **Release migration gate:** merge-to-main triggers reusable Supabase migration workflow before the release gate can pass.
* **Database gate:** migration SQL lint (enforced at commit time via lint-staged), local reset + lint + migration contracts.
* **Deployment health gate:** Railway startup smoke checks and deployed synthetic checks; Railway must wait for the release gate.
* **Migration workflow gate:** explicit Supabase dry-run before applying linked migrations, with guarded manual break-glass dispatch.
* **Security gate:** CodeQL static analysis and AI security review on non-draft PRs.
* **Dependency audit:** `pnpm audit --audit-level=high` in CI.

## Alternatives considered

### Alternative 1: Minimal CI (lint + test only)

Pros:

* Faster CI runtime.

Cons:

* Misses schema/migration drift and build-time issues.
* Increased risk of broken deployments.

### Alternative 2: Manual release checklist only

Pros:

* Flexible human control.

Cons:

* Inconsistent and error-prone.
* Poor scalability as repository grows.

### Alternative 3: Single monolithic CI gate without DB/deployment checks

Pros:

* Simpler pipeline definition.

Cons:

* Fails to catch environment-specific migration/deployment regressions.

## Consequences

**Benefits:**

* Higher confidence in merged/deployed changes.
* Early detection of migration drift and runtime startup failures.
* Repeatable release discipline.

**Costs:**

* Longer CI time.
* Ongoing maintenance of workflow scripts and synthetic checks.

## Implementation notes

* PR validation executes format check, lint, architecture guard, design guard, typecheck, tests, and build in sequence.
* The release workflow includes a policy check that blocks releases for commits not associated with a merged pull request.
* The migration deployment workflow supports both automated and guarded manual dispatch with a production confirmation gate.
* Architecture guard validates boundary and complexity constraints. Design guard enforces visual invariants (hex colors, inline style semantics, meta-label consistency, transition timing, WebGL budget). Both run as fast-fail structural gates (\~1.3s combined).

## Related ADRs

* [ADR-0002: Runtime and build standards](/decisions/adr-0002)
* [ADR-0010: Ingestion orchestration, idempotency, and recovery](/decisions/adr-0010)
* [ADR-0013: Migration governance and drift control](/decisions/adr-0013)
* [ADR-0022: Lint policy and enforcement layer strategy](/decisions/adr-0022)