Production hosting, DNS and content migration — tracking checklist

[alexeygrigorev]

Tracking issue for the production hosting, DNS and content migration. The authority is the runbook — _docs/runbooks/production-hosting-and-dns-migration.md. This issue is the tick-off surface; the runbook holds the detail, the rationale and the verification for every line below. Section references (§) point into it.

What this migration does. datatalks.club moves off GitHub Pages and courses.datatalks.club moves off CMP, both onto this Django deployment, with DNS moving from GoDaddy to Route 53 and email moving to Relay in the main AWS account.

Markers. [P] needs production AWS credentials (387546586013) · [G] needs GoDaddy console access · [OW] one-way or expensive to reverse · [W:x] hard wait of duration x · [B:x] blocked on x.

Lanes. MAIN is the apex/DNS critical path. COURSES, EMAIL, DEV and CLEANUP run in parallel with MAIN and with each other — only the order within a lane is strict, plus the named cross-lane joins.

Companion design documents (linked from the runbook, not restated in it): _docs/design/specs/data-migration-architecture.md · _docs/design/specs/unit-content-pipeline.md · _docs/design/specs/script-inventory.md · the costed Terraform design for website prod/dev + Relay prod/dev, currently at .tmp/infra-design-dev-prod-relay.md and outside version control (D36).

---

Decisions

Resolved (§3.1):

• D1 — two-stage apex swap: apex serves the static site from S3 first, then swaps to the Django site
• D2 — minimal shared dev.; the sandbox account is retired
• D3 — two distinct Lambdas on courses. (maintenance, then redirect)
• D13 — Relay is the sender, not Datamailer
• D18 — one curriculum layout: cohorts/<year>/<module>/module.yaml. llm-zoomcamp already conforms (7 modules); machine-learning-zoomcamp (9) and ai-dev-tools-zoomcamp (4) move. ⚠️ This reverses the earlier advice to revert llm-zoomcamp@c04db93 (_docs/runbooks/session-handoff-20260902.md:53-55) — under D18 that commit is correct and llm-zoomcamp/cohorts/README.md is what is wrong. No public URL moves.
• D19 — modules-format rollout covers every course except stock-markets-analytics-zoomcamp, which stays legacy for 2026. data-engineering-zoomcamp is a candidate to assess, not a commitment.
• D20 — convention over configuration: unit/page structure is consistent across courses and derived by convention, not declared per course
• D21 — DataTalksClub/zoomcamp-template owns that convention (STRUCTURE.md, docs/conventions.md, templates/{root,module,cohort}-README.md). Any layout change includes that repository.
• D22 — dev.datatalks.club carries fake data, never production-derived. Dev Relay therefore never sees a real address, which is what makes the shared dev database low-stakes.
• D23 — Datamailer is the source of Relay's suppression state, and copying it is a precondition of the first production send, not Phase 7 cleanup. Consequence: sandbox Datamailer must survive until that copy is done.
• D24 — no homework slug rewrites; the ^hw(\d+)$ → homework-0N transform is removed, explicit overrides only
• D25 — six cohorts stay skipped: ai-bootcamp-2025, ai-hero-2025, ai-hero-2026, sma-zoomcamp-2026, ai-buildcamp-2, ai-buildcamp-3. Four need only a mapping entry; ai-buildcamp-2/-3 carry edition numbers, not years, which the family+year model cannot express — that pair needs design.
• D26 — the cost bar is website-only. Website (prod + dev) ≤ CMP; Relay is a separate budget.
• D27 — the SEO impact of the apex /docs/, /faq/, /podwiki/ redirect is accepted; no action (also recorded at C3/C4/C5 below)

Open (§3.2) — each one gates the steps that cite it:

• D4 — cache freshness strategy (still unresolved, and it gates the apex swap — see the Phase 5 note)
• D5 — media key scheme
• D6 — zone root placement
• D7 — registrar transfer (deferred)
• D8 — courses-zone fold-in
• D9 — RDS Multi-AZ timing — gates 4.1; single-AZ is what the $169.98 Budget A assumes
• D10 — SPF strategy
• D11 — git history rewrite
• D12 — direct-sync source manifest
• D14 — SES identity owner ⚠️ on the EMAIL critical path
• D15 — Relay sandbox data (clean start recommended; superseded in part by D23 for suppression state)
• D16 — Luma-exporter home
• D17 — Luma refresh owner and cadence
• D28 — SITE.md rollout shape. Two incompatible implementations in flight: one committed to local main in three repos (short copy, deletes description_path), one as six PRs from origin/main (551–635-char copy from content/docs_projection.json, repoints description_path). The website side has already landed and decides part of it — course.yaml no longer accepts description_path at all, so the repointing lane would be rejected with unknown_key. Recommended default: the first lane's convention with the second lane's copy.
• D29 — dev-database placement: dedicated db.t4g.micro (≈$15.68/mo) or logical databases on the production instance ($0). Recommended: dedicated.
• D30 — Relay production database size: db.t4g.medium (≈$52.56) or db.t4g.small (≈$26.28). Recommended: medium.
• D31 — real transactional email volume, and the real newsletter cadence (weekly vs the 5–7/month stated to AWS)
• D32 — NAT gateway (≈$41.09) or NAT instance (≈$7.46). Recommended: gateway.
• D33 — when main/dtc-website joins the policy scan (adding it converts an existing grant into a violation). Recommended: after the apex swap, sequenced with D4.
• D34 — extract modules/relay-host or duplicate two Relay roots. Recommended: extract.
• D35 — retire the main/common bastion in favour of SSM Session Manager (−$6.70/mo, removes a 24/7 SSH-exposed host)
• D36 — give the costed infrastructure design a home in version control

---

Phase 0 — Inventories and prerequisites

MAIN · read-only · §5

