Add complete podcast descriptions with a strict editorial overlay

[alexeygrigorev]

Problem

The website podcast catalogue exposes blank description space for 19 of the 205 source records, including data-team-roles.yaml shown in the mobile report. These records have transcripts, notes, or intros that support concise episode-specific descriptions, but no description field.

The repository's migration verifier correctly requires exact equality with the immutable legacy source snapshot, and the separate missing-media repair attestation correctly says that repair did not change podcast metadata. Editorial additions therefore need their own explicit, strict post-migration overlay rather than weakening legacy verification or rewriting the accepted migration.

Acceptance criteria

• Add concise, truthful, episode-specific descriptions to exactly the 19 currently missing podcast YAML records, derived from existing transcripts/intros/notes.
• Do not add placeholder, meta-review, source-check, or generic SEO filler text.
• All 205 podcasts require a non-empty scalar string description; missing, blank, null, numeric, boolean, sequence, and mapping values fail validation.
• Add a separate dated editorial overlay manifest for exactly these 19 description additions, tied to this issue and the immutable migration source commit.
• The overlay records exact target paths/keys and content digests so undeclared metadata changes, missing entries, extra entries, path traversal, duplicate paths, digest drift, or changes to fields other than description fail closed.
• verify-source compares the immutable legacy source plus only the declared description overlay and remains green; do not weaken the original source-copy comparison.
• The SHA-bound missing-media repair manifest and migration counts remain unchanged and green.
• README documents the post-migration editorial-overlay boundary and podcast description invariant.
• make check, focused overlay tamper tests, make verify-source SOURCE=../datatalksclub.github.io, lint, format, and diff checks pass.

Website integration

After this source change lands, DataTalksClub/website#119 will pin the exact content commit, rebuild only the required podcast projection/provenance deltas without reordering the accepted source array, and render the descriptions in the ordered paginated catalogue. The frozen website #103 candidate must refresh after both changes.

[alexeygrigorev]

Independent tester verdict: PASS

I tested the frozen issue #3 candidate read-only and did not implement or repair it.

Frozen candidate and no-drift boundary

• Baseline content commit: b9a40ba974fdef67ee3a2a70f114734f2581033c
• Candidate file set: exactly 28 modified/untracked files
• Content-set fingerprint before and after testing: cbfa4ba8c3257f86e31e2d16de025c27224565df2a15eba84cc6246c7e73e5ea
• migration.yaml: dd78a343a5f387a74afa914fc6c7e19790e202aa5d6fa9aba08bfda5995c5f86
• Missing-media manifest: 80d3014c47bf57de792473fc1da8f7569daeb55107688c3485153f773948d3aa
• Editorial overlay manifest: 63969508134e8b2ef3c8471e9c8dbccc96842fcfc25225fe02e1ed5a4f5926f6
• Legacy checkout remained at pinned ee43d3fa0929faf691178d79f19528e6f15a83e5; its pre-existing uv.lock modification is external to the candidate and remained the only dirty source path.

Editorial/content audit

• Reconstructed the baseline: exactly 19 of 205 podcasts lacked a valid description, and that set exactly matches the 19 overlay targets.
• Candidate adds descriptions to exactly those 19; no existing podcast description changed.
• All 205 candidate descriptions are non-empty string scalars.
• Independently read the actual transcript, intro, and/or notes for every target. All 19 descriptions are episode-specific and truthful, including the named people, career histories, examples, technologies, practices, and discussion themes.
• Descriptions are concise (28–34 words each) and contain no TODO/TBD, placeholder, source-check, meta-review, or SEO filler language.

Overlay and verifier audit

• Confirmed exact schema, issue/date/baseline/source/migration pins, canonical two-component podcast paths, exact description key, exact ordered 19-row target set, description SHA-256 values, and complete target-file SHA-256 values.
• Confirmed fail-closed handling for manifest-byte drift, malformed/extra keys, missing/extra/duplicate rows, traversal/noncanonical paths, wrong keys/types, description/target digest drift, missing/symlinked targets, and non-string descriptions.
• Confirmed source verification removes only the exact declared description before comparing reconstructed legacy metadata. It accepts the declared value and rejects changed descriptions, undeclared descriptions, and drift in any other metadata field.

Commands and independent probes

• Focused tests: tests/test_editorial_overlay.py tests/test_content.py — 44 passed.
• Independent .tmp/ copy probes: clean overlay accepted; changed description, unrelated title drift, and missing declared target rejected; verifier accepted only the exact declared description and rejected other metadata, declared-description, and undeclared-description drift.
• make check — PASS:
  • content: articles=55, podcasts=205, transcripts=203, books=98, media=815, referenced_media=761
  • repair manifest: repairs=10, added_media=8, media=815
  • editorial overlay: targets=19, field=description
  • tests: 121 passed
  • Ruff lint: passed
  • Ruff format check: 11 files already formatted
