feat: SES production access and monitoring; §7 as single source of operational truth

Q19 is closed — SES production access granted in ca-central-1, confirmed in
writing. Nothing now blocks /contact/.

The structural change is the important one. Specs in docs/ carried their own
copies of resource IDs, regions, DNS records and service state. AGENTS.md §7
is now the single source of truth for operational facts and docs/ cite it
rather than restating it, with the rule recorded in CLAUDE.md under
Conventions.

The reason is the previous commit's DKIM inversion, generalised: the same
fact lived in §7 and docs/05, a correction reached one of them, and the stale
copy told an operator to delete the records that authenticate outbound mail.
A duplicated fact is one that will eventually be wrong in one place, and the
copy that goes stale is the one nobody re-reads. Verified by grep over
docs/*.md — no operational identifier remains.

Also in this change:

- §7 records the SES monitoring: SNS topic ses-alerts, alarms
  SES-BounceRate-High (>= 0.03) and SES-ComplaintRate-High (>= 0.001), and
  the deliberate choice of email feedback forwarding over an SNS feedback
  topic at this volume. The ses-alerts email subscription is stamped PENDING
  CONFIRMATION — the alarms currently notify nobody, now tracked as R9 and on
  the cutover checklist.
- docs/05 records why those alarms are a real control: SES suspends above
  roughly a 5% bounce rate, and under 100 messages a month five bounces
  crosses it.
- Q29: the deploy guard now covers AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
  (emptiness only, never echoed) and INTAKE_ENDPOINT, promoted to job-level
  env. An empty intake endpoint ships a live form posting to nothing, which
  is worse than a failed build. Executed under sh -e across four input
  states; fails closed, leaks nothing.
- docs/06: account ID removed from the backup-bucket callout, pointing at §10
  instead, as README already does.
- astro.config.mjs: prefetch removed entirely. Any setting ships Astro's
  prefetch script to every page against the zero-JS convention. Recorded as a
  decision; revisit against real Lighthouse numbers.

AGENTS.md entry (r) records the full reasoning.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012XquaEq4BgWMCwUqLEyNkF
This commit is contained in:
Pouya Lajevardi
2026-08-26 11:47:17 -04:00
co-authored by Claude Opus 5
parent 6bf1167624
commit 2b6176e4d7
6 changed files with 244 additions and 70 deletions
+13
View File
@@ -162,6 +162,19 @@ page that collects legal inquiries.
URL, Open Graph and Twitter card tags, and appropriate JSON-LD. See
`docs/04-seo-spec.md`. A page without these is not finished.
**`AGENTS.md` §7 is the single source of truth for operational facts.** Resource
IDs, regions, DNS records, credential state, service status — these live in §7
and nowhere else. Specs in `docs/` **cite** §7; they do not restate it. Write
"the region `AGENTS.md` §7 records", not the region. Same for bucket names,
distribution IDs, DKIM tokens, endpoints, and account identifiers.
A duplicated fact is a fact that will eventually be wrong in one place, and the
copy that goes stale is the one nobody re-reads. This rule exists because
`docs/05-backend-spec.md` carried its own copy of the SES DKIM table, a
correction reached §7 and never reached it, and the stale copy ended up telling
an operator to delete the three records that authenticate outbound mail —
under the heading "Never delete".
**A sweep is a command, not a claim.** Any statement that a change was applied
across files — a phrase removed everywhere, a path updated everywhere, a
decision swept through the docs — must cite the command that proves it, and be