• 0.1 [G] Export the complete GoDaddy zone, every record, including a _domainkey sweep
• 0.2 [G] Record the www and join forwarding configurations
• 0.3 [P] Pull the 3-month Cost Explorer baseline
• 0.4 [P] Identify and record the courses hosted zone (Z00653771…)
• 0.5 Owner settles open decisions D4–D10
• 0.6 [P] Record the live SES sending quota and maximum send rate — same step as E.1. Production access already exists and the quota has been raised above the default, so this is a verification step, not a blocker. Two numbers, not one: Max24HourSend must clear ~130,000 recipients in a day alongside transactional traffic, and MaxSendRate decides whether a 130,000 campaign takes ~2.6 h (at 14/s) or ~11 min (at 200/s). If either falls short, the increase is a support request with multi-day lead time and should be raised at once.
• 0.7 Re-verify compatibility artifacts (make compatibility-artifacts-check)

Phase 1 — DNS hosting moves to Route 53

MAIN · §6

• 1.1 [P] [B:D6,D10] Create the main/dns zone; byte-copy every record from 0.1 — ⚠️ written, in main/dtc-website/dns.tf rather than a separate main/dns root (304189f, 73d3364). Note the zone was created while D6 is still open, and the apex record still points at GitHub Pages rather than the new distribution. Apply status not determinable from the repo.
• 1.2 [P] join replacement: API Gateway custom domain, with the ACM CNAME added at GoDaddy now
• 1.3 www strategy — build the Phase 2 distribution first (recommended)
• 1.4 Pre-delegation gate: dns-parity-check green, GoDaddy TTLs lowered [W:48h]
• 1.5 [G] [OW-ish] NS cutover at the registrar; record freeze; mail checks at +1 h and +24 h [W:48h]
• 1.6 Update stale DNS claims in the aws-infra docs

Phase 2 — Apex to S3/CloudFront (stage 1 of the D1 swap)

MAIN · needs Phase 1 · §7 · ✅ EXECUTED 2026-09-02, with a design change

Only the main site tree was rehosted into S3. /docs/, /faq/ and /podwiki/ were not rebuilt — a CloudFront viewer-request Function now 302s them to datatalksclub.github.io. Verified live: x-cache: FunctionGeneratedResponse from cloudfront.

Tree	source_id	Baseline rows	Now
Main site	dtc-main-site	2,301	Served from S3 (200)
Docs	dtc-docs	174	302 → github.io
FAQ	dtc-faq	152	302 → github.io
Podwiki	dtc-podwiki	310	302 → github.io

636 rows — 21.7% of the compatibility contract — now redirect instead of returning 200.

• 2.1 Rebuild the pinned legacy trees — done for dtc-main-site; the other three are no longer rebuilt at all
• 2.2 [P] Bucket + OAC + resolver function + distribution — landed in main/dtc-website/legacy_static_site.tf (038d4c3, 3d66411, 580ef4b) rather than a separate main/legacy-site root. ⚠️ That merge complicates step 7.3, which assumes the legacy site can be retired independently.
• 2.3 [P] Upload the main tree
• 2.5 [P] Apex alias swap — done, apex now answers from CloudFront/S3

Follow-ups this created

