Skip to Content
Slloy Docs
SEO, i18n & Redirect Governance

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 migrating slloy.com to extensionless URLs on 2026-10-22, an early catch-all .html redirect rule was accidentally removed on 2026-11-06 and replaced on 2026-11-08 with a rule that only normalized trailing slashes. As a result, 882 indexed legacy .html URLs returned 404 for 26 days, causing daily GSC impressions to drop from 105/day to 2/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:

ComponentPathResponsibility
Source of Truth CSVseo/legacy-redirects.csvfrom,to,priority table containing 882 rules (360 P0 core/English URLs + 522 P1 localized URLs).
Generated Lookup Tableserver/src/legacyRedirects.generated.tsAuto-generated TypeScript maps (npm run gen:redirects). Never edit by hand.
Runtime Middlewareserver/src/http/middleware/legacyRedirect.tsRegistered at the very top of server/src/http/routes/public.ts (before .html 404 handling).
Regression Test Suitetests/server/legacy-redirects.test.ts9 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)

  1. Query-Specific Legacy Model URLs (39 Entries):
    • Legacy URLs of the form /<locale>/index.html?model=<id> match the entire path + query string and redirect 301 to the dedicated clean model page without carrying over ?model=<id>.
  2. Path-Matched Legacy URLs (843 Entries):
    • Match by exact pathname and preserve the visitor's original query string (so utm_source, gclid, and referral parameters are never lost).
  3. Unlisted .html Fallback:
    • Any .html URL not in seo/legacy-redirects.csv checks if a corresponding clean page exists in dist/; if not, it returns HTTP 404 (never a blind suffix strip or catch-all redirect to the homepage).

2. The 8 Mandatory URL & Redirect Rules

#Engineering RuleRepository Enforcement MechanismWhen Triggered
1Every URL-changing PR must include a redirect mappingtools/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
2Production deploys must curl-verify all 882 legacy URLstools/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
3301 rules live in Git with regression testsseo/legacy-redirects.csv + npm run gen:redirects -- --check + tests/server/legacy-redirects.test.ts.PR CI (static job)
4Migration sequence: 301 first -> update internal links -> verify -> keep >= 90 daysRelease checklist (Section 3).Every URL migration
5Every deployment emits a release receiptrelease-receipt.json artifact + GitHub Actions job summary (timestamp, SHA, actor, redirect verification summary).Every production deploy
6Three daily automated SEO alarmstools/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
790-day URL shape cooldownseo/redirect-policy.json records urlShapeChangedAt: "2026-10-22" (cooldown locked until 2027-01-20 unless an explicit approvedShapeChange override is committed).PR CI
8Two shortcuts are permanently bannednpm 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:

  1. Ship the New Page First: Ensure the new target URL is built and reachable in dist/.
  2. Append to seo/legacy-redirects.csv:
    /old/path.html,/new/path,P1
  3. 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
  4. Document in PR Description: State which URLs were retired, their 301 target, and why.
  5. Deploy & Verify:
    • Trigger Deploy Production Cloudflare (operation=deploy, confirmation=DEPLOY).
    • Confirm the workflow's verify-redirects --all step passes 100% (882/882 PASS). If any entry fails, execute an immediate Worker rollback (operation=rollback, confirmation=ROLLBACK).

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.csv

On this page