Release & rollback runbook (HITL)

[tkowalczyk]

Parent PRD

#22

What to build

This is the one HITL slice in the set. Its definition of done requires a human to walk the documented sequence against real infrastructure. Every other slice in this breakdown is verifiable by tests or CI.

Write the release and rollback runbook that makes manual deployment a repeatable procedure rather than a remembered one.

Deployment stays manual by decision, not by omission — see the deployment model decision in the PRD. A continuous deployment pipeline was considered at priority zero in the original audit and deliberately rejected: for a template it would encode account identifiers, secret names, and branch conventions that no cloner shares, and it could not be meaningfully exercised in this repository. The gap the audit identified is real, but it is a documentation gap, and this slice closes it.

The runbook covers, per environment, in order: the migration gate, the environment-scoped build, the deploy, and how to verify the result. It also documents the two operational procedures that currently exist nowhere — shipping a risky change to a fraction of traffic first, and recovering from a bad deploy without improvising under pressure.

The manual migration gate should be documented as a deliberate choice, so that its absence from automation reads as a decision rather than an oversight.

Note the interaction with #23: once required secrets are declared, deploy fails with a named list when one is unset. The runbook should say so, because that check is the safety net that partially compensates for having no pipeline.

Acceptance criteria

• An ordered release sequence is documented per environment, covering migration, build, deploy, and verification
• The manual migration gate is documented as a deliberate decision with its reasoning, not presented as a limitation
• Rollback is documented with the command that performs it
• Gradual rollout is documented with the command that performs it
• Deploy-time secret validation from Secrets contract & typegen determinism #23 is described as part of the flow
• Human verification: a maintainer follows the documented sequence for one environment end to end without consulting external documentation, and confirms it is complete and correct
• Any step that turned out to need external documentation is folded back into the runbook
• Existing verification passes: type-check, tests, lint

Blocked by

• Blocked by Secrets contract & typegen determinism #23 — the runbook describes deploy-time secret validation introduced there
• Blocked by Cloudflare config posture: source maps, routing, placement #32 — the runbook describes the per-environment routing posture established there

User stories addressed

Reference by number from the parent PRD:

• User story 28
• User story 29
• User story 30
• User story 31

[tkowalczyk]

Status: implementation complete, BLOCKED on the human-verification criterion.

docs/release-runbook.md is written and pushed in 1993b53, with an invariant test (src/release-runbook.test.ts, 43 cases) holding it to the deploy scripts and the manifest.

Acceptance criterion	Status
Ordered release sequence per environment (migrate → build → deploy → verify)	✅ derived from the deploy* scripts, so a new environment fails the build until documented
Manual migration gate as a deliberate decision	✅ with the ordering rule that follows from it — additive before the deploy, destructive as a second release
Rollback with the command that performs it	✅ wrangler rollback, plus its three limits (no schema, no secrets, one Worker)
Gradual rollout with the command that performs it	✅ wrangler versions upload → wrangler versions deploy <id>@10 <id>@90
Deploy-time secret validation from #23 described in the flow	✅ named as the one automated gate the manual process leans on
Human verification: a maintainer walks one environment end to end	❌ outstanding — see below
Steps needing external documentation folded back in	⚠️ folded back for everything found by verification against Wrangler 4.118; the walkthrough may find more
type-check, tests, lint	✅ all exit 0 (253 tests)

Why the human criterion is outstanding: it requires releasing against real infrastructure. No Worker exists in the attached account yet — wrangler versions list returns 404 for tanstack-start-app, -staging and -production — and deploying one is an outward-facing action that was not part of this work.

What the walkthrough should confirm, in order: push the three secrets for one environment; run the four steps for that environment; check that /api/health/ready reports the env you expected; then read the configuration table at the end and confirm each row matches what you observed.

Two things the runbook already corrects, both found by running the commands rather than recalling them:

1. pnpm deploy never ran this repo's deploy script — deploy is one of pnpm's own commands and it wins. README, AGENTS.md and the symlinked CLAUDE.md documented the broken form; all now say pnpm run deploy.
2. After a build, wrangler deploy --env staging does not error. The Vite plugin writes a redirect to a flattened config with no env blocks, so the flag is silently ignored and whatever the last build baked in gets shipped.

Closing this issue is the maintainer's call once the walkthrough is done.