migration-map

migration-map — planning skill (GAP-T4, FREE)

Site-migration / redirect-map playbook per rules/tech-seo-governance.md R-134 (Migration Redirect-Map Contract), R-135 (Migration Phase Gate), R-136 (Post-Migration Verification & Rollback Watch). SF's redirect_chains is a Tier-1 export collected on every crawl but consumed by nothing; this skill turns it (plus the old-site inventory + an operator mapping seed) into a one-to-one redirect map and a post-launch verification.

Recommendation-only (R-135). The engine produces the map + the verification; the operator deploys (htaccess/nginx/platform snippets are recommendations, emitted as report text). The engine NEVER writes to client infrastructure, NEVER calls mcp__gsc__submit_sitemap, and NEVER auto-triggers Change-of-Address (no API exists — GSC UI is operator-only). The Excel write is behind the standard request_approval gate. Scope fence: content-remediation owns single-URL retire (R-90/R-91); this skill handles the BULK map and never re-issues a single-URL retire.

Modes (input mode, enum-in-description per W-F3 D1)

• plan — read the old-site inventory + the operator seed, expand explicit pairs + ordered regex rules over the full inventory, lint, and write redirect_404 rows (status: TODO). A mode value that is neither plan nor verify → DURUR (the skill refuses with an explanation, never guesses).
• verify — read the post-launch crawl (redirect_chains.csv + response_codes_all.csv), confirm each map row resolves old → single-hop 301 → 200, and update matching redirect_404 rows' status (DONE for verified; rows stay TODO/ONGOING otherwise). R-136 cadence (T+1d / T+7d / T+30d) is a report checklist, not a scheduler.

Outputs

• master.xlsx#redirect_404 — {url, inlinks, action, target_url, status} rows (action carries 301/410 per R-91 convention; status = statusEnum). Written via scripts/util/sheet_merge.merge_keyed_rows(..., key_column="url") — idempotent re-runs replace the same url keys in place and preserve foreign rows (sf_projection's own redirect_404 rows survive). sf-import's transaction.replace wipes the sheet → re-run after every sf-import.
• outputs/reports/{date}-migration-map.md — map stats + unmapped triage table + lint findings + server-config snippet section + the R-135 phase-gate checklist (incl. the Change-of-Address line when the domain changes) + (verify) the verification table + rollback recommendation.
• events.jsonl — append_provenance(source.kind="sf_csv", operation="project_excel", target_excel_sheet="redirect_404").

Body protocol

Mirrors tech-audit's shape minus the budget pre-flight (this skill is free).

1. create_run — workflow_runner.create_run(skill="migration-map", mode=...).
2. read inputs — resolve sf-exports/{date}/raw/; plan: read internal_all.csv (Address + Inlinks) + the seed *-url-mapping.csv (old_url,new_url,action) + optional *-mapping-rules.json (validated against schemas/migration-mapping.schema.json); read master.xlsx#gsc_performance (url/clicks, read-only) for traffic-critical detection. verify: read redirect_chains.csv + response_codes_all.csv from the post-launch export.
3. transform (pure) —

   from scripts.planning import migration_map_transform as mmt
   # plan
   out = mmt.build_map(inventory_rows, mapping_pairs, mapping_rules, gsc_rows,
                       homepage_collapse_pct=homepage_collapse_pct)
   # verify
   res = mmt.verify_map(redirect_rows, redirect_chain_rows, response_rows)
   

   build_map lints loops/self-redirects (RED), chains > 3 hops, homepage-collapse %, traffic-critical-unmapped, duplicate-target fan-in — and never silently drops an old URL (every one is a row or listed in unmapped, R-134). verify_map flags 302/307-leaks, chains > 3 hops, 4xx/5xx regressions, and redirect-to-homepage drift (R-136), with a RedirectChainsSchemaDriftError guard on column drift.
4. request_approval — request_approval(...) ("N redirect satırı master.xlsx#redirect_404'e yazılsın mı?"); skill EXIT awaiting_approval.
5. write_excel — on approve, sheet_merge.merge_keyed_rows(master_xlsx, "redirect_404", out["redirect_rows"], key_column="url", run_id=..., project_slug=..., writer="migration-map") (plan), or update matching rows' status (verify).
6. render_report — render_template.py templates/reports/migration-map.template.md → outputs/reports/{date}-migration-map.md (server-config snippets + phase-gate checklist as recommendation text).
7. provenance event — append_provenance(source.kind="sf_csv", operation="project_excel", target_excel_sheet="redirect_404", rows_written=...).
8. deployment confirmation (operator-gated) — only after the operator explicitly confirms the redirects are deployed, emit events_writer.append_work(event_type="redirect_deployed", task_id=...) (event_kind=work). This is gated on the approval/confirm step and is never autonomous — the engine does not deploy and does not assume deployment. Until confirmed, rows stay TODO.
9. complete — workflow_runner.complete(...) with string-typed outputs.

DURUR conditions

Stop and flag the manager — do not patch, do not fabricate.

1. mode is neither plan nor verify (refuse with explanation — never guess a mode).
2. plan: internal_all.csv (inventory) missing — run sf-import first.
3. plan: the operator mapping seed (*-url-mapping.csv) absent — a bulk map needs the operator's old→new decisions (an LLM session may DRAFT the seed; the engine does not invent targets).
4. verify: redirect_chains.csv missing, or its Address column absent (RedirectChainsSchemaDriftError) — re-export with default columns.
5. master.xlsx#redirect_404 row schema mismatch on write (RowSchemaError).
6. Loops / self-redirects in the proposed map (lint.verdict == "RED") — surface for operator resolution before any deploy.
7. PSEO_WORKSPACE_ROOT unset and no workspace_root arg.

Cross-references

• Rules: rules/tech-seo-governance.md (R-134 / R-135 / R-136); rules/content-update-discipline.md (R-91 single-URL 301/410 — the content-remediation scope fence).
• Transform: scripts/planning/migration_map_transform.py (build_map, verify_map, MigrationMapError, RedirectChainsSchemaDriftError).
• Write path: scripts/util/sheet_merge.py (merge_keyed_rows, key=url).
• Schemas: schemas/master-excel.schema.json#redirect_404 (5-col + statusEnum), schemas/migration-mapping.schema.json (optional regex rules), schemas/events.schema.json (redirect_deployed work event — enum-legal, no change).
• Template: templates/reports/migration-map.template.md.
• Command: commands/pseo-migration-map.md.
• Downstream: master-task-sync (optional follow-up tasks via primary_source: "redirect_404"), indexing-ping (sitemap-submit recommendation — operator-consent gated), drift-check.

Discipline checklist

• Recommendation-only — engine never deploys, never submits sitemaps, never auto Change-of-Address (R-135).
• Free — budget.uses_paid_mcp=false; GSC reads are cost-0 and optional.
• Never silently drops a URL — every old URL is a redirect row or listed unmapped (R-134).
• Schema-first — frontmatter validates against skill-frontmatter.schema.json; redirect_404 rows validate against master-excel.schema.json#redirect_404.
• Plugin-agnostik — no slug literals; pure two-mode transform.
• Idempotent write — merge_keyed_rows replaces the same url keys in place; foreign sf_projection rows preserved.
• redirect_deployed event gated on operator confirm — never autonomous (append-only via events_writer).
• Scope fence — BULK map only; content-remediation owns single-URL retire (R-90/R-91).