SEO & AI Engine Optimization Framework · May 2026

Site Migration: planning, redirect mapping, post-launch monitoring

A comprehensive playbook for the highest risk operation in SEO. Migrations destroy organic traffic when executed badly and improve it when executed well. The canonical horror story is the unplanned…

The Canonical 2026 Reference for SEO Safe Website Migrations Across Platform Changes, Domain Changes, URL Structure Changes, HTTPS Migrations, Design Refreshes, and Consolidations

A comprehensive playbook for the highest risk operation in SEO. Migrations destroy organic traffic when executed badly and improve it when executed well. The canonical horror story is the unplanned migration that drops traffic 60 to 80 percent overnight and never fully recovers. This document codifies the protocols that prevent that outcome.

Cross stack implementation note: code samples are written in plain HTML and bash. For React, Vue, Svelte, Next.js, Nuxt, SvelteKit, Astro, Hugo, 11ty, Remix, WordPress, Shopify, and Webflow equivalents of the page patterns referenced here, see framework-cross-stack-implementation.md.

1. Document Purpose

Migrations are the single highest stakes operation in SEO. The canonical horror story repeats in every agency: a client moved platforms over a weekend without a URL map, without a redirect plan, without staging validation. By Monday organic traffic was down 70 percent. By Friday 80 percent. By month three the client accepted the new normal of a third of pre migration traffic. Years of accumulated SEO value destroyed in 72 hours of bad execution.

This framework specifies the systematic methodology for migrations that preserve and frequently improve SEO value. It applies to every migration class: domain migrations (old-domain.com to new-domain.com), platform migrations (WordPress to Next.js, Shopify to Webflow, custom PHP to Astro), HTTPS migrations (legacy sites recovering from lapsed certs), URL structure changes, subdomain to subfolder moves, site consolidations (M&A), site separations (divestiture), design refreshes, internationalization restructures, and technology stack swaps.

All follow the same fundamental pattern: comprehensive pre migration audit, meticulous URL mapping, clean execution with redirect discipline, vigilant post launch monitoring, structured recovery.

1.1 Migration Risk Categorization

The risk level drives timeline and effort. Compressing the timeline below the risk appropriate minimum is the most reliable predictor of failure.

migration_risk_levels:
  low_risk:
    examples: HTTPS migration on small site; URL pattern change for single section; design refresh preserving every URL
    typical_impact: 0 to 10 percent temporary loss, recovery 2 to 4 weeks
    minimum_timeline: 2 to 4 weeks

  medium_risk:
    examples: platform migration preserving URLs; HTTPS on large site; subdomain to subfolder
    typical_impact: 10 to 25 percent temporary loss, recovery 4 to 12 weeks
    minimum_timeline: 6 to 8 weeks

  high_risk:
    examples: domain migration with URL pattern preserved; platform migration with URL changes; major template restructuring
    typical_impact: 20 to 40 percent temporary loss, recovery 8 to 16 weeks
    minimum_timeline: 8 to 12 weeks

  very_high_risk:
    examples: domain migration combined with platform change; multi site consolidation; complete URL restructure
    typical_impact: 30 to 60 percent temporary loss, recovery 12 to 24 weeks
    minimum_timeline: 12 to 16 weeks

The 60 to 80 percent overnight loss in the horror story corresponds to a very high risk migration executed without methodology. The same migration class executed with this framework loses 30 to 50 percent in week 1 and recovers to baseline plus 5 to 15 percent by month 4.

1.2 Decision Framework: When to Migrate

A migration that does not need to happen should not happen. Justifications worth the risk: the current platform cannot support a strategic technical requirement (SSR, schema completeness, page experience), the current domain carries baggage (acquired domain, prior penalty, name change), the current URL structure prevents critical schema or hreflang patterns, maintenance costs on the legacy stack exceed migration costs within 18 months, a security or compliance requirement mandates the move.

Justifications that do not warrant the risk: aesthetic preferences for a newer framework, vendor incentive structures, perceived modernization without a measurable business outcome.

2. Client Variables Intake

The intake is collected over three sessions: a kickoff call, a technical session with platform engineers, and a written questionnaire. Stored at /var/www/sites/[domain]/migration/intake.yaml. Locked at the start of URL mapping. Updates after that point are addenda.

# MIGRATION FRAMEWORK CLIENT VARIABLES

# --- Migration Identity ---
migration_id: ""
client_name: ""
migration_class: ""              # domain, platform, https, url_structure, consolidation, separation, design_refresh, ma_integration, i18n, tech_stack
risk_level: ""                   # low, medium, high, very_high
business_justification: ""
target_launch_date: ""
hard_deadline: ""                # legal, M&A, brand launch, hosting termination

# --- Source State ---
source_primary_domain: ""
source_cms_platform: ""
source_hosting_provider: ""
source_rendering_pattern: ""     # static_html, ssr, ssg, csr_spa, hybrid
source_trailing_slash_policy: ""
source_total_indexable_pages: 0
source_total_pages_with_traffic_12mo: 0
source_total_pages_with_backlinks: 0
source_estimated_monthly_organic_sessions: 0
source_schema_types_in_use: []
source_hreflang_clusters: []
source_llms_txt_present: false

# --- Target State ---
target_primary_domain: ""
target_cms_platform: ""
target_hosting_provider: ""
target_rendering_pattern: ""
target_trailing_slash_policy: ""
target_url_structure_pattern: ""
target_schema_types_planned: []
target_hreflang_clusters: []

# --- Scope of Changes ---
domain_changing: false
platform_changing: false
url_structure_changing: false
design_changing: false
internal_link_graph_changing: false
schema_implementation_changing: false
hreflang_implementation_changing: false
hosting_changing: false

# --- Backlink and Authority ---
source_referring_domains_total: 0
source_top_authority_referrers_dr60_plus: 0
source_brand_search_volume_monthly: 0
source_wikidata_qid: ""
source_knowledge_graph_entity_present: false

# --- Business Constraints ---
rollback_tolerance: ""           # zero_tolerance, brief_outage_ok, 24h_recovery_ok
maximum_acceptable_traffic_loss_week_1: 0
maximum_acceptable_recovery_window_weeks: 0
ecommerce_revenue_dependence: ""  # critical, significant, modest, none

