URL Migration & 301 Redirect Policy
Engineering governance for Slloy's 882 table-driven legacy 301 redirects, 8 mandatory URL rules, 90-day shape cooldown, and post-deploy verification.
[!WARNING] Incident Background (
2026-10-19–2026-11-15): After migratingslloy.comto extensionless URLs on2026-10-22, an early catch-all.htmlredirect rule was accidentally removed on2026-11-06and replaced on2026-11-08with a rule that only normalized trailing slashes. As a result, 882 indexed legacy.htmlURLs returned404for 26 days, causing daily GSC impressions to drop from105/dayto2/day.The 8 engineering rules below are enforced by failing CI checks and post-deploy verification gates—never edit or delete redirect rules without following this runbook.
1. Architecture: Table-Driven Worker Middleware (882 Legacy URLs)
Slloy does not use Cloudflare Console Bulk Redirects (which are capped at 20–few hundred rules on lower plans, live outside Git version control, have zero unit tests, and can be deleted silently in the dashboard). Instead, all 882 legacy redirects live in the repository and execute in O(1) inside the Cloudflare Worker:
| Component | Path | Responsibility |
|---|---|---|
| Source of Truth CSV | seo/legacy-redirects.csv | from,to,priority table containing 882 rules (360 P0 core/English URLs + 522 P1 localized URLs). |
| Generated Lookup Table | server/src/legacyRedirects.generated.ts | Auto-generated TypeScript maps (npm run gen:redirects). Never edit by hand. |
| Runtime Middleware | server/src/http/middleware/legacyRedirect.ts | Registered at the very top of server/src/http/routes/public.ts (before .html 404 handling). |
| Regression Test Suite | tests/server/legacy-redirects.test.ts | 9 invariant unit tests (exact count, no .html target, no self-redirect, no redirect chains, 301 status, query preservation, query convergence, trailing slash, POST non-redirect). |
Exact Matching Semantics (legacyRedirect.ts)
- Query-Specific Legacy Model URLs (
39Entries):- Legacy URLs of the form
/<locale>/index.html?model=<id>match the entire path + query string and redirect301to the dedicated clean model page without carrying over?model=<id>.
- Legacy URLs of the form
- Path-Matched Legacy URLs (
843Entries):- Match by exact pathname and preserve the visitor's original query string (so
utm_source,gclid, and referral parameters are never lost).
- Match by exact pathname and preserve the visitor's original query string (so
- Unlisted
.htmlFallback:- Any
.htmlURL not inseo/legacy-redirects.csvchecks if a corresponding clean page exists indist/; if not, it returnsHTTP 404(never a blind suffix strip or catch-all redirect to the homepage).
- Any
2. The 8 Mandatory URL & Redirect Rules
| # | Engineering Rule | Repository Enforcement Mechanism | When Triggered |
|---|---|---|---|
1 | Every URL-changing PR must include a redirect mapping | tools/sitemap-diff.mts compares current build against seo/sitemap-baseline.txt (1,904 baseline URLs). Any removed URL must have a 301 in legacy-redirects.csv or be registered in seo/gone-urls.txt. | PR CI (browser job) & pre-deploy |
2 | Production deploys must curl-verify all 882 legacy URLs | tools/verify-redirects.mts --all verifies every legacy URL returns 301, exact Location, target returns 200, and hop count = 1. | Post-deploy gate in Deploy Production Cloudflare |
3 | 301 rules live in Git with regression tests | seo/legacy-redirects.csv + npm run gen:redirects -- --check + tests/server/legacy-redirects.test.ts. | PR CI (static job) |
4 | Migration sequence: 301 first -> update internal links -> verify -> keep >= 90 days | Release checklist (Section 3). | Every URL migration |
5 | Every deployment emits a release receipt | release-receipt.json artifact + GitHub Actions job summary (timestamp, SHA, actor, redirect verification summary). | Every production deploy |
6 | Three daily automated SEO alarms | tools/seo-daily-alert.mts via .github/workflows/seo-alert.yml (daily 09:30 CST): sitemap count drift > 10%, sample 404 rate > 5%, and 60-URL 301 liveness check. | Daily Cron |
7 | 90-day URL shape cooldown | seo/redirect-policy.json records urlShapeChangedAt: "2026-10-22" (cooldown locked until 2027-01-20 unless an explicit approvedShapeChange override is committed). | PR CI |
8 | Two shortcuts are permanently banned | npm run check:redirects rejects any .html target and rejects bulk redirecting unrelated pages to /; seo/gone-urls.txt is reserved strictly for permanently deleted content (410/404). | PR CI |
3. Standard Runbook: How to Change or Retire a URL
Follow these exact steps whenever renaming or retiring any public page:
- Ship the New Page First: Ensure the new target URL is built and reachable in
dist/. - Append to
seo/legacy-redirects.csv:/old/path.html,/new/path,P1 - Regenerate & Run Local Invariant Checks:
npm run gen:redirects # Regenerates server/src/legacyRedirects.generated.ts npm test # Runs 9 unit tests in tests/server/legacy-redirects.test.ts npm run build:web npm run check:redirects:dist # Verifies all 882+ target URLs exist in dist/ npm run check:sitemap # Verifies no sitemap URL disappeared without a 301 - Document in PR Description: State which URLs were retired, their
301target, and why. - Deploy & Verify:
- Trigger
Deploy Production Cloudflare(operation=deploy,confirmation=DEPLOY). - Confirm the workflow's
verify-redirects --allstep passes100%(882/882 PASS). If any entry fails, execute an immediate Worker rollback (operation=rollback,confirmation=ROLLBACK).
- Trigger
Useful CLI Commands
npm run gen:redirects -- --check # CI check: CSV matches generated.ts
npm run check:redirects # Static invariants (no self-loop, no chain, no .html target)
npm run check:redirects:dist # Verify every redirect target exists in dist/
npm run check:sitemap # Diff current sitemap against seo/sitemap-baseline.txt
npm run verify:redirects -- --sample 40 # Live smoke check of 40 random legacy URLs
npm run verify:redirects -- --all --priority P0 # Live check of all 360 P0 rules
npm run verify:redirects -- --all --out verify.csvSEO Metadata Rules, Sitemap & GSC Operations
Page Title and H1 formulas, fitPageTitle 75-char enforcement, honest Free-to-Try copy rules, sitemap architecture, and Google Search Console operations.
Customer Authentication, Registration Guard & Session Security
Strict separation between customer Better Auth and staff_accounts, disposable email and DoH MX registration guards, Turnstile verification, and CSRF/session protection.