docs(phase5c): enrollment communications documentation + Google Workspace runbook

- PHASE5C_ENROLLMENT_COMMUNICATIONS.md: the full design doc.
- RUNBOOK_GOOGLE_WORKSPACE_EMAIL.md: every REQUIRES GOOGLE WORKSPACE ADMIN ACTION step
  (mailbox, service account, domain-wide delegation scoped to gmail.send only, SPF/DKIM/DMARC),
  environment variables, testing procedure, production secret handling, rotation, revocation,
  troubleshooting, quotas.
- RUNBOOK_STUDENT_ACTIVATION.md: day-to-day operation of the pipeline from /admin.
- WEBSITE_ENROLLMENT_INTEGRATION.md: explicit website-vs-RootNode responsibility boundary,
  the new contact_email field, and closes the 'RootNode doesn't send activation email yet'
  known limitation this doc previously documented.
- RUNBOOK_SELF_PACED_ENROLLMENT.md, RUNBOOK_STUDENT_ACCOUNT_LIFECYCLE.md: point at the new
  automatic-email behavior and the Resend activation control.
- REMOTE_AND_SELF_PACED_ARCHITECTURE.md, ENGINEERING_SOP.md: close the enrollment-
  communication gap; new ENGINEERING_SOP §16.
- PRODUCTION_VALIDATION_CHECKLIST.md, README.md, platform/README.md: cross-references and a
  Phase 5C production-validation section.
This commit is contained in:
2026-08-25 14:45:18 -05:00
parent b38c46aaec
commit 777efd168d
11 changed files with 595 additions and 29 deletions
+20
View File
@@ -82,5 +82,25 @@ can prove in advance.
admin portal, and `docs/WEBSITE_ENROLLMENT_INTEGRATION.md` is what the website team
actually integrated against (update it if reality drifted during that integration)
## Enrollment communications / Google Workspace email (Phase 5C — see docs/PHASE5C_ENROLLMENT_COMMUNICATIONS.md)
- [ ] Every step in `docs/RUNBOOK_GOOGLE_WORKSPACE_EMAIL.md` marked REQUIRES GOOGLE WORKSPACE
ADMIN ACTION has actually been completed (sending mailbox, service account, domain-wide
delegation scoped to `gmail.send` only, SPF/DKIM/DMARC)
- [ ] `EMAIL_PROVIDER=gws` set in the real production environment — confirm it is NOT left at
the dev-provider default, which would silently mean no real student ever receives email
- [ ] `GOOGLE_SERVICE_ACCOUNT_JSON`, `EMAIL_FROM_ADDRESS`, `EMAIL_FROM_NAME`, `EMAIL_REPLY_TO`,
and `PUBLIC_APP_ORIGIN` are all set from the real production secret store, not left at any
dev/example value
- [ ] `infra/scripts/gws-email-test.js` (opt-in, `RUN_GWS_EMAIL_TEST=true`) run once against a
real `TEST_EMAIL_RECIPIENT` and confirmed delivered — the one and only "does this actually
work" proof this checklist can't fake
- [ ] `COOKIE_SECURE=1` in the real production environment — confirms the dev-preview
notification route (`GET /api/admin/notifications/:id/dev-preview`) is unreachable and no
activation/reset token is ever returned by any API response
- [ ] `GET /metrics`'s notification gauges/counters contain no student_id/email/token/
notification_id/external_event_id in any label value on a real production scrape
- [ ] `docs/RUNBOOK_STUDENT_ACTIVATION.md`'s steps still make sense walked against the real
admin portal, including a real (not dev-provider) activation email actually arriving
Only once every box above is checked against the real server does the deployment graduate from
"infrastructure package built" to "actually in production."