# --- Team and Process ---
internal_engineering_lead: ""
internal_marketing_lead: ""
internal_executive_sponsor: ""
qa_resources_committed_hours: 0

# --- Tooling Access ---
gsc_verified_source_domain: false
gsc_verified_target_domain: false
ga4_property_continuous: false
bing_webmaster_verified: false
staging_environment_url: ""
dns_administrative_access: false
nginx_server_administrative_access: false

# --- Engagement Variables ---
engagement_tier: ""
audit_scope_for_migration: ""    # standard, deep
migration_budget_hours: 0
post_launch_monitoring_window_days: 90

The most dangerous intake gaps: source_total_pages_with_backlinks unknown, source_schema_types_in_use undocumented, target_url_structure_pattern not yet decided, rollback_tolerance not discussed with the executive sponsor.

3. Migration Type Taxonomy

The migration class drives every subsequent decision. A single class migration follows one playbook. A multi class migration combines playbooks and multiplies risk.

3.1 CMS or Platform Swap

The site moves from one CMS or framework to another. Specific risks: schema implementation differs across platforms, rendering pattern may change (SSR to SSG, or worse SSR to client side rendering), the internal link graph regenerates, plugins providing SEO functionality may not have target equivalents. Examples: WordPress to Next.js, Shopify to Webflow, custom PHP to a modern framework, Drupal to anything, Wix or Squarespace to a self hosted platform.

Minimum checklist: every source URL has a known disposition on the target, every schema type has a target implementation strategy, every template has a target equivalent, rendering pattern matches or exceeds the source for AI bot accessibility.

3.2 Domain Change

Moving to a new domain. Rebrand, M&A consolidation, country code TLD change. The highest classical SEO risk because every backlink, brand signal, sameAs reference, Knowledge Graph claim, and press citation points to the old domain. The redirect map must catch them all. Change of Address in GSC accelerates Google's understanding but does not transfer signals automatically.

3.3 URL Structure Change

URLs change pattern without domain or platform change. Adding or removing trailing slashes, adding a category level, reorganizing taxonomy, consolidating duplicate sections. The class that most often happens without people calling it a migration. A redesign that "modernizes" URLs is a migration. A taxonomy reorganization is a migration. A trailing slash standardization is a migration. All require full URL mapping and redirect discipline.

3.4 HTTPS Migration

Most production sites are HTTPS by 2026. Still applies to legacy government sites, legacy internal tools being publicly exposed, sites recovering from lapsed certificates, sites adopting HSTS preload for the first time. The mistakes are predictable: missing certificate auto renewal, leaving canonical references on HTTP, deploying mixed content, deploying HSTS preload before testing the rollback path.

3.5 Design Refresh

Visual design changes. URLs, schema, content, hosting, platform preserved. Still qualifies as a migration because the internal link graph regenerates, page experience metrics may shift, and accidental schema removal during template work is the most common cause of "we redesigned and lost rankings." Deceptively risky because the team labels it low risk. A refresh that strips author bylines loses E-E-A-T. A refresh that hides FAQ accordions inside JavaScript reveal patterns strips them from AI bot accessibility.

3.6 Consolidation of Multiple Domains

Multiple sites merge into one destination. M&A integration, brand portfolio rationalization, multi region consolidation. Challenges: conflicting canonical content, brand transition signaling, backlink concentration on the destination, schema and entity layer reconciling multiple Organization entities into one.

3.7 Site Separation

The inverse of consolidation. Corporate divestiture, separating B2B and B2C arms, splitting multi region businesses. Risks: source authority does not divide evenly, resulting sites each start with lower authority, internal link patterns that worked at scale do not apply to smaller properties, schema reorganization because the original Organization no longer maps to a single new entity.

3.8 M&A Integration

A specialized consolidation where one entity acquires another. The legal entity change drives schema and entity changes (new sameAs network, Wikidata claim updates, Knowledge Graph re reconciliation). Cross reference framework-knowledgegraph.md.

3.9 Internationalization Restructure

Adding or restructuring hreflang clusters. Introduces hreflang specific risks: reciprocal annotation failures, x-default handling, language and region code formatting, staged deployment. Cross reference framework-hreflang.md.

3.10 Technology Stack Swap

The rendering layer changes while platform, design, URLs, and content are preserved. Moving from PHP to Node.js while keeping WordPress URL structure, replacing a custom static site generator with Astro. SEO risk in rendering pattern changes, schema injection timing, and the long tail of edge cases the original stack handled.

3.11 Multi Class Migrations

Migrations combining classes are the most dangerous configuration. Domain plus platform is doubled risk. Domain plus platform plus URL structure is tripled. Domain plus platform plus URL plus design is the configuration that produces the 60 to 80 percent traffic loss horror stories.

When unavoidable, stage the migration across phases. Phase 1: platform swap with URLs preserved. Phase 2: domain change months later. Phase 3: URL structure change months after. Each phase recovers fully before the next begins.

4. Pre-Migration Audit

Migration without thorough pre migration audit is gambling. The audit follows the same methodology as framework-initialaudit.md, with migration specific extensions. The audit deliverable is the baseline against which post launch recovery is measured.

4.1 Baseline Crawl of the Source Site

Full Screaming Frog crawl per framework-initialaudit.md Section 4.1. Output the complete URL inventory with status codes, redirect targets, canonical tags, meta robots, internal link counts, schema type coverage. The crawl command and config pattern documented in Section 14.2.

4.2 All URLs Inventory From Every Source

The crawl is one input. The complete URL inventory combines five sources to catch URLs the crawl misses: Screaming Frog crawl (URLs reachable from the homepage via internal links), GSC Coverage report (every URL Google has discovered), GA4 historical (every URL that received traffic in the past 12 months), XML sitemap (every URL the site declares as canonical), server access logs (every URL any bot has crawled in the past 90 days).

Each surfaces URLs the others miss. Crawl catches the discoverable graph. GSC catches phantom indexed URLs from prior versions. GA4 catches URLs with traffic that fell out of the internal link graph. Sitemap catches the declared canonical set. Server logs catch parameter variants. Union all five into the master inventory at /var/www/sites/[domain]/migration/source-urls.csv and deduplicate by canonical URL. The master inventory is the universe the URL map must cover.

