Last updated Jun 14, 2026

Production-readiness review

Per the endpoint maturity ladder, no operation promotes Preview → Beta or Beta → GA without a passing production- readiness review (PRR). The PRR is filed at apps/api/__gates__/prod-readiness/<operation_id>.md and reviewed by the API Council in the weekly forum.

Reviewers

• At least one engineer from the bounded context that owns the resource.
• At least one engineer outside the context (cross-team perspective).
• The on-call lead for the surface week.

Checklist

Every line must be checked or explicitly justified.

Specification

• OpenAPI spec includes the endpoint with full x-matter-explainer, x-matter-mcp, x-matter-rate-limit, x-matter-slo, x-matter-cost-budget, x-matter-cache-layer, x-matter-pii, x-matter-classification, x-matter-maturity extensions.
• Error codes follow the family taxonomy + every code has a docs page at apps/docs/content/docs/errors/<code>.mdx.
• Spec backward-compat check (oasdiff) passes against the previous minor version.
• MCP catalog regenerated; x-matter-mcp.never_expose set intentionally if the op is sensitive.

Implementation

• Pure-logic primitives shipped at apps/api/lib/ with vitest coverage.
• Service package wires Prisma + event emitter with typed Deps.
• Route handler ≤ 50 lines (parse + service call + marshal).
• Canonical middleware pipeline composed (auth, scope, rate-limit, idempotency, dry-run, audit, event).
• Architecture lint passes (no cross-context imports, no raw SQL outside packages/database/src/).

Testing

• Service-unit tests at ≥ 90% coverage.
• Route-integration tests for auth, scope, idempotency, dry- run, audit, event.
• Property test for any invariant-bearing operation (using fast-check + saga-property.ts harness).
• Tenant-isolation red-team test for the new surface.
• Per-mode parity (live, sandbox, test).
• Cross-version compatibility test (current + previous minor).

Operations

• SLO declared + monitored in dashboard (apps/api/__gates__/slo-board.md).
• Cost budget declared + enforced under load test.
• Runbook drafted at apps/docs/content/docs/runbooks/<kind>.mdx.
• Runbook registered in apps/api/lib/runbook-registry.ts.
• On-call rota aware of the new surface.
• Chaos drill added to apps/api/lib/chaos-cadence.ts.

Security

• Threat model updated at apps/docs/content/docs/security/threat-model.mdx.
• PII canary covers any new PII fields.
• PII drift validation gate green (apps/api/lib/pii-drift-validation.ts).
• SOC 2 control map updated if the surface touches a control area (apps/api/lib/soc2-controls.ts).

Customer experience

• Field-level explainers cover every non-trivial property.
• Cookbook recipe authored at apps/docs/content/docs/cookbook/<name>.mdx (≥ 1 paste-able example per supported SDK).
• Error messages translatable per i18n registry.
• Deprecation plan documented if the new endpoint replaces an existing one.

Sign-off

• PRR doc filed at apps/api/__gates__/prod-readiness/<operation_id>.md.
• API Council quorum reviewed + signed off.
• Feature flag rollout ladder defined (shadow → 1% → 10% → 50% → 100% over 4 weeks).

After GA

• One-week stability watch — every alert reviewed by the bounded- context owner.
• One-month customer-feedback review.
• Add the new endpoint to the next quarterly chaos game-day if applicable.