# CI Enforcement Checklist

Use this as the mandatory pipeline baseline for public-facing releases.

## 0. Execution Tiers (Automatic Determinant)

Use three execution tiers so the pipeline cost matches the risk of the change. Tier
selection must be automatic; do not depend on a developer remembering which jobs to run.

- `fast`
  - default on normal pushes
  - runs compile/unit/contract/codegen/security baseline gates
  - should complete quickly and catch obvious drift
- `medium`
  - triggered automatically for workflow-sensitive change sets such as:
    - `packages/web/**`
    - `doc/operations/local-dev/**`
    - auth/session/browser/runtime-path scripts
  - adds browser and local-dev parity validation where relevant
- `heavy`
  - triggered by schedule or explicit deploy intent
  - includes image publish, deploy, remote validation, and rollback-capable checks

Automatic selectors should be based on:
- `rules:changes` for file-scope risk
- branch and pipeline source (`push`, `merge_request`, `schedule`)
- explicit manual deploy jobs for environment-changing actions

Do not require an operator to remember whether a change is "fast", "medium", or
"heavy". The CI configuration must encode that decision.

## 1. Contract Gates
- Validate OpenAPI (`doc/api/openapi.draft.yaml`) syntax.
- Validate AsyncAPI (`doc/api/asyncapi.draft.yaml`) syntax.
- Run Spectral lint using `doc/governance/openapi.spectral.yaml` for OpenAPI.
- Run contract invariant checks from `doc/governance/Contract_Invariant_Gates.md`.
- Apply machine-readable enforcement controls from `doc/governance/production_enforcement_policy.yaml`.
- Run breaking-change diff check against previous released API contracts.
- Fail build if specs and implementation drift.

## 2. SDK/CLI Gates
- Generate SDK from current OpenAPI.
- Run SDK compile/import smoke tests.
- Regenerate generated client artifacts and run CLI command smoke tests.
- Build Python SDK sdist/wheel successfully when `packages/python-sdk/**` changes.
- Run CLI introspection smoke for:
  - `schema`
  - `explain --output json`
  - `mcp list-tools`

Task/review requirement: any task that changes `doc/api/**`, SDK/client-facing
OpenAPI descriptions, AsyncAPI payloads, or codegen scripts must attach evidence
from:

```bash
CODEGEN_ENFORCE_CLEAN=1 bash scripts/ci/sdk_codegen_smoke.sh
```

This requirement applies to description-only contract changes because generated
TypeScript artifacts include endpoint descriptions.

## 3. Security Gates
- SAST scan.
- Dependency vulnerability scan.
- Secrets scan in repo and artifacts.
- Container image scan (if containerized).
- IaC policy scan for deployment manifests.
- Production promotion gate over SAST, dependency/SCA, secrets, image/container,
  DAST, and hardening summaries. Critical/high-class findings, unavailable
  scanners, or missing summaries fail unless `doc/governance/security_scan_exceptions.json`
  contains an approved, expiring exception with owner, impact, compensating
  control, and approver.
- Pre-prod image and DAST release jobs run in fail-closed scan mode for skipped
  or unavailable scanners. DAST blocking requires documented target, auth, rate
  limit, and rollback evidence before scanning live pre-prod endpoints.
- Waiver governance follows `doc/governance/Security_Waiver_Governance_v1.md`;
  waived or deferred controls must stay visible in release evidence and expired
  critical/high waivers block production-style promotion.

## 4. Reliability and Quality Gates
- Unit tests.
- Integration tests for critical flows:
  - auth
  - provision/release
  - billing debit cycle
  - Stripe webhook idempotency
- Contract tests between frontend and API.
- Hardcoded runtime-policy constant scan (allow test/fixture paths only).

## 5. Schema and Data Integrity Gates
- Schema initialization validation: apply `doc/architecture/db_schema_v1.sql` to an ephemeral DB and verify it completes without errors.
- Incremental schema validation: apply the previous committed `doc/architecture/db_schema_v1.sql` to an ephemeral DB, then apply the current schema on top and verify the forward-only update completes without errors.
- No legacy data migration required — this is a greenfield launch. See `doc/architecture/Schema_Migration_Plan.md`.
- Post-launch schema evolution (additive-only, forward-only) is governed by the Schema Migration Plan.
- Ledger integrity test suite.

## 6. Observability Gates
- Enforce structured logging fields (`timestamp`, `level`, `service`, `correlation_id`).
- Ensure tracing is enabled for API + workers.
- Ensure critical metrics are emitted for provisioning/billing/payments.

## 7. Release Governance Gates
- Changelog entry required.
- ADR reference required for architecture-impacting changes.
- Backward compatibility statement required in PR template.
- Manual approval required for breaking API changes.

## 8. UX and Design Baseline Gates
- Enforce pre-coding readiness checks from `doc/governance/Design_Baseline_Gate.md`.
- Block feature PRs that add/modify UI flows without:
  - matching contract updates (`openapi.draft.yaml` / `asyncapi.draft.yaml`)
  - corresponding `doc/product/ux-mocks/*` updates
  - state matrix coverage (`loading`, `empty`, `error`, `success`, `restricted`, `rate_limited`)

## 9. Suggested Pipeline Order
1. Lint + format checks
2. OpenAPI/AsyncAPI validation + OpenAPI spectral lint
3. Multi-agent queue validation (`doc/governance/Agent_Work_Queue.yaml`)
4. Build + unit tests
5. Integration + contract tests
6. Security scans
7. SDK/CLI generation smoke
8. Schema initialization validation
9. Packaging + attestations
10. Security promotion gate

## 10. Runner Capacity Baseline

Runner capacity decisions are governed by
`doc/operations/CI_Runner_Capacity_Baseline_v1.md`.

Do not add or retag GitLab runners based only on anecdotal pipeline delay. A
capacity change needs queue-time evidence, runtime evidence, runner inventory or
equivalent ops export, host headroom, rollback steps, and post-change metrics.