4.3 All Backlinks Inventory

Pull from Ahrefs and Semrush in parallel. Cross reference to capture backlinks each tool's index misses. Output: every backlink with source URL, target URL, anchor text, DR or DA, first/last seen date, dofollow status. The inventory drives redirect prioritization. URLs with high authority backlinks must have careful 1:1 mapping. URLs with no backlinks may be retired without authority loss.

4.4 All Schema Inventory

Extract every JSON LD block. Aggregate by @type. Document the @id pattern, property completeness, sameAs network, @graph structure.

python3 /home/user/migrations/scripts/schema-inventory.py \
  --crawl /home/user/migrations/[client]/source-crawl/internal_all.csv \
  --output /home/user/migrations/[client]/schema-inventory.json

Output catalogs every schema type in use, count of pages per type, property coverage rate, sameAs network completeness, @id usage pattern, @graph structure pattern, validation pass rates.

4.5 All GSC Indexed URLs

The GSC Coverage report exports the full indexed URL set. For larger sites use the GSC API via ~/Code/tdg-tools/gsc.py with the service account at ~/secrets/tdg-gsc.json. URLs indexed but not in the crawl are phantom URLs from prior versions. URLs in the crawl but not indexed are quality, manual action, or crawl budget signals.

4.6 All GA4 Historical URLs

Pull 13 months of GA4: Pages and screens, Landing page (organic filter), Source/medium with landing page, Conversions by landing page, Engagement time, Exit rates. The history identifies URLs that perform regardless of crawl or index presence. A URL receiving 500 monthly organic sessions but excluded from the sitemap is still load bearing.

4.7 All Canonical Tag Mapping

Extract every rel=canonical declaration. Build the canonicalization map: non canonical URL to canonical target. Identifies clusters of duplicate content the source had collapsed. The target must preserve the collapse via redirect or canonical. Loss of canonical discipline during migration is one of the top three causes of post migration indexing degradation.

4.8 Backup Strategy

Before any migration action: full database backup with verified restore procedure, full file system backup including media library, DNS settings documented with TTL and MX/TXT/CNAME records, email configuration documented, all third party integration credentials documented, DNS provider and hosting provider administrative credentials separately documented, rollback procedure tested in staging. The backup strategy assumes the rollback path will be needed. A plan that assumes the rollback path will never be exercised is a plan with hidden tail risk.

4.9 Pre Migration Audit Deliverable

A 6 to 12 page deliverable at /var/www/sites/[domain]/migration/pre-audit.md. Sections: migration class and business justification (1 page); source state baseline (2 to 3 pages); target state plan (1 to 2 pages); URL inventory summary (1 page); risk register (1 to 2 pages); rollback plan summary (1 page).

5. URL Mapping Discipline

The URL map is the single most important migration document. Every legacy URL must map to a destination on the new site. A URL without a planned destination is a URL that will return 404 on migration day.

5.1 The Four Mapping Patterns

1:1 (preferred): each source URL maps to a single destination. Example: /services/web-design to /web-design-services/.

1:many (pick one canonical destination): the source URL split into multiple destinations. The map picks one destination as the redirect target (the page covering the dominant intent). The other destinations receive internal links from the redirect target.

many:1 (consolidating): multiple source URLs map to a single destination. The destination receives consolidated content covering every signal the source URLs carried.

no destination (410, not 404): source URL intentionally retired. 410 Gone tells Google the URL is permanently gone and accelerates removal from the index. 404 allows Google to assume the URL might return and keeps it in crawl queues for months.

5.2 The URL Map Structure

The master map is a CSV at /var/www/sites/[domain]/migration/url-map.csv.

source_url,destination_url,status_code,mapping_pattern,traffic_12mo,backlinks,schema_types,priority,notes
https://old.example.com/services,https://new.example.com/services/,301,1:1,12000,45,Service,critical,trailing slash
https://old.example.com/blog/post-1,https://new.example.com/blog/article-1/,301,1:1,2400,8,Article,high,slug change
https://old.example.com/long-page,https://new.example.com/services/,301,1:many,3200,12,Service,critical,split into 3 children
https://old.example.com/tag/seo,https://new.example.com/tags/seo/,301,many:1,400,1,Collection,medium,consolidate 10 tags
https://old.example.com/event-2023,,410,retire,0,0,Event,low,past event no value

The priority column drives validation effort. Critical priority URLs receive manual review of the destination before launch. High priority URLs are sampled at 30 percent. Medium at 10 percent. Low spot checked.

5.3 Mapping Principles

Catch all to homepage is the anti pattern: a migration that maps every unmapped URL to the homepage destroys page level signals. Every backlink to a deep page becomes a backlink to the homepage. Search engines treat catch all as evidence of low migration quality.

Every preserved URL must map: a URL with any traffic in the past 12 months, any backlinks, or any rankings must have a 1:1 or 1:many destination.

Retired URLs use 410, not 404. Redirect chains are forbidden: every source URL redirects in a single hop. Mapping is canonical to canonical: source canonical URL to target canonical URL.

5.4 The 1:many Decision Process

Identify the dominant search intent of the source based on its top ranking queries. Identify the destination URL that best matches the dominant intent. Redirect there. Ensure the destination has prominent internal links to the other child destinations. Verify the destination's content addresses the dominant intent before launch. The wrong choice produces an intent mismatch.

5.5 The many:1 Decision Process

The destination must serve every signal the consolidated sources carried. Identify the dominant query set across the consolidated sources. Verify the destination addresses them with sufficient word count, schema, and content depth. If the destination cannot serve the consolidated signals, the consolidation is wrong. A common error is consolidating "for tidiness" without verifying the destination can serve the consolidated intent.

5.6 The Mapping Validation Pass

python3 /home/user/migrations/scripts/url-map-validate.py \
  --map /var/www/sites/[domain]/migration/url-map.csv \
  --source-urls /home/user/migrations/[client]/source-urls.csv \
  --target-staging https://staging.[domain] \
  --output /var/www/sites/[domain]/migration/url-map-validation.json