• make verify-source SOURCE=/home/alexey/git/datatalksclub.github.io — PASS: articles=55, podcasts=205, transcripts=203, books=98, images=815, baseline_images=807
• git diff --check — PASS.

No candidate files drifted during testing. No files were staged or committed, and no push, AWS, deploy, or other lifecycle state change was performed.

[alexeygrigorev]

Product-manager acceptance — ACCEPT

I accept the frozen issue #3 candidate at baseline b9a40ba974fdef67ee3a2a70f114734f2581033c and content-set fingerprint cbfa4ba8c3257f86e31e2d16de025c27224565df2a15eba84cc6246c7e73e5ea, independently confirmed unchanged across exactly 28 candidate files.

I reviewed all 19 added descriptions. Each names the actual guest or episode subject and gives useful, episode-specific topics for a catalogue card. The copy is concise and concrete; it contains no placeholder, QA/source commentary, generic SEO language, or repeated filler. It directly fixes the blank-card problem and is compatible with website issue DataTalksClub/website#119, whose projection already consumes the source description field.

The editorial boundary is appropriate: exactly the previously blank 19 records change, the dated overlay permits only description, and it pins the baseline content commit, immutable legacy commit, unchanged migration digest, exact target set, description digests, complete target-file digests, and manifest bytes. Source verification removes only the exact declared descriptions before comparing all remaining migrated metadata. The immutable migration.yaml digest remains dd78a343a5f387a74afa914fc6c7e19790e202aa5d6fa9aba08bfda5995c5f86; the separate missing-media manifest remains 80d3014c47bf57de792473fc1da8f7569daeb55107688c3485153f773948d3aa; and the new overlay manifest is 63969508134e8b2ef3c8471e9c8dbccc96842fcfc25225fe02e1ed5a4f5926f6.

The independent tester PASS is accepted as the technical gate. No additional product change is authorized during commit. The engineer may commit these exact accepted bytes with Closes #3.

Residual integration risk is limited and non-blocking for this source change: website #119 must pin the resulting exact content commit and rebuild the podcast projection before visitors see the descriptions; frozen website #103 must refresh afterward. Neither integration should invent or rewrite this source-owned copy.

[alexeygrigorev]

Local commit handoff

The exact QA-passed and PM-accepted issue #3 candidate has been committed locally.

• Commit: e29f56ce70bd997171a78a9f0facc9354797f421
• Parent: b9a40ba974fdef67ee3a2a70f114734f2581033c
• Accepted content-set fingerprint: cbfa4ba8c3257f86e31e2d16de025c27224565df2a15eba84cc6246c7e73e5ea
• Committed path count: exactly 28
• Commit subject: Add complete podcast descriptions
• QA PASS: Add complete podcast descriptions with a strict editorial overlay #3 (comment)
• PM ACCEPT: Add complete podcast descriptions with a strict editorial overlay #3 (comment)

Before staging, the base, exact 28-path set, and accepted fingerprint were recomputed and matched. After commit, the content worktree is clean and main is ahead of origin/main by one commit. Nothing was pushed or amended.

Accepted verification remains: focused overlay tests 34 passed; make check passed with 121 tests; strict source verification passed with 55 articles, 205 podcasts, 203 transcripts, 98 books, 815 images, and 807 baseline images; lint, format, and diff checks passed. The external legacy checkout remains pinned at ee43d3fa0929faf691178d79f19528e6f15a83e5; its pre-existing unrelated uv.lock modification was not touched.

Website issue DataTalksClub/website#119 can pin the exact content commit after this local commit is pushed through the repository lifecycle.

[alexeygrigorev]

Deployment/source-publish verification: PASS

• Published main is exact commit e29f56ce70bd997171a78a9f0facc9354797f421.
• The sole workflow run for that SHA, Validate content #31365358459, completed successfully; its exact-SHA validate job and every validation, immutable-source/overlay verification, attestation, and artifact step passed.
• GitHub raw main exposes the new data-team-roles.yaml description byte-for-byte (f2743da3e17eabda4733d1573ef6f74c7836ad7bdc1c89a267814e49a5325741) and the editorial overlay byte-for-byte (63969508134e8b2ef3c8471e9c8dbccc96842fcfc25225fe02e1ed5a4f5926f6).

Source publication is complete and issue #3 can close.