Epic: Preserve every URL, link, fragment, asset, and SEO contract

Normative authority:

• Development process
• 02 — URL, link, and SEO compatibility
• 03 — GitHub content and people
• 07 — Security, privacy, and operations
• 09 — Migration, rollout, and roadmap
• 10 — Verification strategy
• Closed owner decisions #12, #24, and #226
• Open cutover-threshold decision #29

PM disposition

OPEN / GROOMED / P0 / coordination epic / release-blocking. This issue is not an implementation lane and is not accepted. The title remains accurate: this epic coordinates preservation of the public URL, link, fragment, asset, metadata, and SEO contracts across their owning issues. Every child and consumer still requires the normal engineer → independent tester → PM → focused commit → local no-ff merge/push → on-call lifecycle.

The evidence anchor is website origin/main@face8e4808d65afbf0374d1ced7a88079950d663 (face8e4). Push run 33295699282 failed its quality gate on frozen projection terminology digests; downstream Django, Playwright, container, publish, and deployment jobs did not complete. Scheduled run 33294786109 is for the older 9a491cd tree and is not current evidence. No unchanged red run is a release or parity acceptance.

Product outcome

Before a production cutover, inventory every current public contract and prove the equivalent Django behavior or an explicit reviewed one-hop redirect/retirement. The gate covers routes and aliases, raw path/query/fragment spelling, assets, canonical/alternate/Open Graph/Twitter metadata, structured data, headings, links/forms, robots, sitemaps, and crawlable server-rendered content. Unknown paths remain real 404s; no homepage catch-all, implicit redirect, guessed identity, or unreviewed retirement is permitted.

Preservation-first remains the default. The accepted scope decision in #29 permits separately reviewed non-article URL/SEO changes; that permission is not a blanket approval and does not bypass the owning issue, compatibility evidence, reversibility, monitoring, or the later #74 production authorization.

Current compatibility evidence

The closed foundations are inputs, not whole-epic completion:

• #34 captured the immutable source/production inventory. The checked manifest has 2,965 rows and the comparison has 4,918 differences; every row remains preserve with review_state=proposed_preserve.
• #35 delivered the generic digest-bound Django parity/redirect/link gate. Its checked-real-input result is intentionally BLOCKED while approved expectations, source adapters, and complete target observations are absent; its fixture PASS is not whole-site approval.
• #36 has an accepted implementation and remains OPEN/HUMAN for two exact redacted live checks against the current deployed release. Its earlier deployment evidence cannot be reused for face8e4.

The checked current baked projection at face8e4 is characterization evidence only. Its manifest records 55 articles, 205 podcasts, 203 transcripts, 98 books, 438 people, 421 events, 12 courses, 282 Wiki pages, and 1,253 media records, plus checked Wiki search/graph artifacts. It does not prove a reproducible source handoff, direct-sync authority, route parity, or production readiness. #253 is returned to grooming because two clean exact regenerations agree with each other but differ from face8e4 on nine tree paths (seven JSON files and the S24E06/S24E07 artwork-name pair). No generated hash or tree from that failed comparison is accepted.

Current release-recovery issues such as #253, #261, #279, and #280 repair the base/evidence gate. They do not replace the owning compatibility contracts and are not silently counted as #3 children.

Source, runtime, and activation boundaries

Editorial source authority

Specification 03 names five editorial repositories:

• DataTalksClub/content — structured articles, podcast metadata/transcripts, books, and adopted media;
• DataTalksClub/datatalksclub.github.io — remaining legacy-main editorial collections and migration provenance;
• DataTalksClub/docs — Docs pages, navigation, and assets;
• DataTalksClub/faq — FAQ courses, sections, questions, and JSON source; and
• DataTalksClub/podwiki — Wiki pages, typed links/citations, graph, and search source.

This is the source inventory, not an approval that all five are enabled or equivalent. #38 owns the exhaustive source rollout/ownership manifest, source-specific direct-sync contracts, and management/cutover boundaries. The current preferred DataTalksClub/content pin and checked generated tree remain subject to the #253 source-first repair.

Source-only work