The validator checks: every source URL has a row in the map, every destination URL resolves on staging with HTTP 200, every retired URL has 410 specified, no source URL appears in the destination column (no chains), no destination is duplicated where mapping is 1:1, every critical priority URL has a destination that exists.

5.7 URL Map Sign Off

Sign off requires three parties: SEO consultant verifies mapping logic and priority, marketing lead verifies destinations serve business intent, development lead verifies destinations exist on the target. Documented at /var/www/sites/[domain]/migration/url-map-signoff.md with named approvers and date. The map is locked at sign off. Changes after are addenda requiring re sign off.

6. The Redirect Plan

The URL map specifies what redirects to what. The redirect plan specifies how the redirects are implemented, validated, and maintained.

6.1 Redirect Status Code Selection

Code Use case in migration
301 Default for preserved URLs moved to a new location. Passes ranking signals.
302 Only for genuinely temporary redirects. Not for migration.
308 Functionally equivalent to 301 for SEO.
410 Default for intentionally retired URLs. Faster index removal than 404.
404 For URLs the site truly does not know about. Not used in planned retirements.
451 Content removed for legal cause.

Wrong code choices that recur: 302 instead of 301 for permanent moves leaks ranking signals. 404 instead of 410 for retired URLs slows index removal. 301 instead of 410 for retirements with no destination creates a wave of soft 404s.

6.2 nginx Configuration Patterns

# Single URL 301
location = /old-path/page {
    return 301 https://new.example.com/new-path/page/;
}

# URL pattern 301 via regex
location ~ ^/blog/post-([0-9]+)/?$ {
    return 301 https://new.example.com/blog/article-$1/;
}

# Subdirectory consolidation
location /old-section/ {
    return 301 https://new.example.com/new-section/$request_uri;
}

# Domain change with path preservation
server {
    listen 443 ssl http2;
    server_name old.example.com;
    location / {
        return 301 https://new.example.com$request_uri;
    }
}

# 410 for retired URLs
location = /event-2023 {
    return 410;
}
location ~ ^/tag/[a-z0-9-]+/?$ {
    return 410;
}

# HTTP to HTTPS
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://example.com$request_uri;
}

# www to non www canonical (every Joseph owned site is non www canonical)
server {
    listen 443 ssl http2;
    server_name www.example.com;
    return 301 https://example.com$request_uri;
}

6.3 The nginx Map Directive for Bulk Redirects

When the URL map has hundreds or thousands of arbitrary 1:1 entries, use the nginx map directive plus a single return statement.

map $request_uri $redirect_target {
    default                       "";
    /services                     /services/;
    /services/web-design          /web-design-services/;
    /blog/post-1                  /blog/article-1/;
    /tag/seo                      /tags/seo/;
}

server {
    listen 443 ssl http2;
    server_name example.com;

    if ($redirect_target != "") {
        return 301 https://example.com$redirect_target;
    }
}

The map is generated from the URL map CSV via the toolchain in Section 14. The map file lives at /etc/nginx/snippets/[domain]-migration-redirects.conf and is included in the relevant server block.

6.4 The Redirect Chain Elimination Protocol

A redirect chain is A to B to C or longer. Chains waste crawl budget, leak signals at each hop, and break when any link in the chain dies. Build the URL map with the final destination for every source URL. Inspect every destination URL for any redirect already configured on the target. If the destination URL itself redirects, replace the source URL's destination with the final URL. Implement only the collapsed direct redirects.

Common chain sources: HTTP to HTTPS plus migration redirect, trailing slash plus migration redirect, www to non www plus migration redirect, legacy redirect from a prior migration. Collapse each pair to a single 301 to the final URL.

6.5 Redirect Verification

python3 /home/user/migrations/scripts/redirect-verify.py \
  --map /var/www/sites/[domain]/migration/url-map.csv \
  --base-staging https://staging.[domain] \
  --output /var/www/sites/[domain]/migration/redirect-verification.json

Verification matrix: every preserved URL returns HTTP 301 with the correct Location header, every retired URL returns HTTP 410, every destination URL returns HTTP 200, no source URL produces a chain, every redirect uses HTTPS, every redirect uses the canonical hostname.

6.6 Long Term Redirect Maintenance

Old domain redirects must remain in place for years. Removing them after 12 months is a leading cause of recovery loss. Domain change redirects: maintain indefinitely as long as the legacy domain registration is renewed. URL structure change redirects: maintain indefinitely. Retired URL 410 responses: maintain indefinitely. HTTP to HTTPS redirects: maintain indefinitely.

The redirect map is a permanent operational document. It is included in configuration management. It is reviewed quarterly. It survives platform changes, hosting changes, and team transitions.

7. Pre-Launch Validation

Pre launch validation is the gate between the staging build and production cutover. Every criterion must pass before launch. A failed criterion is a launch block.

7.1 Staging Environment Build

Staging is a complete replica of the target at staging.[domain]. Runs the target CMS, contains every production page, implements every schema type and hreflang annotation, has the production sitemap accessible, has robots.txt configured to allow crawling once promoted, has the production redirect map active. Staging authentication: HTTP Basic Auth plus robots.txt Disallow all. Both removed on launch day.

7.2 Full URL Coverage Test Against the Redirect Map

python3 /home/user/migrations/scripts/url-coverage-test.py \
  --source-urls /home/user/migrations/[client]/source-urls.csv \
  --map /var/www/sites/[domain]/migration/url-map.csv \
  --staging https://staging.[domain] \
  --output /var/www/sites/[domain]/migration/coverage-test.json

Any URL without a map row is a coverage gap. Any URL whose map row does not produce the expected response on staging is a configuration error. Gaps must be resolved. No URL ships without an explicit disposition.

7.3 All Schema Validation Pass

python3 /home/user/migrations/scripts/schema-validate.py \
  --staging https://staging.[domain] \
  --urls /var/www/sites/[domain]/migration/staging-urls.csv \
  --output /var/www/sites/[domain]/migration/schema-validation.json

Pass criteria: Schema.org Validator at 100 percent zero errors and zero warnings, Google Rich Results Test at 100 percent of eligible types producing at least one valid rich result, reference graph completeness against declared schema_types. Schema lost during migration is rarely noticed until rich results disappear from SERPs weeks later.