• C1 — the compatibility contract no longer describes reality. All 636 redirected rows carry classification: "preserve" / expected_status: 200. The baseline schema hard-codes const: "preserve", so a redirect cannot be expressed in it — only through the digest-bound approved-expectations sidecar. Until that is recorded, the 2.4 parity crawl reports 636 regressions and cannot function as a gate — not for this phase, and not for the 9.4 stage-2 swap that depends on it. Highest priority in the phase.
• 2.4 [B:C1] Staging parity crawl — rescope to the 2,301 S3-served rows plus redirect assertions for the other 636
• C2 — GitHub Pages is now a permanent production dependency, not a rollback net. docs, faq and podwiki must stay live and maintained indefinitely — the apex holds no copy of their content. This invalidates 2.6 ("frozen for ≥30 days") and 7.2 ("retire the four Pages deployments") for three of the four.
• C3/C4/C5 — SEO impact accepted; no action (D27). Owner decision, 2026-09-02: these pages are not meaningfully indexed, so the redirect's search consequences do not need mitigating. This closes three findings together — the missing rel=canonical on the FAQ tree (152 rows; docs and podwiki do carry one), the 302-vs-301 question, and the apex robots.txt still advertising Sitemap: https://datatalks.club/podwiki/sitemap.xml which now redirects off-domain. Recorded so they are not re-raised. Note this does not touch C1 or C2, which are contract and availability problems rather than search problems.
• C6 — Redirect legacy /podwiki/* URLs to the canonical /wiki/* routes #306 is superseded. It records that 310 /podwiki/* URLs would 404 at cutover; they redirect now. Close or rewrite it rather than leaving it describing a condition that no longer exists.
• C7 — the redirect must survive the stage-2 swap. When the apex alias moves to the Django site (4.4), these 636 paths break unless the new distribution carries the same Function or Django answers them itself. Added to the 4.4 gate below.
• 2.6 Keep the main-site Pages deployment live and frozen ≥30 days as the rollback target

Phase 3 — Media to S3

Independent of MAIN · #301 · §8

• 3.1 [P] Land aws-infra PR Copy the existing course platform verbatim and establish its characterization baseline #30; apply main/dtc-website (bucket and upload role only)
• 3.2 Groom and implement Serve public projection media from object storage instead of the git-tracked tree #301 — projection integrity without the git-tracked tree
• 3.2a Resolve the confirmed orphan media file (1,254 files against 1,253 records) — identified as images/podcast/s24e06-how-to-build-ai-that-actually-ships-in-production.jpg, unrecorded on disk and correctly absent from the bucket; still needs a decision on whether to record it or delete it
• 3.3 [P] media-sync initial upload — done; all 1,253 objects are present in s3://dtc-website-media/
• 3.4 [P] media-verify: 1,253/1,253 digest matches plus a two-way set reconciliation
  • 1,253/1,253 verified by fetching every recorded key through CloudFront and re-digesting the bytes — zero unreachable, zero digest mismatches, zero content-type mismatches. Both space-containing keys return 200.
  • two-way set reconciliation — needs s3:ListBucket, so it cannot be done anonymously; there is currently no proof the bucket holds no extra objects
  • idempotency unproven by execution — a second media-sync run should report 0 uploads, but that is inferred from reading content/media_tooling.py:285, not observed
• 3.5 Wire the media store into the deployed task definitions (57fc3ae); the /images/* CloudFront behavior itself still waits on the Phase 4 distribution

Phase 4 — Production stack, prod. and dev., stage-2 swap

MAIN + DEV · §9

• 4.0 [P] Policy-suite amendment first — credential-free and the longest pole. Three fail-closed blockers, all verified in ~/git/aws-infra (§14.6):

  • SOURCE_DIRECTORY_SCOPES is a literal four-element tuple (tests/policy/safe_repository_inputs.py:16-20) and contains none of the new roots; adding one drags in EXPECTED_TERRAFORM_CONFIG_FILES, the source manifest, and the pinned test counts
  • a production root under the DataTalksClub owner cannot pass OIDC004/OIDC005 — both force exact sandbox claim values today
  • aws_iam_instance_profile has zero permitted owners, so Relay cannot enter scope at all
  • (D33) adding main/dtc-website converts its existing cloudfront:CreateInvalidation grant (legacy_static_site.tf:459-469) into a violation — defer until after the apex swap
  • while in there: main/maintenance-page has no enable_deployment gate, no backend block, no allowed_account_ids, no tags — an apply at defaults stands up a live public HTTP API

• 4.1 [P] [B:D9] Production website root — module instantiation, with policy-suite churn budgeted (§9.1). Root naming still open between main/dtc-website and main/website; the costed design recommends main/website.

• 4.2 [P] Minimal dev.datatalks.club on shared production infrastructure; tradeoffs accepted under D2 (§9.2) and made low-stakes by D22 (fake data)

• 4.3 Staging discipline while prod. and the apex both serve: four duplicate-content controls, prod. noindexed (§9.3)

• 4.4 [P] [OW-SEO] Stage-2 apex swap (§9.4), after a six-item gate:

  • parity on prod. against the live apex
  • M8 steps 1–4 complete
  • caching evidence captured
  • rollback rehearsed — including the three-step alias procedure below
  • data freshness: sources re-synced within 72 h and at least N future-dated events (§13.8)
  • full-fidelity CMP import proven against a disposable target (§13.9) — ⚠️ currently unbuilt
  • the /docs/, /faq/, /podwiki/ → github.io redirect survives the swap (C7) — either the new distribution carries the same CloudFront Function, or Django answers those 636 paths itself

  ⚠️ The DNS change alone is not sufficient. CloudFront refuses an alias another distribution already claims, and both apex names are claimed by the legacy distribution (legacy_static_site.tf:269) — a second distribution gets CNAMEAlreadyExists. Order: aws cloudfront associate-alias onto the new distribution → flip the Route 53 aliases → then remove the names from the legacy distribution's aliases. Doing the last step first turns a rehearsed swap into an outage. Alias rollback is 1–10 min; keep the S3 legacy site warm ≥30 days.

Phase 5 — Anonymous edge caching

MAIN · must be proven before 4.4 · §10

• 5.i [website] Route-cache registry, cache-class headers, and no-Set-Cookie/CSRF tests
• 5.ii [P] [aws-infra] Per-class edge policies, anonymous classifier, response guard
• 5.iii [B:D4] Reviewed narrow invalidation grant for the worker role — after or alongside the direct-sync work

⚠️ §10.4 records a hard contradiction between the owner's "update the cache on updates" requirement and the standing ban on cloudfront:CreateInvalidation. Still unresolved, and it gates the apex swap. It needs resolving, not working around — and it is entangled with D33, because main/dtc-website already holds a scoped invalidation grant that only stays legal while that root is outside the scan.

Phase 6 — courses.datatalks.club, two Lambdas

COURSES lane · fully parallel, the zone is already on Route 53 · §11

• 6a.1 Fix the maintenance Lambda: 200 → 503 with Retry-After; track the root, add a backend — the main/maintenance-page root now exists (fcdcdbf) but still returns 200 (lambda/index.js:433-439), and 🚨 unlike main/courses-redirect it has no enable_deployment gate at all — every resource is unconditional, so an apply today creates live resources. "Inactive" here means only that nobody has applied it.
• 6a.2 [P] Deploy dark with a certificate; rehearse the alias swap on dev.courses.datatalks.club
• 6a.3 [P] Activate during the M8 freeze (rollback: revert the alias, rehearsed)
• 6A′ [P] Compatibility views on the new stack — APIs must never cross-host redirect
• 6c.1 [P] main/courses-redirect: generated path map, 301 on GET/HEAD, gated 308 — root written (fcdcdbf) and genuinely inert: every resource carries count = var.enable_deployment ? 1 : 0, defaulting to false
• 6c.2 [P] [B:consumer gate] Redirect Lambda live; CMP infrastructure retained through its window

Phase E — Email via Relay

EMAIL lane · parallel, does not wait for DNS · §11E

Volume, and what it changes. 130,000 newsletter recipients weekly plus transactional ≈ 563,000 messages/month. Consequences already folded into the runbook: SES postage alone is ≈$56/mo (≈$56–91 depending on the real cadence — D31); delivery history grows 0.65–1.04 GB per weekly campaign, 34–54 GB/year unpruned; and §14's old "$15–18/mo for all of main/relay" was wrong by roughly 8× — Relay production is ≈$144/mo.

• E.1 [P] SES quota and send rate recorded — the same step as 0.6. Not a blocker: production access exists (aws-infra/docs/aws-support/2026-08-09-ses-newsletter-quota-increase.md:19) and the quota is raised. That document records the 2026-08-09 state (50,000/24 h, 14/s) and two open increase requests to 200,000/24 h and 200/s; its own follow-up to record the approved values was never done. Do it here.
• E.3 [P] [B:D14 hand-off] main/relay root:
  • bind to the datatalks.club identity and a Relay-owned configuration set
  • outbound only — inbound stays unconfigured, which is the key mitigation from the code audit
  • --memory limits set for the 1 GiB host
  • managed RDS db.t4g.medium, single-AZ, gp3 50 → 500 GB (D30) — not PostgreSQL on the host as sandbox does
  • retention/pruning job shipped in the same change — prune_db_task_results exists and has never been invoked; RDS storage autoscaling is one-way, so this is a go-live prerequisite, not an open milestone
  • backups and one rehearsed restore are part of done. Note C3 ("no backup") is not a defect — Relay has never had a client, the website is its first, so backups/pruning/volume monitoring are capabilities that were never required and now become requirements
  • observability on the django-website injected-alarm contract, decided before the Terraform is written
  • deploy dark
• E.4 Clean-start the data volume (D15); the sandbox Relay stays on as the dev Relay
• E.4a Copy Datamailer's suppression and unsubscribe state into Relay (D23) — a precondition of the first production send, before E.6 stage 1. An empty suppression list re-mails exactly the addresses that already damaged the sending reputation. Fallback if the export is impractical: seed SES account-level suppression. Keeps sandbox Datamailer alive until verified.
• E.5 GATE — both assessments delivered. [B:remediation] — the code-audit verdict is "not ready to send production email":
  • E.5a minimum fix list C1–C4 plus H2 and H5, via groomed issues
  • E.5b observability items 1–9 (items 1 and 1b are under a day's work and get detection to 15 minutes)
• E.6 [B:E.5a] Ramp: a stage −1 shadow week running dry_run at volume, then stages 0–4. What constrains the ramp is deliverability evidence — bounce and complaint rates — not sending capacity. Hard preconditions: the canary and outbox_* alarms re-pointed at Relay with a live subscriber proven; suppression state copied (E.4a) before stage 1; pruning proven before stage 4. Abort thresholds: 3% bounce, 0.08% complaint.
• E.7 Datamailer stays read-only; fixes the 7.4 teardown ordering trap

Phase 7 — Decommission and cost harvest

CLEANUP · after every rollback window has closed · §12

• 7.0 [P] SES identity state mv out of main/cmp — execute early, together with E.3
• 7.0a [P] Rehome the email canary (health probe and alarms) out of main/cmp into main/relay
• 7.1 [P] [OW] Destroy main/cmp — the final Aurora snapshot is the point of no return
• 7.2 [OW] Retire the GitHub Pages deployments — ⚠️ only the main-site one. docs, faq and podwiki are now permanent redirect targets (C2) and must stay live and maintained.
• 7.3 Retire the legacy static site after the 4.4 window closes — ⚠️ it lives inside main/dtc-website/ rather than its own root, so this is surgery on a shared root, not a clean destroy
• 7.4 Sandbox preconditions, then teardown in the corrected order: sandbox Relay → sandbox/website → CMP (7.1) → sandbox Datamailer. Datamailer retires last, held alive by three independent dependencies: sandbox Relay sends through its configuration set; CMP production is its client until 7.1; and the D23 suppression copy must complete first. The old ordering counted its ≈$13–15/mo saving too early.
• 7.5 [P] Remove the cross-account media-bucket read granted by PR Copy the existing course platform verbatim and establish its characterization baseline #30
• 7.6 [P] [OW] Destroy sandbox/website; retire its OIDC pipeline and policy fixtures
• 7.7 [P] Cost Explorer harvest against §14 — expected ≈$270–340/mo freed. ⚠️ main/common is not in the harvest: main/aisl runs in its VPC and needs its NAT, so that NAT can never be retired.

---

Cost — two budgets (D26)

§14 · all figures estimates; Phase 0.3's Cost Explorer pull is the authority for actuals

	Scope	Bar	Est. $/mo	Verdict
Budget A	website prod + dev + shared plumbing + the three small Lambdas	≤ CMP's $180–225	169.98	PASS
Budget B	Relay prod + dev	judged separately	155.48	40% is SES postage
Combined	the actual invoice	—	325.46	vs ≈$193–240 today

• Confirm Budget A's assumptions hold at implementation: single-AZ RDS (D9), dedicated dev database (D29), NAT gateway (D32), Container Insights ON
• Record the transitional peak in the budget alarm: ≈**$597–665/mo** while everything runs at once, ≈$305/mo above steady state. Compressing the overlap is worth more than any single sizing decision.

Seven corrections the costed design found in §14, all now folded in:

• Relay priced at $15–18/mo → ≈$144 for Relay production alone
• "Turn Container Insights off" would put web_running_tasks and worker_running_tasks into permanent ALARM (modules/django-website/observability.tf:27-78, treat_missing_data = "breaching") — withdrawn
• The cited "free S3 gateway endpoint in the module" does not exist — modules/django-website has no VPC endpoint at all, so a new VPC ships with the July 2026 NAT-data failure mode un-fixed unless the endpoint is written at root level
• A new NAT does not replace an existing cost — main/aisl runs in main/common's VPC and needs its NAT
• Aurora Serverless v2 re-examined at a 0-ACU floor and still rejected — the dev readiness probe prevents the pause, so it bills ≈$43.80/mo
• §9.4's apex swap was incomplete — aws cloudfront associate-alias is required
• §7.4's teardown order understated the transitional bill

---

Content ingestion

Runs in parallel with its own gates · §13

• 13.3 Direct-sync programme — in flight, all gates closed
• 13.4 Ongoing update path: target state plus its approval and rollback story
• 13.7 Settle the genuinely undecided ingestion items
• 13.8 Events: the Luma data dump, the freshness gate, and the PII boundary
• 13.9 Full-fidelity CMP database import — two modes specified, only one built
  • Data sources pinned correctly: the production export is the newest /data/tmp/rds-export/rds-prod-*.db, produced nightly by cron (six rotations on disk — always take the newest). course-management-platform/db/db.sqlite3 is CMP's dev database and must not be used for schema mapping.
  • Real counts recorded: courses_course 21, courses_project 52, courses_question 616, courses_homework 128; 20,009 accounts / 20,907 enrollments / 36,547 submissions
  • ⚠️ Schema drift is a real blocker with no escape hatch. The three post-pin tables are not empty in production — courses_emailcampaign 1, courses_systemprojectevaluation 1, courses_systemevaluationcriteriaresponse 11 — so make review-data's fail-closed refusal cannot be waved away as "they're empty anyway". Adopt the upstream migrations or re-pin the adoption; no hand-editing dumps. Re-count at freeze time.
  • ⚠️ Project Attempt N is real production copy, not placeholder junk — 31 of 52 courses_project rows, with a public FAQ entry explaining it (content/faq_projection.json:310). The real placeholder marker is the description prefix Production-like generated (courses/services/local_course_seed.py:362), which appears zero times in production. Filter on that, never on the title.
• 13.10 Course-repository curriculum layout and the unit content pipeline (D18–D21, D24, D25) — detail in _docs/design/specs/unit-content-pipeline.md
  • Move machine-learning-zoomcamp's 9 and ai-dev-tools-zoomcamp's 4 module directories under cohorts/2026/, repairing in the same commit: nine homework.md collisions, 102 relative image references, 103 ](../) back-links
  • Rewrite llm-zoomcamp/cohorts/README.md, which documents the opposite convention
  • Carry the change into DataTalksClub/zoomcamp-template (D21)
  • Delete the ML homework.md module-directory fallback heuristic (unit_links.py:168-171) with the move, not before
  • Fix the 4 ai-dev-tools lesson bodies that open # Module N — <Title> while their unit title is <Title> — a content fix in the course repo; the stripper is correct to leave them

Content-pipeline fixes already landed (aed2497, c928f37, fbab381, 2c97886, 1b1a49f, 1b8352a):

• Every repository-relative link a lesson writes now resolves — 272 relative non-.md links (45 + 219 + 8), 0 unresolved. Independently re-measured; a "288" figure that circulated is not reproducible under this definition.
• Duplicate title heading removed — 103 of 181 units were repeating their title; removals go from 74 to 177 of 181, the 4 remaining being the ai-dev-tools lessons above
• _VIDEO_LINE_RE deleted — it matched 0 of 181 units
• ⚠️ New columns video_url, code_sources (migration 0053) and instructions_source_path (0054) are empty until a reimport, which needs a fresh commit or a cleared run row
• The "Edit on GitHub" 404 mechanism is branch-path absence, not commit-SHA resolution — UnitRepository.edit_url() builds {base}/edit/{branch}/{source_path} (courses/services/unit_assets.py:63-70); no commit SHA appears in any public affordance. The fbab381 guard is still right and stays.

Reference layers

Not steps, but the analysis the steps depend on: §14 cost and security (two budgets) · §14.6 the policy-suite blockers · §15 migration-script specifications · §16 risk register · §17 what this runbook does not cover · Appendix A DNS parity worksheet.

---

Known blockers outside this checklist

• Push llm-zoomcamp@c04db93 and machine-learning-zoomcamp@1aa481e — done. Both are now on their repositories' origin/main (944b35e, 61fdaab). Under D18, c04db93 is the correct layout and ships.
• Push the newer SITE.md commits, which are still local-only in all three repositories — and settle D28 first, since origin/main's course.yaml still carries description_path, which the parser now rejects as an unknown key
• Get consent from the people quoted on the homepage.
• No way to generate article, podcast and event assets in the current style #311 — a repeatable way to generate article, podcast and event assets in the current design style. Courses have one (_docs/design/illustration-assets.md); the three editorial content types do not, and 213 podcast covers are being regenerated.
• Decide the eight external link literals gating the events refresh
• Author or generate the speaker-bio normalization rows for the nine new events
• Decide whether the accent-border ban is global (it is enforced in practice but written down nowhere)
• Redirect legacy /podwiki/* URLs to the canonical /wiki/* routes #306 — 310 legacy /podwiki/* URLs would 404 at cutover — superseded, they now 302 to github.io (see C6)

[alexeygrigorev]

Grooming Complete — terminology baseline-repair slice

This comment grooms only the terminology portion of #309; it does not authorize or rescope the hosting, DNS, data, email, or AWS migration checklist.

Evidence and base

• The frozen implementation base is origin/main at 2d3c28d1b8d1c2f3844f47f664945b42849d5eb9; the runbook blob is 95fa41a184b26031dd90ee053a6449f51cd7ec46.
• On that base, uv run python scripts/check_development_terminology.py reports exactly 102 unclassified legacy term findings. All 102 are in _docs/runbooks/production-hosting-and-dns-migration.md; there are no findings for another path.
• These are deliberate references to the retained development deployment and its migration boundary. The compatibility boundary says the former name remains in physical paths/identifiers until Migrate legacy development Terraform, state, and OIDC identifiers safely #94, while current operator terminology is development: development-legacy-identifiers.md. The migration roadmap still requires an explicit classification for every route/workflow/management action: 09-migration-rollout-roadmap.md.

In scope

• In the website repository, classify the 102 runbook occurrences in development-terminology-allowlist.json with finite, path-scoped, count-bound rules. The current inventory naturally partitions into 34 literal physical paths/names and 68 explicitly contextual migration-boundary phrases; the engineer must provide the occurrence ledger and exact counts rather than relying on line numbers.
• Use the existing policy classes with a reason and follow_up: "#94" (or a more specific approved follow-up where the occurrence is captured evidence). Preserve the runbook's wording and all physical values; this is a baseline classification, not a rename.
• Add a regression assertion for this slice so a whole-file allowance or a bare/catch-all sandbox rule cannot silently replace the contextual rules. A changed occurrence count, unmatched occurrence, overlapping/ambiguous coverage, stale rule, or changed runbook blob fails closed and returns to grooming.

Explicit non-goals and dependency

• No whole-file SHA allowance for the runbook; no single pattern: "sandbox" (or equivalent catch-all); no rewrite of the runbook, frozen captures, generated projections, compatibility hashes, source code, Terraform, AWS state/resources, GitHub environments/OIDC, DNS, email, or migration data.
• The workspace currently contains external runbook work on local main (c96578f, ahead of origin/main). Freeze/reconcile that work before engineering this slice. Start from the resulting exact main and recompute the 102 baseline; if the runbook blob changes, the old ledger/counts are invalid and must not be updated silently.
• Migrate legacy development Terraform, state, and OIDC identifiers safely #94 remains the owner of any state-safe physical/OIDC rename. This issue does not advance or authorize that migration, and the other Production hosting, DNS and content migration — tracking checklist #309 checklist lanes remain independent.

Acceptance and verification

• From the reconciled clean base, the pre-fix ledger reproduces 102 findings, all in the named runbook; the post-fix policy covers every occurrence exactly once, with expected counts summing to 102 and no stale/unmatched rule.
• uv run python scripts/check_development_terminology.py exits 0.
• uv run --frozen pytest core/tests/test_development_terminology.py passes, including tests for count/digest drift, stale rules, and rejection of a whole-file/catch-all exemption for this runbook.
• The engineer handoff and independent tester report record the exact base/head, policy/ledger digests, rule counts, and git diff --check; the allowed source diff is limited to the terminology policy and its regression test. Browser/screenshots are not_applicable because this is a documentation/CI-policy change with no page-render impact.
• PM accepts only after the independent tester reproduces the inventory and confirms no physical identifier or migration behavior changed.

[alexeygrigorev]

Software Engineer Report — terminology baseline-repair slice

Issue: #309

Frozen candidate

• Worktree: issue-309-terminology-engineer-20260902
• Exact base/head commit identity: c96578f09b1284b3c81a11634bdb81599b409733
• The candidate is detached at the external runbook commit, uncommitted, and frozen. The external runbook commit is preserved; this slice does not edit its wording.
• git status --short contains only the two intended modified paths:
  • _docs/compatibility/development-terminology-allowlist.json
  • core/tests/test_development_terminology.py

Ledger and policy

• Runbook: _docs/runbooks/production-hosting-and-dns-migration.md
• Recomputed pre-fix inventory: 102 occurrences, all in the runbook.
• Runbook blob SHA-256: 3cbcd1b2836c13e14740cb4bc1d88ae3ea59c5fc58162504cc1ca6a09413790a
• Finite path-scoped rules: 52 total; 13 physical rules covering 34 occurrences and 39 contextual rules covering 68 occurrences.
• Every occurrence is covered exactly once; expected counts sum to 102. Every rule is count-bound, has an existing policy class/reason, and follows up with #94.
• No runbook whole-file allowance, bare/catch-all term rule, wording change, infrastructure/AWS/Terraform/source/projection change, or physical identifier rewrite.
• Frozen occurrence-ledger SHA-256: 21b474c92d4e0a2ccaed7a246aa00d58051714a07ff6480886c002bbc77cd012
• Policy SHA-256: 42dce1e10b8753cb50637242e57bfcc22a00bb00473fe874faa9e54ed8af21ce
• Regression-test SHA-256: 9cf05a8ef56ca26640cdc4b659bce0fe705e274921967f26c1227e26306484cf

Focused results

• uv run python scripts/check_development_terminology.py — pass.
• uv run --frozen pytest core/tests/test_development_terminology.py -q — 9 passed, 4 subtests passed.
• uv run --frozen ruff check core/tests/test_development_terminology.py — pass.
• uv run --frozen ruff format --check core/tests/test_development_terminology.py — pass.
• uv run --frozen mypy core/tests/test_development_terminology.py — pass.
• git diff --check — pass.

Plan-driven verification

• Plan: .tmp/verification-309/verification-plan.json
• Plan artifact SHA-256: 392df00e4a53cba30559ea7f7ba06456d2e8feb438842ecb59e17618d874ff93
• Controller plan digest: 6c080b3274d879a840146033ccaab4b28dd4e406dd95318f23a41ee1bd7f139b
• Graph digest: 05ffeee99244c9becd5e98e40be08188f1c5e2a61204daece984c3beb1d1bce6
• Source manifest digest: 86cf3891ca4633556eb9551806729b0044ec317290f12572d616999bd6d1f2ee
• Plan source tree: commit c96578f09b1284b3c81a11634bdb81599b409733, tree 6df97a33876e513e8652172da2785cf754ba27f6, 3392 entries.
• Dispositions: rerun for container, content invariants, Django, evidence validation, Playwright, quality, and selector; not_applicable for compatibility and screenshots; no reused or skipped components.
• Container, content invariants, Django, and Playwright passed: container 13 assertions, content invariants 4 assertions, Django 2589 passed/9 skipped of 2598, Playwright 30 passed.
• Evidence and report validation commands passed:
  • make verification-evidence-check VERIFY_PLAN=.tmp/verification-309/verification-plan.json VERIFY_EVIDENCE_DIR=.tmp/verification-309/evidence VERIFY_CONSUMER=engineer
  • make verification-report-check VERIFY_PLAN=.tmp/verification-309/verification-plan.json VERIFY_EVIDENCE_DIR=.tmp/verification-309/evidence VERIFY_REPORT=.tmp/verification-309/verification-report.json VERIFY_PHASE=engineer VERIFY_CONSUMER=engineer
• Report: .tmp/verification-309/verification-report.json (verdict: failure only because of the inherited CI baseline below).
• Screenshots: not_applicable; PM-groomed documentation/CI-policy change has no page-render impact.

Known inherited baseline failure

make test-ci and the quality-contract-v1 test-ci target reproduce one pre-existing failure in ci/tests/test_content_update.py::test_source_specific_counts_are_safe_aggregates:

• expected Podwiki counts: graph_links=13006, graph_nodes=1072, search_documents=2998, wiki_pages=282
• observed: graph_links=12987, graph_nodes=1070, search_documents=2996, wiki_pages=282
• result: 616 passed, 1 failed of 617

The failing assertion is outside the two changed paths and is unchanged by this terminology slice. It should be handled as its own content-invariants/backlog repair rather than folded into #309 terminology work.

Tester handoff

The candidate is ready for independent tester review from the exact c965 base/head. Recompute the 102-occurrence ledger and plan from this frozen worktree, verify one-to-one policy coverage and the unchanged runbook blob, and retain the known Podwiki baseline attribution above. No PM acceptance, commit, push, merge, or deploy has been performed.

[alexeygrigorev]

QA Review — #309 terminology baseline-repair

Disposition: HOLD (candidate scope passes; release envelope is not green).

This is an independent tester report. No product files were changed, committed,
merged, pushed, deployed, or PM-accepted.

Frozen candidate and independent plan

• Candidate worktree: .tmp/issue-309-terminology-engineer-20260902
• Tester worktree: .tmp/verification/issue-309-terminology-tester-20260902
• Exact base and observed HEAD: c96578f09b1284b3c81a11634bdb81599b409733
• Tester worktree status: exactly the two intended modified paths:
  _docs/compatibility/development-terminology-allowlist.json and
  core/tests/test_development_terminology.py
• git diff --check: passed
• Binary patch SHA-256: 4e76e4bece612d1c8fae5157411319caf46ba657c5f95742675447a301780c7e
• Independently recomputed plan:
  .tmp/verification/issue-309-terminology-tester-20260902-artifacts/verification-plan.json
• Plan SHA-256: 957b039f9b9d9b9079ef14b2917b663b4597c5ed24ff8f365c552e55416864b9
• Selection SHA-256: c0db2c2fd86a50031d06dde5ad3f7e08316b6e06ff3652885b3316123c919ad8
• Graph SHA-256: 05ffeee99244c9becd5e98e40be08188f1c5e2a61204daece984c3beb1d1bce6
• Policy version/profile/reason: 5 / full / test_infrastructure
• Source tree: commit c96578f09b1284b3c81a11634bdb81599b409733, tree
  6df97a33876e513e8652172da2785cf754ba27f6, 3,392 entries, manifest
  86cf3891ca4633556eb9551806729b0044ec317290f12572d616999bd6d1f2ee
• The tester plan matches the engineer plan in every field except the generated
  created_at timestamp. It independently selects fresh container,
  content-invariants, Django, evidence-validation, Playwright smoke, quality,
  and selector components; compatibility and screenshots are not applicable.

Issue-contract evidence

• Pre-fix reconstruction using the base policy: 102 unclassified findings,
  all in _docs/runbooks/production-hosting-and-dns-migration.md; no other path.
• Post-fix: 102 occurrences, 52 finite path-scoped rules, covering each
  occurrence exactly once.
• Rule breakdown: 13 physical rules / 34 occurrences and 39 contextual
  rules / 68 occurrences.
• Runbook SHA-256:
  3cbcd1b2836c13e14740cb4bc1d88ae3ea59c5fc58162504cc1ca6a09413790a
• Occurrence-ledger SHA-256:
  21b474c92d4e0a2ccaed7a246aa00d58051714a07ff6480886c002bbc77cd012
• Policy SHA-256:
  42dce1e10b8753cb50637242e57bfcc22a00bb00473fe874faa9e54ed8af21ce
• Regression-test SHA-256:
  9cf05a8ef56ca26640cdc4b659bce0fe705e274921967f26c1227e26306484cf
• uv run python scripts/check_development_terminology.py: passed.
• uv run --frozen pytest core/tests/test_development_terminology.py -q:
  9 passed, 4 subtests passed.
• Ruff check, Ruff format check, and git diff --check: passed.
• No runbook whole-file allowance, bare/catch-all sandbox rule, wording
  change, physical-identifier rewrite, infrastructure/AWS/Terraform/source/
  projection change, or non-candidate path was found.
• Regression mutation probes rejected both an overlapping rule and a runbook
  whole-file allowance. Mutation artifact:
  .tmp/verification/issue-309-terminology-tester-20260902-artifacts/evidence/mutation-regression.log
  (SHA-256 e1748365be64bd64f5512439fc0aade13a26792e9005401fae7e676d6bf6fa30).

Fresh graph-selected evidence

• Container: 13/13 assertions passed; artifact
  evidence/container-check.json, SHA-256
  06482794762051fab7b5234da795b82a4c5a3dc4deca49c6196c9fc2dac29dde.
• Content invariants: 4 assertions passed, one policy file/one record;
  artifact SHA-256 8cf10bde8afec9392b5fad24f7c5a64496e2c1180cad76ad22ec82bc3faaaba2.
• Full Django: 2,598 tests, 2,589 passed, 9 skipped, 0 failed.
• Graph selection/ownership controls: 80 passed.
• make test-ci: 616 passed, 1 failed.
• Quality contract: all targets before test-ci passed; the same one
  test-ci failure made the quality command fail.

Blocking baseline attribution

The sole CI/quality failure is unchanged ci/tests/test_content_update.py::test_source_specific_counts_are_safe_aggregates:

• expected Podwiki: graph_links=13006, graph_nodes=1072,
  search_documents=2998, wiki_pages=282;
• observed: graph_links=12987, graph_nodes=1070,
  search_documents=2996, wiki_pages=282.

The failing test and all Podwiki projections are outside the two changed paths;
the candidate does not mask or alter them. Logs:

• evidence/evidence-validation-output.log, SHA-256
  57c5c7a9445e7d41b7ab9f22e2d635455669fcf69d186ceb08b59a5a37f86e4f;
• evidence/quality-output.log, SHA-256
  c72e3cf5dc80a9a11ae3efe2aee942ea21cb50886e916f3177844c358bcca7ba.

The recomputed plan records Playwright smoke as required by the
test_infrastructure profile. It was not rerun in this handoff because the
exclusive browser lane was owned by another tester and the orchestrator directed
this report to finalize the non-browser verification. The engineer's 30-pass
browser result is therefore not claimed as independent tester evidence. This is
an additional unresolved plan component, not a pass or a screenshot claim.

Screenshots are explicitly not applicable: the plan has
render.impact=false and zero required captures, and the issue is limited to
documentation/CI-policy classification.

Required next step

Resolve the independent Podwiki aggregate contract on its owning backlog lane,
then re-freeze #309 on that exact base and rerun the complete tester plan,
including Playwright smoke, before PM acceptance. No commit, merge, push,
deployment, or closure is authorized by this report.

Tester verdict: HOLD.

[alexeygrigorev]

Product Acceptance — #309 terminology baseline-repair slice

Verdict: HOLD — NOT ACCEPTED.

The issue-specific terminology evidence is satisfactory on the frozen candidate:

• Exact base: c96578f09b1284b3c81a11634bdb81599b409733.
• Pre-fix inventory: 102 findings, all in the named runbook. Post-fix: 52 finite path-scoped rules cover every occurrence exactly once (13 physical / 34 occurrences; 39 contextual / 68 occurrences).
• The terminology checker, focused regression tests, mutation probes, git diff --check, container/content invariants, and full Django passed.
• The candidate diff is limited to _docs/compatibility/development-terminology-allowlist.json and core/tests/test_development_terminology.py; runbook wording and source, infrastructure, AWS, Terraform, and projection behavior are untouched.

I cannot accept or authorize commit, merge, push, or deployment. The independent tester recorded:

• A shared Podwiki aggregate-baseline failure in ci/tests/test_content_update.py::test_source_specific_counts_are_safe_aggregates (expected 13006/1072/2998/282; observed 12987/1070/2996/282).
• Required independent Playwright smoke was selected but not rerun because the exclusive browser lane was occupied; the engineer’s 30-pass result cannot substitute for independent tester evidence.

Replay order after the owning Podwiki baseline repair:

1. Preserve the exact c965 candidate and its evidence; do not amend the runbook or broaden Production hosting, DNS and content migration — tracking checklist #309.
2. Replay only the two-file candidate onto the repaired shared baseline, then recompute exact base/head, ledger/policy/test/plan digests, and git diff --check.
3. The independent tester reruns the complete plan from that frozen candidate, including Playwright smoke, and records the final disposition (screenshots remain not_applicable for this non-rendering slice).
4. PM re-reviews only after the baseline and Playwright gates are green; only then may the normal commit, merge, push, and on-call sequence proceed.

This PM HOLD applies to the terminology slice; the broader tracking checklist remains open.

[alexeygrigorev]

PM coordination clarification — dependency on the Podwiki contract repair

The terminology candidate at c96578f remains held and must not be accepted against the stale #303 aggregate contract. After external/unrelated work is reconciled, #303 is replayed first from one clean exact current-main baseline, independently tested through its complete required envelope, PM-accepted, committed/merged, pushed, and observed green by on-call. That produces the next exact current main (B1) for this slice.

Only then replay the two #309 files on B1. Recompute the 102-finding ledger, finite-rule/policy/test digests, exact base/head, and verification plan; the independent tester must run the complete selected envelope, including Playwright smoke, with no pending required component. PM acceptance follows that PASS. The terminology scope remains unchanged: no runbook wording, physical identifier, migration, source/projection, AWS, or broader checklist change; browser screenshots stay not_applicable for this non-rendering slice.

This is a sequential dependency, not a broad union candidate: #309 receives only the accepted #303 commit in its base, not #303 files in its diff and not reused evidence. The #253 source/projection lane and the rest of #309 remain independent. Any base, policy, projection, or relevant-input drift requires a fresh freeze/replay.

[alexeygrigorev]

PM process resolution — #303/#309 circular baseline

Decision: HOLD remains. The #309 terminology slice is not PM-accepted and is not eligible for commit, merge, push, deployment, or checklist closure.

The current handoffs reveal a required-gate cycle, so the prior sequential instruction (“#303 first, then #309”) is not executable under the governing lifecycle:

• Restore green CI on main: stale podwiki count pins in the content-update contract test #303’s one-file candidate fixes the stale Podwiki aggregate contract and passes its focused test-ci, but its required quality/full-Django gates still fail on the 102 terminology findings that this Production hosting, DNS and content migration — tracking checklist #309 slice repairs; Playwright smoke is pending.
• Production hosting, DNS and content migration — tracking checklist #309’s two-file candidate independently covers all 102 findings and passes its terminology/full-Django checks, but its required make test-ci/quality gate still fails on the stale Podwiki aggregate contract owned by Restore green CI on main: stale podwiki count pins in the content-update contract test #303; Playwright smoke is pending.

PM ruling

• A temporary checkout with both diffs can be run only as a diagnostic/release rehearsal. It is not either issue’s candidate, cannot establish independent acceptance for Production hosting, DNS and content migration — tracking checklist #309, and cannot supply reusable evidence: the source tree, changed-path range, plan, and relevant-input envelope differ.
• No explicit “baseline exception,” skipped, or not_applicable classification is allowed for the sibling failure. The process and quality contract require a terminal independent tester PASS; a red required target remains red even when another issue is expected to fix it.
• Updating Production hosting, DNS and content migration — tracking checklist #309’s acceptance checkboxes alone cannot override the lifecycle or quality contract. The terminology scope stays exactly two files and must not absorb Restore green CI on main: stale podwiki count pins in the content-update contract test #303’s test-contract change.

Exact next actions

1. Keep the frozen Production hosting, DNS and content migration — tracking checklist #309 candidate and current HOLD evidence intact. Do not amend its 102-occurrence ledger, rebase it onto a moving tree, or broaden its diff.
2. The orchestrator/product owner must record a lifecycle decision in a dedicated decision issue and update both issue specifications before another freeze. The process-compliant option is a narrowly defined paired-delivery protocol: isolated Restore green CI on main: stale podwiki count pins in the content-update contract test #303/Production hosting, DNS and content migration — tracking checklist #309 diffs, independent recomputed plans and issue-specific tester evidence, then one separately identified fresh full-envelope release rehearsal on exactly B0 + both focused diffs with no evidence reuse. Only after that evidence is green may each PM gate and focused commit proceed.
3. If that process amendment is not approved, both issues remain HOLD until re-groomed into independently verifiable scopes; no PM baseline waiver is available.
4. After the decision and external-work reconciliation produce clean B0, replay each candidate from the exact approved base, release the exclusive browser slot, run every selected component, and obtain fresh tester-final PASS reports before PM acceptance. The present Production hosting, DNS and content migration — tracking checklist #309 evidence is not reusable.

No #309 source, terminology policy, runbook, infrastructure, projection, or migration change is authorized by this comment.