The first source-only lanes are #292 (Docs), #293 (FAQ), and #294 (Podwiki); a future bounded source-only slice of #39 may inventory legacy tools/conferences. These lanes may parse only caller-supplied immutable checkouts, preserve exact source bytes/provenance and opaque relation keys, and emit deterministic normalized evidence. They must not change public routes, checked projections, models, database rows, direct-sync state, search ranking, graph output, Studio/API behavior, provider state, or production state. Their source-only PASS is not runtime or activation evidence.

Public runtime and projections

The public family owners are #39 (remaining main collections), #40 (exact Person short identity and relations), #41 (Docs), #42 (FAQ), and #43 (canonical /wiki projection). They own their route, content, fragment, asset, metadata, and browser contracts; they are coordinated under #4 and are not direct implementation work inside this epic. #44 alone owns unified search/graph document construction, ranking/filter behavior, graph validation, build identity, activation/fallback/rollback, and Lambda-retirement evidence. It consumes accepted public identities and source seeds; it does not own source ingestion or public-content authority.

The checked/baked projection remains the safe compatibility fallback until an owning source/family cutover is accepted. No issue may hand-edit generated bytes, follow a moving branch at runtime, or treat current checked JSON as proof of source reproducibility.

Direct sync and activation

Closed decision #226 establishes the future direct-sync flow: allowlisted source lock → authenticated immutable checkout → bounded parse/classify/validate → source-owned direct upsert → source-scoped draft/soft-delete transition → immutable SyncLog. #38 is the open direct-sync parent and remains needs grooming; #273–#278 own its bounded schema, runner, ingress/reconciliation, reader cutover, management, and staged-path contract work.

Direct sync is not a site-wide ContentRelease candidate/active-pointer/rollback graph. Historical staged rows remain read-only migration evidence under #219 until #278 contracts their retirement. #276 owns source/family public-reader cutover only after exact source/projection parity and an owner-approved public-authority manifest. A valid source-only parser, direct-upsert run, or search/graph build does not itself activate a public reader.

External and production boundaries

Development noindex/protected-edge evidence belongs to #36. Redirect/410 and SEO-exception records remain with #62 and are constrained by the unresolved operational threshold packet in #29. The course compatibility map and inactive redirect workload belong to #60 and #71. #71 does not activate production; #73 rehearses and #74 separately authorizes production activation, observation, rollback, and legacy retention. No #3 issue text grants provider, DNS, deployment, protected-data, or production authority.

Compatibility contributor ledger

This ledger records ownership/consumption, not acceptance. An open issue, local candidate, synthetic fixture, or prior deployment is not a passed dependency.

Closed/reusable foundations

• #1 — runnable Django/uv foundation and lifecycle.
• #34 — immutable URL/link/fragment/asset/SEO inventory.
• #35 — generic parity/redirect/link gate.

Open gates and contributors

• #36 — development/preview noindex and protected edge/origin HUMAN evidence.
• #39 — remaining legacy-main adapter/public parity; owned under #4 and still needs grooming.
• #40 — exact Person identity/relationship resolution; owned under #4 and still needs grooming.
• #41 — Docs source/public compatibility epic.
• #42 — FAQ source/anchor/feed compatibility epic.
• #43 — /wiki source/public projection; #44 is downstream.
• #44 — unified search/graph projection and separate build lifecycle.
• #60 — complete course HTML/API parity and migration rehearsal.
• #62 — safe settings/SEO-exception umbrella; redirects remain parked behind #29.
• #71 — inactive legacy course-host redirect source/rehearsal; production activation remains #74.

Current route/content regressions

• #162 — restore .html podcast detail canonicals; blocked on #253's accepted source/generator baseline.
• #223 — restore path-only podcast guest links.
• #270 — accept safe localized podcast resources without weakening URL policy.
• #271 — restore whitespace-neutral Wiki/Person prose after link localization.

The source-only children #292–#294 belong to #41–#43 and are listed here as prerequisites, not as direct #3 implementation children. #253 and the release-recovery issues are evidence/base gates, not completion of any compatibility contributor.

Current dependency DAG