7.4 All Canonical Tags Correct

Every staging page has a self referential rel=canonical pointing to its production URL with canonical hostname (non www where applicable), HTTPS, canonical trailing slash. Canonical pointing to a non production URL, a redirect target, or an unauthorized cross domain target is a launch block.

7.5 All hreflang Correct If International

Every annotation reciprocated, every annotation points to canonical URLs, every language and region code uses ISO formatting, x-default present. Per framework-hreflang.md.

7.6 All Robots.txt and llms.txt Correct

Production robots.txt verified to allow crawling of canonical URLs, block legitimate exclusions, reference the production sitemap, allow all reputable AI bots. llms.txt verified to exist at the production root, reference production canonical URLs, match the format per framework-aicitations.md. If the source had llms.txt, the target must too.

7.7 All Sitemap Correct

Every canonical URL in the URL map's destination column appears in the sitemap. No retired URLs. No staging URLs. lastmod dates reflect the migration date for changed URLs. The sitemap validates as XML and returns HTTP 200. The robots.txt references the sitemap URL.

7.8 Core Web Vitals Match or Exceed Source

LCP on staging less than or equal to LCP on source (or both pass 2.5s). INP less than or equal (or both pass 200ms). CLS less than or equal (or both pass 0.1). A staging environment with regressed Core Web Vitals is a launch block. Cross reference framework-pageexperience.md.

7.9 All Internal Links Updated to New URLs

Internal links on staging use production canonical URLs. No internal link points to a legacy URL that would redirect. Validation runs against the staging crawl. Cross reference framework-internallinking.md.

7.10 Pre Launch Validation Sign Off

# Criterion
V1 Staging environment built and accessible
V2 Full URL coverage test (zero gaps)
V3 All schema validation pass
V4 All canonical tags correct
V5 All hreflang correct if international
V6 Production robots.txt configured and correct
V7 llms.txt present if source had it
V8 Production sitemap correct and accessible
V9 Core Web Vitals match or exceed source
V10 All internal links updated to production URLs
V11 Redirect verification complete with zero failures
V12 Zero redirect chains
V13 GA4 tracking deployed and validated on staging
V14 GSC verification ready for target hostname
V15 Backup of source within 24 hours of launch
V16 Rollback plan documented and rollback path tested

Score: 16. Launch approval requires 16 of 16 with zero open critical failures.

8. Launch Day Protocol

Launch day executes the cutover. The protocol is sequential and time bounded.

8.1 Launch Window Selection

Tuesday or Wednesday morning between 09:00 and 11:00 local business time. Full business days with team availability, morning launches allow the full day for monitoring. Avoid Friday afternoons, Mondays, holiday weeks, the day before scheduled vacations. Refuse the day before a major business deadline, during a major marketing campaign, during peak revenue periods, during scheduled press coverage.

8.2 DNS Cutover Window

DNS TTL pre lowered to 300 seconds 48 hours before the launch window. At launch window start, the DNS A or CNAME record is updated to the target hosting. DNS propagation is verified from multiple geographic locations using dig against public resolvers (Google 8.8.8.8, OpenDNS 208.67.222.222, Quad9 9.9.9.9). Once propagation is confirmed (typically 5 to 15 minutes), redirect verification runs against production. TTL raised back to 3600 seconds 24 hours after launch. Pre lowering the TTL prevents the rollback path from being blocked by DNS caching.

8.3 Redirect Verification Within First Hour

python3 /home/user/migrations/scripts/redirect-verify.py \
  --map /var/www/sites/[domain]/migration/url-map.csv \
  --base-production https://[domain] \
  --output /var/www/sites/[domain]/migration/post-launch-redirect-verification.json

Any redirect that worked on staging but fails in production is configuration drift requiring immediate resolution.

8.4 GSC Re Verification of New Site

Submit the production sitemap in GSC. For domain migrations, file the Change of Address request. Trigger URL Inspection on the top 10 priority pages. Verify GSC Coverage shows new pages discoverable (indexed count zero on day 1 is expected).

8.5 Sitemap Submission

Submit the sitemap to Bing Webmaster Tools. Trigger IndexNow ping for priority URLs via curl -X POST https://api.indexnow.org/indexnow -H "Content-Type: application/json" -d @indexnow-launch-payload.json. The launch payload contains the top 100 priority URLs from the destination column.

8.6 Internal Link Audit

Within 4 hours, confirm every internal link on production points to a production URL and no internal link redirects through the legacy map. The audit pulls a crawl of production and cross references against the destination column. Each redirect hop on internal navigation wastes crawl budget.

8.7 Branded Query SERP Check

Within 6 hours, run branded queries and verify the brand name returns the new domain, the Knowledge Panel (if present) still surfaces, the legacy domain's SERP snippet shows the 301. Knowledge Panel updates may take days to weeks; the Knowledge Graph entity update is asynchronous. The sameAs update in Section 11 accelerates the refresh.

8.8 The 24 Hour Traffic Monitoring

GA4 real time and acquisition for the first 24 hours. Real time users should remain within typical daily band (brief dip during cutover expected, recovery within 30 minutes). Organic acquisition shows traffic arriving at the target. Direct traffic shows arrival from bookmarks. Referral traffic validates backlinks are redirected correctly. A 24 hour loss exceeding 30 percent is a yellow flag. A loss exceeding 50 percent is a red flag triggering the rollback decision.

8.9 The 48 Hour Error Monitoring

Server logs and GSC Coverage monitored for 48 hours. Server access logs: 4xx and 5xx response counts vs pre migration baseline. GSC Coverage: new errors vs baseline. Common errors: "Server error (5xx)", "Soft 404", "Redirect error", "Submitted URL not found (404)". By hour 48, configuration issues are typically resolved and Section 9 monitoring takes over.

8.10 Launch Day Communication

Pre launch briefing 30 minutes before DNS cutover: SEO consultant, marketing lead, development lead, executive sponsor on call. Launch confirmation when DNS propagation completes. Hour 1, 6, 24 status updates. Dedicated issue escalation chat or call line. Rollback decision authority: the executive sponsor with input from SEO and engineering leads. Partner notifications at hour 24.

