Skip to main content

Definition of Done

Every PR must satisfy every applicable box before merge. PR template enforces this checklist.

Universal (every PR)​

  • Code reviewed and approved by at least one other engineer.
  • Conventional commit messages (feat, fix, refactor, docs, test, chore, perf, ci).
  • Lint + format + typecheck pass locally and in CI.
  • Unit tests pass. Coverage thresholds met (95% aggregates, 100% VOs, 90% domain services).
  • Mutation testing on changed files ≥75% (aggregates), ≥85% (VOs).
  • No new TODO / FIXME without a linked issue.
  • No .only, .skip, debugger, console.log left behind.
  • Secrets are not committed. .env.example updated if new env vars added.

Features that touch data / domain​

  • tenant_id + RLS policy on any new table.
  • Migration is backward-compatible within current major version.
  • Repository methods accept tenantId as explicit parameter.
  • Domain aggregate guards against cross-tenant references.
  • Branded ID types used (no raw string IDs).
  • Integration tests with Testcontainers cover happy path + failure path.
  • services/<name>/DATA_MODEL.md updated.

Features that touch API​

  • OpenAPI generated, committed, and diff-reviewed.
  • services/<name>/API_CONTRACTS.md updated.
  • Pact consumer contract test added/updated; Pact broker green.
  • Error responses use canonical codes from ERROR_CODES.md.
  • Idempotency-Key handling verified on write endpoints.
  • Cursor-only pagination used.
  • No response leaks domain entities — DTOs only.
  • Deprecation headers set if deprecating.

Features that touch events​

  • New event types added to event-schemas/{service}/{aggregate}/{event}/v{N}.json.
  • services/<name>/EVENT_SCHEMAS.md updated.
  • Outbox pattern used in producer (transactional with aggregate write).
  • Inbox pattern used in consumer (dedupe + idempotent apply).
  • Schema conformance contract test added.
  • No PII in event payload. References by ID only.
  • Retention class (operational / regulated / audit) declared.

Features that touch security​

  • services/<name>/SECURITY_MODEL.md updated.
  • RBAC/ABAC matrix updated in tests.
  • security-reviewer agent run; no critical/high findings.
  • Secrets managed via KMS + Vault.
  • argon2id for any new password handling.
  • JWT TTLs respected (≤15 min access, ≤30d refresh).
  • No PII in logs.
  • test/integration/tenant-isolation.spec.ts still passes.

Features that touch AI​

  • All provider calls go through ai-gateway-service.
  • No direct import of openai / anthropic / etc. outside the gateway.
  • AIProvenance VO attached to every persisted AI artifact.
  • HITL flow: draft_ai → reviewed requires decisionId.
  • Pre-call + post-call moderation applied.
  • Prompt regression suite green (≥parity vs baseline).
  • Safety adversarial corpus green (zero policy violations).
  • AI telemetry fields present (ai.purpose, ai.model, ai.cost_usd, ai.safety.action, …).
  • Feature flag default-off, per-tenant opt-in.

Features that touch frontend​

  • WCAG 2.2 AA — axe-playwright scan shows zero new serious/critical.
  • Both LTR and RTL Storybook stories added.
  • Logical CSS properties only (padding-inline, etc.).
  • All user-facing strings through ICU MessageFormat — no hardcoded English.
  • Animations gated on prefers-reduced-motion.
  • Lighthouse budgets met (LCP/INP/CLS/JS gzip per page).
  • No Redux, no Recharts, no dangerouslySetInnerHTML on user content.
  • Forms use React Hook Form + shared Zod schemas.

Features that touch observability​

  • @ghasi/telemetry used (no vendor SDKs).
  • Log lines include trace_id, tenant_id, request_id.
  • Required span attributes present on DB/cache/HTTP/NATS/S3/AI calls.
  • SLIs/SLOs updated in services/<name>/OBSERVABILITY.md.
  • Any new alert has a runbook + named owner.

Bug fixes (in addition to above)​

  • A regression test is included in the same commit.
  • Root cause documented in the PR body (not just the symptom).

New service (in addition to above)​

  • All 17 docs from SERVICE_TEMPLATE.md exist (stubs acceptable initially).
  • Directory skeleton in place.
  • tenant-isolation.spec.ts, outbox.spec.ts, inbox.spec.ts passing.
  • Pact broker + schema registry updated.
  • OpenTelemetry verified in staging (traces + logs + metrics visible).
  • Helm chart + Terraform module added.
  • SERVICE_READINESS.md signed off by tech lead + SRE before prod.

Before production deploy​

  • Canary 5% for 30 min passed in staging.
  • Rollback plan verified.
  • On-call alerted of deploy window.
  • Feature flags set as intended.

Spec vs code​

  • If this PR changes behavior that contradicts a spec doc, update the spec (with user approval) in the same PR.
  • If this PR adds a new rule worth remembering, add it to AGENTS.md, the matching .cursor/rules/*.mdc, or docs/standards/*.md in the same PR.