Skip to content

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

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.

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