9. Post-Launch Recovery

Post launch recovery is the structured monitoring and response phase that runs for 30 to 90 days.

9.1 The Expected Traffic Dip Pattern

Well executed recovery: day 1 at 70 to 85 percent, week 1 at 75 to 90, week 2 at 85 to 95, week 4 at 95 to 105, month 2 at 100 to 110, month 3 at 105 to 115 percent of pre migration baseline.

Poorly executed recovery: day 1 at 40 to 60 percent, week 1 at 50 to 70, week 4 at 70 to 85, month 3 at 80 to 95, month 6 at 90 to 100 percent or never reaches baseline.

9.2 The Daily Check In For 30 Days

Daily checks: GA4 organic sessions vs baseline (rolling 28 day comparison), GA4 organic conversions, GA4 top 50 landing pages, GSC Coverage new errors, GSC URL Inspection on top 20 priority URLs, GSC Performance impressions and clicks, server log 4xx and 5xx counts, server log Googlebot/Bingbot/GPTBot/ClaudeBot/PerplexityBot crawl rates, sitemap status in GSC and Bing, robots.txt accessibility, SSL certificate validity, Core Web Vitals from GSC Page Experience, redirect spot check on 25 random source URLs, brand search SERP check. Produces a 1 page status note at /var/www/sites/[domain]/migration/daily-status/[date].md.

9.3 The Weekly Recovery Review

Every week for 12 weeks: week over week traffic delta, recovery percentage vs baseline, issue register (open, resolved, deferred), ranking tracker output for top 100 keywords, backlink monitor, schema validation status, competitor SERP movement. The report goes to the executive sponsor, marketing lead, and development lead.

9.4 The Monthly Deep Review

At month 1, 2, and 3. Comprehensive ranking analysis against baseline, traffic recovery by channel, conversion recovery by type, backlink trends, full schema validation pass, full crawl audit comparing current vs staging baseline, AI Overview citation status on priority queries.

The month 3 review is the migration closeout. If recovering on track (above 90 percent by month 3), the closeout produces success documentation and the migration moves to the ongoing audit cadence in framework-ongoingaudit.md. If not on track, the closeout produces the structured remediation plan.

9.5 The Post Launch Issue Categories

9.6 The 30 60 90 Day Recovery Targets

Missing day 30 triggers extended remediation. Missing day 60 triggers executive review and potentially rollback. Missing day 90 categorizes the migration as failed.

10. The Rollback Plan

The rollback plan is the documented procedure for reverting the migration if recovery cannot be achieved by forward fixes. Rollback is the option of last resort.

10.1 When to Roll Back vs When to Fix Forward

Roll back if: traffic loss exceeds 50 percent in week 1 and root cause analysis cannot identify a forward fix within 7 days; conversion loss exceeds 50 percent and the business cannot absorb the revenue impact; a manual action was triggered that cannot be remediated within scope; critical infrastructure on the new site is unreliable; the rollback path remains feasible.

Fix forward if: traffic loss is within the -15 to -50 percent band and issues are identifiable; configuration drift is resolvable; indexing lag is the primary cause and Google is showing progress; the business has committed to the new site (rebrand announcement that cannot be retracted); rolling back would introduce more disruption than the current state.

The rollback decision is the executive sponsor's authority with input from SEO, engineering, and business leads. Documented at /var/www/sites/[domain]/migration/rollback-decision.md.

10.2 The Rollback Decision Criteria

The thresholds are guidelines. The executive sponsor weighs them against business context.

10.3 The Technical Rollback Procedure

Decision communication to the launch team. DNS revert: the record is changed back to the source hosting; with pre lowered TTL, propagation completes within 5 to 15 minutes. Source site verification: source is verified serving correctly at its hostname; if any source data was modified during the migration window, source restore from backup runs first. Reverse redirect verification: any references to new URLs that the source did not previously serve are configured as redirects back to equivalent source URLs. GSC update: if Change of Address was filed, cancel it; leave the new domain GSC property verified to monitor residual signals. Sitemap revert: re submit the source sitemap, remove the new sitemap. Internal communication: communicate the rollback as a strategic decision, not a failure.

The rollback path takes 2 to 6 hours. Feasibility decays over time: at hour 24, rollback is straightforward; at week 1, more reconfiguration; at month 1, may be infeasible because the new site has accumulated traffic, conversions, and content modifications the source no longer has.

10.4 Post Rollback Analysis

The post mortem identifies what went wrong (root cause), what worked, what was missed, what to change for the next attempt. A rollback is not permanent abandonment of the migration goal; it is a deferred attempt with better preparation.

10.5 The Partial Rollback Pattern

Some migrations support partial rollback: reverting a subset while preserving the rest. A domain migration combined with a platform change may roll back the platform while preserving the domain change. Requires the migration to have been staged across phases (Section 3.11). A big bang multi class migration cannot be partially rolled back because the changes are intertwined.

11. Schema and Entity Continuity

Schema and entity continuity is the structural layer of migration. Content can move and rankings can recover, but if the schema graph and entity reconciliation break, the AI synthesis engines and the Knowledge Graph lose track of who the business is. Recovery from entity layer breakage is months versus weeks for content layer recovery.

11.1 The Schema Migration Inventory

Every source schema type must have a target implementation (Section 4.4). Specification: every @type used, every @id pattern (preserve where possible), every property generator, every sameAs reference, every Person entity for authors preserved. The target schema produces a parallel graph that maps to the source's.

11.2 The sameAs Network Update

Update sameAs targets to the new domain: Organization entity sameAs, Wikipedia (official website parameter), Wikidata (P856), LinkedIn company page, Facebook business page, Twitter or X profile, Instagram business profile, industry directory entries, Crunchbase, press release distribution profiles. The update is a 30 to 60 day effort because external profile updates require account access and sometimes review by the receiving platform. The migration timeline accommodates this as a parallel workstream beginning at launch.

11.3 Knowledge Graph Entity Re Claiming

For sites with a Knowledge Graph entity, re reconciliation may be needed after domain migration. When URLs change, Google may maintain the entity but slowly update URL signals (most common, weeks to months), treat the new URLs as a separate entity (entity confusion), or lose track of the entity until manual re submission (worst case, rare).

