Preventing Deployment Regressions: Hard Rules for Multi-Target S3 Workflows

Over the last 3 hours, a development session on queenofsandiego.com deployed a stale local index.html to production S3, inadvertently wiping three features that had been working in the live environment: the JADA → BOOK NOW hero crossfade animation, the Stripe embedded checkout booking flow, and (unexpectedly) resurrected a deleted "Ranch & Coast readers..." hero line that had been intentionally removed in a prior session.

The root cause was straightforward: local file state was ahead of what the developer had last reviewed, but behind what was already live in S3. The deploy command copied the stale local version over the newer production state without validation, and the single-command deploy touched both staging and prod simultaneously, violating the staging-first gate that should have caught the regression.

This incident prompted a formal rule-set to prevent recurrence, codified in the project's agent instructions so it auto-loads on every session.

What Happened: The Regression Chain

• Local → S3 copy without diff: /Users/cb/Documents/repos/sites/sailjada.com/index.html was copied to both the staging.sailjada.com and production CloudFront distributions without first pulling the current S3 state and diffing against it.
• Simultaneous staging + prod deploy: A single command deployed to both targets in one operation, bypassing the manual review gate at staging.
• Missing prior-session context: The session summary from an earlier agent had explicitly warned about stale local files. This warning was present in the project memory but not re-surfaced during file edits.
• No S3 versioning fallback: CloudFront + S3 for this project do not use S3 object versioning, so the old production state was immediately overwritten with no recovery path short of git history.

Result: three distinct features vanished from production, requiring a rollback via CloudFront cache invalidation and re-deployment from git.

Technical Details: The Eight Hard Rules

To prevent this class of error, eight non-negotiable rules were encoded into /Users/cb/Documents/repos/sites/queenofsandiego.com/CLAUDE.md, which is automatically loaded at the start of every session for that project:

D1: Always Pull + Diff Before Editing

Before modifying any file that will be deployed to S3, retrieve the current production state and compare it locally:

aws s3 cp s3://queenofsandiego-web-prod/index.html ./index.html.prod --profile sailjada
diff -u index.html.prod index.html

If the diff shows features you don't recognize or intend to change, stop and ask before proceeding.

D2: Single-Target, Single-Logical-Change Deploys

Never deploy to both staging and production in one command. Always deploy to staging.sailjada.com first (CloudFront dist ID: E... redacted), verify manually or via smoke tests, then promote to production (CloudFront dist ID: E... redacted) in a separate, gated command.

D3: One File Per Logical Change

Each git commit and each deploy should represent one coherent feature or fix. If you're touching index.html, styles.css, and gas-referral/Bootstrap.gs for separate reasons, deploy them separately. This makes rollbacks surgical and audit trails clear.

D4: Obey Your Own Prior Session Warnings

Every session summary that mentions risk (stale files, unverified S3 state, pending approvals) is a future agent's roadmap. If you see a warning in memory or in a CLAUDE.md note, re-check before deploying. If in doubt, re-read the session context and ask.

D5: Snapshot Production Before Overwrite

Since S3 versioning is not enabled on queenofsandiego-web-prod, create a manual backup before any cp` or sync that overwrites:

aws s3 cp s3://queenofsandiego-web-prod/index.html ./backups/index.html.$(date +%s) --profile sailjada

FILE: index.html | SIZE: XXX bytes | SHA256: ... | TARGETS: staging only | GIT: commit ABC | FEATURES MODIFIED: [hero fade, checkout link] | CONFIDENCE: ready

FEATURE: JADA_HERO_FADE | TOKEN: data-feature="jada-crossfade" | STATUS: live in prod
FEATURE: STRIPE_EMBEDDED_CHECKOUT | TOKEN: id="stripe-checkout-embed" | STATUS: live in prod
FEATURE: RANCH_COAST_HERO | TOKEN: id="ranch-coast-hero" | STATUS: deleted (do not resurrect)