closed #1 -> #34 -> #35

#292 -> focused Docs source/public-projection slice under #41
#293 -> focused FAQ source/public-projection slice under #42
#253 + #40 + #294 -> #43
#292/#41 + #293/#42 + #43 + accepted public inputs -> #44 search/graph

#253 repaired source/projection baseline -> #162
#253/#261/#279 repaired current release base -> #223 -> #270
#271 is an independent render-regression lane; all four route/content regressions feed #3 parity

#219 + accepted source/ownership/historical-selection manifest -> #273
#253 + #273 -> #274 -> #275
#253/#273/#274/#275/#272 + owner-approved public-authority manifest -> #276
#276 observed compatibility windows -> #278 staged-path/spec/runbook contract removal

#60 accepted course map -> #71 inactive redirect source/rehearsal
#29 threshold decision + #66 producers + #60/#71/#73 evidence -> #74 production activation/observation

The arrows describe required handoffs, not permission to bypass an issue’s own acceptance gate. In particular, #38 direct-sync work is not a prerequisite for the source-only parser lanes; #44 does not become source authority; #71 does not authorize production; and #74 cannot be backdated to a source-only or development result.

Epic completion gate

• The complete versioned manifest covers all current main/Docs/FAQ/Wiki/course public routes, aliases, raw path/query/fragment spellings, assets, links/forms, metadata, structured data, robots, sitemaps, and machine contracts, with source and production provenance bound to one current release identity.
• Every row has an accepted preserve, an explicit reviewed one-hop redirect, or an approved direct retirement with owner, reason, destination/status, focused test, monitoring, and rollback/retention evidence. No unexplained 404, soft 404, chain, loop, homepage fallback, canonical loss, broken asset, or link/fragment failure remains.
• Main/Person/Docs/FAQ/Wiki and course compatibility contributors deliver accepted source/projection/runtime evidence; current regressions #162/#223/#270/#271 are independently passed where applicable; #44’s search/graph contract is accepted without taking source authority.
• #38/#276’s direct-sync source/family cutover contracts and #278’s historical staged-path retirement are accepted without treating a source-only check or ContentRelease row as public authority.
• #36 development noindex/protected evidence, #60 course/API rehearsal, #62/#29 exception controls, and #71/#73/#74 redirect/cutover gates are complete under their owning issues. Production/provider/DNS/edge actions remain authorized only by their named HUMAN owners.
• Project-wide #72/#76/#77 classification, producer traceability, report, and go/no-go consumers receive exact current evidence; required tester screenshots, PM acceptance, focused commits, no-ff integration, push CI, deployment/readiness, and on-call observations pass for the applicable scopes.

Explicit non-goals

• No source repository write, website-created commit/branch/pull request, moving-branch runtime fetch, hand-edited generated projection, or speculative source enablement.
• No implementation of Docs/FAQ/Wiki/Main/Person adapters, search/graph, direct sync, course migration, redirect Lambda, settings, or provider/production behavior inside this coordination issue.
• No ContentRelease revival as source authority, arbitrary older-SHA sync, automatic rollback, homepage catch-all, URL normalization, or public-route inference from labels/current rows.
• No production/protected-data/provider/DNS/edge/credential access, deployment, activation, sender action, Search Console action, or legacy-write retirement from this issue.
• No acceptance from fixture PASS, source-only output, checked JSON, stale 9a491cd regression evidence, local worktree, or another issue’s role report.

Lifecycle

Keep #3 OPEN until its contributors and downstream release gates provide current accepted evidence. The orchestrator may progress independent source-only and issue-owned lanes, but must not merge or claim the epic from stale projection hashes or an unchanged red baseline. This issue receives coordination/evidence comments only; each implementation, tester, PM, commit, merge, push, deployment, and HUMAN gate remains with its owning issue.

Start with _docs/PROCESS.md and specs 02, 03, 07, 09, and 10, then review the listed child issues and their ownership boundaries. This epic is explicitly coordination work rather than an implementation lane, so do not modify it directly; done means selecting a groomed owning issue with a defined compatibility contract and verification evidence.