After migration: run the Knowledge Graph search to verify continuity. If found and references the new domain, no action. If found but still references the old domain, monitor for 30 days. If not found, re claiming via the Knowledge Graph API may be required. Cross reference framework-knowledgegraph.md.

curl -A "Mozilla/5.0" -s "https://kgsearch.googleapis.com/v1/entities:search?query=[business-name]&key=[api-key]&limit=10"

11.4 Wikidata Q-ID Persistence and URL Updates

Wikidata Q-IDs persist through migrations. URL claims (P856 website, P154 logo) update to reflect the new domain. Identify the Q-ID. Update P856. Update any property that referenced URLs. Verify propagation to the SPARQL endpoint within 24 to 48 hours. The Wikidata bot account executes with proper attribution.

11.5 Bing Entity Claim Update

Bing maintains a parallel entity graph used by Bing Search, ChatGPT Search, and Microsoft Copilot. Bing Places (local): update website URL. Bing Webmaster Tools: verify the new domain. Bing Search: trigger re indexing via Bing URL Submission API.

11.6 Schema and Entity Continuity Verification

Within 30 days of launch: schema validation pass rate on the new domain matches or exceeds the source, the Knowledge Graph entity surfaces with correct domain, the Knowledge Panel surfaces with correct domain, Wikidata P856 reflects the new domain, the Bing entity reflects the new domain, the sameAs network update is at least 70 percent complete.

12. AI Surface Continuity

A 2026 specific concern. AI Overview citations cite specific URLs. AI Mode citations cite specific URLs. ChatGPT, Perplexity, Gemini, Claude, and Copilot all cite specific URLs in their grounding context. When URLs change, every citation breaks until the citations are refreshed.

12.1 The AI Re Citation Lag

The 30 to 90 day post launch monitoring includes the AI citation gap re measurement. Expect the gap to widen in week 1, peak around week 2 to 4, and recover by month 2 to 3.

12.2 The AI Citation Refresh Protocol

Fresh content publication on the new domain: publishing 5 to 10 substantial pieces within the first 30 days signals the new domain's editorial activity on priority topics. AI engines weight recently updated content.

Re crawl request via the engine refresh signals: Google via GSC URL Inspection plus sitemap submission plus IndexNow ping. OpenAI, Anthropic, Perplexity: verify the relevant bot Allow rules and let crawl follow the standard schedule.

Internal link graph pointing at the priority URLs: AI synthesis engines weight internal linking as editorial priority.

External link refresh to priority URLs: outreach to high authority backlink sources to update links. The link update accelerates AI re crawl because external authority signals trigger faster grounding crawl prioritization.

The fresh signal pattern: updated content carries a dateModified that AI engines weight. Major content additions in the first 30 to 60 days elevate grounding priority.

12.3 The AI Citation Gap Re Measurement

The citation gap from the pre migration audit (framework-initialaudit.md Section 10.3) is re measured at week 1, 4, 8, and 12 post launch.

Citation gap that does not narrow by week 8 indicates the AI surface optimization in framework-aioverviews.md and framework-aicitations.md requires re application on the new domain.

12.4 The AI Surface Continuity Verification

Within 30 days: AI bot Allow rules in robots.txt confirmed on the new domain, llms.txt deployed, priority query citation status checked across the seven major engines, citation gap measured at week 1, 4, 8, 12. Feeds Section 9.4.

13. Migration Project Plan Template

A 10 to 12 week timeline for a standard migration. Higher risk migrations extend the timeline. Lower risk migrations may compress to 6 to 8 weeks.

13.1 Weeks 1 and 2: Pre Migration Audit

Client intake (Section 2). Migration class classification (Section 3). Pre migration audit (Section 4). Backlink baseline. Schema inventory. Traffic and ranking baseline. GSC and GA4 historical pull. Server log analysis. Backup execution. Output: audit deliverable signed off.

13.2 Weeks 3 and 4: URL Mapping

Master URL inventory consolidation (Section 4.2). URL map drafting (Section 5.2). Mapping pattern decisions (Section 5.1). Priority assignment. Mapping validation pass (Section 5.6). URL map sign off (Section 5.7). Redirect plan drafting (Section 6). Output: URL map locked.

13.3 Weeks 5 and 6: Staging Build

Target platform provisioning. Content migration. Schema implementation (Section 11.1). hreflang implementation. Internal link graph regeneration. Redirect implementation (Section 6). robots.txt and llms.txt configuration. Sitemap generation. GA4 and GSC tracking deployment. Output: staging environment ready.

13.4 Weeks 7 and 8: Pre Launch Validation

Staging full crawl. URL coverage test (Section 7.2). Schema validation (Section 7.3). Canonical validation (Section 7.4). hreflang (Section 7.5). Robots.txt and llms.txt (Section 7.6). Sitemap (Section 7.7). Core Web Vitals (Section 7.8). Internal link audit (Section 7.9). Redirect verification (Section 6.5). Backup of source within 24 hours. Output: pre launch validation sign off with all 16 criteria passing.

13.5 Week 9: Dress Rehearsal

The full launch protocol executed against staging. DNS TTL pre lowering simulated. Redirect verification rehearsal. GSC verification rehearsal. Sitemap submission rehearsal. Traffic and error monitoring tooling tested. Rollback procedure tested. Output: dress rehearsal report.

13.6 Week 10: Launch

DNS cutover (Section 8.2). Redirect verification first hour (Section 8.3). GSC re verification (Section 8.4). Sitemap submission (Section 8.5). Internal link audit (Section 8.6). Branded query SERP check (Section 8.7). 24 hour traffic monitoring (Section 8.8). 48 hour error monitoring (Section 8.9). Output: launch status reports at hour 1, 6, 24, 48.

13.7 Weeks 11 and 12: Post Launch Monitoring

Daily check ins (Section 9.2). Weekly recovery review (Section 9.3). Issue triage. AI surface continuity verification (Section 12.4). Schema and entity continuity verification (Section 11.6). Output: 30 day post launch report. Transition to ongoing audit cadence at week 12.

13.8 Months 2 and 3: Extended Recovery

