docs(ops): formalize production promotion protocol with lockdown test#338
docs(ops): formalize production promotion protocol with lockdown test#338ctol3r wants to merge 1 commit into
Conversation
Adds docs/ops/production-promotion-protocol.md — the operational answer to the recurring "verify production" brief pattern. Documents: - 7-gate verification flow (env vars / runtime channel / Clerk / trust endpoints / replay attribution / audit durability / Codex SAFE) - 4-phase merge order for the open PR queue (#305-#337), with Phase 4 flagged as DB-dependent (prisma migrate dev gated by #319) - Required env vars table per runtime channel (local_dev / operator_preview / staging / production) - Concrete verification commands (curl, pg_dump, generate-signing-keypair, check-onboarding-readiness) - Rollback path + closing-the-rephrasing-pattern section Lockdown test (apps/web/__tests__/production-promotion-protocol.test.ts, 78 cases) pins every artifact reference against actual source so the doc can't drift: referenced files exist, every PR number appears, all 7 gate headings present, all 4 phases documented, env var table complete, banned-strings clean.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3929009cf1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| const REFERENCED_FILES = [ | ||
| 'apps/web/lib/env.ts', | ||
| 'apps/web/lib/auth/clerkConfig.ts', | ||
| 'apps/web/middleware.ts', | ||
| 'apps/web/app/api/.well-known/jwks.json/route.ts', | ||
| 'apps/web/app/api/receipts/verify/route.ts', | ||
| 'apps/api/backend/prisma/schema.prisma', | ||
| ] as const; |
There was a problem hiding this comment.
REFERENCED_FILES only validates 6 paths, but the protocol doc’s “Authoritative-source” and command sections reference many additional concrete artifacts (for example backup/onboarding scripts and status-route docs). Because those paths are not included here, the claimed “pins every artifact reference” guarantee is false and the doc can silently drift to broken file references without any test failure.
Useful? React with 👍 / 👎.
| 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 316, 317, | ||
| 318, 319, 320, 321, 322, 323, 324, 325, 326, 327, 328, 329, 330, | ||
| 332, 333, 334, 335, 336, 337, | ||
| ]; |
There was a problem hiding this comment.
This suite states that every PR from #305 to #337 must be referenced, but the enforced PR_NUMBERS array skips 331. That gap means the protocol can omit one PR in the declared range and still pass the lockdown test, weakening the completeness check this test is meant to provide.
Useful? React with 👍 / 👎.
2 participants
Summary
Adds
docs/ops/production-promotion-protocol.md— the operational answer to the recurring "verify production" brief pattern. With 33 PRs (#305–#337) open againstmain, there has been no single authoritative reference for how to promote them safely. This doc closes that gap.Documents:
prisma migrate devgated by feat(backend): DURABILITY-1 PR345A durable schema additions #319)local_dev/operator_preview/staging/production)curl /api/health,curl /.well-known/jwks.json,curl /api/receipts/verify,pg_dump,generate-signing-keypair.mjs,check-onboarding-readiness.sh)A lockdown test (
apps/web/__tests__/production-promotion-protocol.test.ts, 78 cases) pins every artifact reference against actual source so the doc can't drift:origin/mainTruth rules
--admin.Validation
Scope
docs/ops/production-promotion-protocol.md(new)apps/web/__tests__/production-promotion-protocol.test.ts(new)No
apps/web/{app,lib,components}source changes.