Weekly check ins compressed to bi weekly. Monthly deep reviews (Section 9.4). AI citation gap re measurement (Section 12.3). Long tail issue remediation. Day 30, 60, 90 recovery target measurement (Section 9.6). Output: month 3 migration closeout.

13.9 Effort Budget by Risk Level

All values in hours. Low risk: 60 to 120 total. Medium: 120 to 240. High: 240 to 480. Very high: 480 to 960. Each tier scales proportionally across audit, URL mapping, staging, validation, launch, and monitoring phases. Assumes one SEO consultant plus one development engineer plus internal client team availability. Larger migrations require multi person teams.

14. Bubbles-Hosted Migration Toolchain

The migration toolchain runs on the Bubbles self hosted server at IP 169.155.162.118. Intentionally self hosted with no third party CDN or proxy in the path. Migration data is sensitive client information and the infrastructure mirrors the principle of client trust the engagement is built on.

14.1 Bubbles Server Profile

Debian amd64 with 16 GB RAM. LAN at 192.168.1.132 / 192.168.1.173. Tailscale at 100.90.97.104. Public at 169.155.162.118. SSH via Tailscale. nginx vhosts under /var/www/sites/. Migration deliverables under /var/www/sites/[domain]/migration/. Working files under /home/user/migrations/.

14.2 Screaming Frog SEO Spider on Linux

screamingfrogseospider --crawl https://[source-domain] \
  --headless --save-crawl \
  --output-folder /home/user/migrations/[client]/source-crawl/ \
  --config /home/user/migrations/configs/sf-migration-source.seospiderconfig \
  --export-tabs "Internal:All,External:All,Response Codes:All,Canonicals:All,Hreflang:All" \
  --export-format csv

Config: JavaScript rendering enabled, custom extraction rules for schema JSON LD, canonical tags, hreflang, meta robots, crawl size up to 1 million URLs, UA rotation across Googlebot, GPTBot, ClaudeBot, PerplexityBot. For source sites exceeding Bubbles' memory, the crawl runs from a development machine and syncs to Bubbles.

14.3 Python Scripts for URL Mapping Diff

Scripts at /home/user/migrations/scripts/. url-map-validate.py validates the URL map against source inventory and staging (Section 5.6). url-coverage-test.py tests the source inventory against staging via the redirect map (Section 7.2). redirect-verify.py verifies every redirect against staging or production (Sections 6.5 and 8.3). Each outputs JSON plus a markdown summary.

14.4 nginx Rewrite Rule Generator From CSV Mapping

python3 /home/user/migrations/scripts/csv-to-nginx.py \
  --map /var/www/sites/[domain]/migration/url-map.csv \
  --domain [domain] \
  --output /etc/nginx/snippets/[domain]-migration-redirects.conf

Produces the map directive pattern from Section 6.3 for arbitrary 1:1 mappings, regex location blocks for pattern matches, dedicated location blocks for 410 retirements. Handles URL encoding, trailing slash policy, hostname normalization, status code selection.

14.5 Redirect Chain Validator

python3 /home/user/migrations/scripts/redirect-chain-validate.py \
  --map /var/www/sites/[domain]/migration/url-map.csv \
  --base https://[staging-or-production] \
  --output /var/www/sites/[domain]/migration/redirect-chain-validation.json

Detects static chains (map declares A maps to B and B maps to C) and live chains (map declares A maps to B, but the live environment redirects B to C).

14.6 Sitemap Diff Tool

python3 /home/user/migrations/scripts/sitemap-diff.py \
  --source https://[source-domain]/sitemap.xml \
  --target https://[staging-or-target-domain]/sitemap.xml \
  --map /var/www/sites/[domain]/migration/url-map.csv \
  --output /var/www/sites/[domain]/migration/sitemap-diff.json

Identifies URLs in source sitemap with no target entry, URLs in target that did not exist in source, URLs in both with different lastmod values.

14.7 Schema and GSC/GA4 Pull Scripts

schema-inventory.py extracts every JSON LD block (Section 4.4). schema-validate.py tests every staging page against Schema.org Validator and Google Rich Results Test (Section 7.3). GSC pull via ~/Code/tdg-tools/gsc.py with service account at ~/secrets/tdg-gsc.json. GA4 pull via ga4-pull.py. Both run at project start to establish the baseline.

14.8 IndexNow Submission Script

indexnow-submit.py accelerates Bing, Yandex, and Naver indexing of new URLs. Runs at launch and at each subsequent priority URL update.

14.9 Migration State Storage and Archive

Migration state in BadgerDB at /home/user/migrations/db/: project metadata, version history of URL maps and redirect plans, validation result history, daily check in archive. Deliverables archived to /mnt/storage/migrations/[client]/[migration-id]/ containing pre-audit.md, url-map.csv, redirect-plan.md, pre-launch-validation.md, launch-day-protocol.md, post-launch-monitoring/, source-crawl/, target-crawl/, schema-inventory.json, redirect-verification.json, rollback-decision.md (if applicable), closeout-report.md.

14.10 No Third Party CDN or Proxy

The Bubbles migration toolchain operates without any third party CDN or proxy in the path. Migration data is sensitive. Routing through external infrastructure introduces dependencies. For client sites where third party CDN is part of the existing stack, the migration notes the configuration but does not recommend adding new third party infrastructure.

14.11 Toolchain Maintenance Cadence

Weekly: nginx log rotation, BadgerDB compaction, validation script regression test. Monthly: Screaming Frog updates, Python script updates, nginx template review. Quarterly: full toolchain test pass, cross reference validation, archive review. Annually: framework library review, migration script regression test.

End of Framework Document

Document version: 2.0 Last updated: 2026-05-14 Maintained by: ThatDeveloperGuy

Site migrations are the highest stakes operations in SEO. The canonical horror story is the unplanned migration that drops traffic 60 to 80 percent overnight. This framework codifies the protocols that prevent that outcome. Apply systematically. Document everything. Maintain old domain redirects long term. The cost of a botched migration is months or years of recovery work; the cost of a careful migration is several weeks of disciplined process.

Companions

Want this framework implemented on your site?

ThatDevPro ships these frameworks as productized services. SDVOSB-certified veteran owned. Cassville, Missouri.

See Engine Optimization service ›