Make current-course lessons and homework a coherent reading flow

Outcome

Current shared-curriculum reading must behave as one coherent flow: module overview → ordered lessons → cohort-specific terminal homework. Shared lessons must render the structured video_url already imported into SharedLesson.video_url with the same safe, accessible behavior as cohort-bound Unit pages.

The motivating AI Dev Tools lesson currently exposes its recording as an ordinary body link even though video_url is the source contract. The shared importer persists that field, but shared_lesson.html does not render it. Shared lesson navigation is also lesson-only, the homework rail separator is visually broken, the homework is a terminal dead end, and “Open the cohort page →” is vague/redundant.

Normative references:

• zoomcamp-ops/docs/shared-curriculum-v2.md
• _docs/design/specs/unit-content-pipeline.md
• _docs/specs/04-courses-and-cohorts.md
• _docs/design/design-system.md
• _docs/architecture/database-only-content.md

Product decisions

• video_url frontmatter is the sole primary-recording field. A recording represented there is removed from body Markdown so it is not shown twice; ordinary topical/external video links remain prose links.
• Reuse one allowlisted video rendering contract for Unit and SharedLesson: responsive YouTube embed, descriptive title, lazy loading, strict referrer policy, fullscreen/allow policy, and a visible external “Watch on YouTube” fallback. Untrusted/invalid providers are never framed or linked from a corrupt DB value.
• Navigation is module-local and ends at the selected delivery’s terminal homework. It does not invent cross-module sequencing. When no cohort/homework is resolved, the flow ends at the last lesson and the existing delivery chooser explains how to select a delivery.
• Homework is a terminal step, not a dead end: it links back to its module and previous lesson, is marked current in the shared rail, and has no false “next” destination.

Scope

Source content

• Audit current schema-v2 lessons for primary recording body links. For AI Dev Tools, move all four current module recordings into each lesson’s video_url frontmatter and remove only the duplicate body recording line.
• Preserve lesson ids, paths, titles, navigation frontmatter, body content, and non-primary video links.
• Prepare and freeze the source changes as an uncommitted, issue-isolated candidate for tester and PM review. Commit/push the byte-identical accepted source tree and perform accepted-SHA sync/import only after both gates, following the lifecycle below.

Shared rendering and flow

• Give SharedLesson the safe video context and shared player/fallback presentation already expected of Unit.
• Recompose the module list/rail so lessons and terminal homework read as one ordered surface with continuous borders/separators; remove the curved/dropped dashed seam.
• Provide coherent controls for module overview, first/middle/last lesson, and terminal homework. Preserve ?cohort=<identifier> on every delivery-dependent link.
• Mark the current lesson/homework with aria-current="page"; expose ordered-list/list semantics and unambiguous previous/next/back labels.
• Replace the vague resolved-delivery link with a specific action such as “View 2026 cohort details” only when it adds value; omit it when the page already exposes the relevant delivery action. Preserve chooser and archive-warning states.

Non-goals

• Cross-module or cross-course next/previous navigation.
• Changing curriculum order, homework questions/scoring/deadlines, source routes/slugs, canonical URLs, enrollment resolution, archive behavior, or course content beyond duplicate primary-recording links.
• Supporting arbitrary iframe/video providers or extracting recordings heuristically from rendered Markdown.
• Hardcoding video/navigation/content in templates or Python outside database-owned fields.
• Combining #423 or #424 into the same commits/rollback unit.
• Redesigning legacy/module-format lesson pages beyond extracting a genuinely shared video primitive without visual regression.

Dependencies and coordination

• Website rendering and source content are implemented and tested together as uncommitted candidates. Issue closure requires an accepted AI Dev Tools source commit and website re-sync, but those release operations occur only after tester and PM gates.
• The AI Dev Tools working tree had unrelated changes during grooming. Use a clean pinned worktree or coordinate ownership; never stash or overwrite them.
• #423/#424 are related source changes, not blockers. Rebase/sequence focused commits and verify each SHA independently.

Lifecycle sequencing

1. Engineering prepares the website diff and the four source lesson edits without committing or pushing either repository, records the pinned source base plus candidate-tree digest, runs the local parser/import twice against that exact candidate, and freezes an issue-isolated handoff.
2. The independent tester verifies those uncommitted bytes: recomputed selective-CI plan, focused/full required gates, source overlay reconstruction, parser/import/idempotence, and browser/screenshots. An accepted source commit SHA, push, or deployed sync is not a prerequisite for the tester verdict.
3. PM performs product acceptance on the same frozen uncommitted candidate after tester PASS.
4. Only after both gates pass, the source owner creates and pushes a focused commit whose tree matches the tested candidate digest exactly. The accepted immutable source SHA is then synced/imported, replayed once more to prove no-op behavior, and its database provenance/render checked.
5. The website change is committed/merged/pushed under _docs/PROCESS.md; on-call observes required CI and the accepted-SHA content verification. The issue closes only after these post-gate release checks pass.

+Post-gate source commit/push/sync criteria are operations owned after tester/PM acceptance, not pending/skipped components in a tester-final report. Any content or code change beyond attaching the tested bytes to a commit invalidates the gates and returns the work to engineering/tester/PM.

Acceptance criteria

• Every current AI Dev Tools lesson with a primary recording declares an HTTPS YouTube video_url; the matching body recording link is absent, and non-primary links/content are unchanged.
• Before tester review, source repository checks and website parser/import tests accept the uncommitted frontmatter together with existing prev_url/next_url; importing the pinned candidate tree twice persists the exact URLs in SharedLesson.video_url and the second local import is a no-op.
• After tester PASS and PM acceptance, the four source edits are committed/pushed as the byte-identical tested tree. Syncing that immutable accepted SHA persists matching provenance and URLs; a second accepted-SHA sync is a no-op. This post-gate operations criterion is not a precondition of the tester verdict.
• A shared lesson with an allowed YouTube URL renders one responsive 16:9 player plus a visible external fallback link, with descriptive accessible title, lazy loading, strict referrer policy, allow/fullscreen attributes, and no duplicate recording link in the article.
• A lesson without video_url renders no player/fallback. An invalid or non-allowlisted stored URL renders neither an iframe nor an unsafe fallback and does not break the page.
• Cohort-bound Unit and shared SharedLesson use the same video safety/presentation contract and pass parity tests; existing Unit behavior has no visual or security regression.
• Module overview presents ordered lessons and, when a delivery with terminal homework is resolved, homework as the final distinct step. Borders/separators remain continuous at every radius/theme/width.
• First lesson offers module context and next lesson; middle lessons offer previous/next; last lesson offers previous and terminal homework when available; terminal homework offers previous lesson and back to module, is visibly/semantically terminal, and has no next control.
• When no delivery/homework is resolved, no homework link is fabricated and the existing chooser remains. Archive context continues to warn/link to the archive rather than attaching current homework.
• All module/lesson/homework rail and flow links retain the valid ?cohort= context; canonical URLs remain cohort-query-free. Invalid context keeps existing safe resolution behavior.
• Current lesson or homework is visibly distinct and carries aria-current="page"; navigation has an accessible name, semantic ordered/list structure, visible focus, ≥44 CSS px targets, and Enter activation.
• Resolved-delivery copy names the cohort and destination/purpose or is omitted when redundant. “Open the cohort page →” no longer appears as a vague standalone action; chooser/archive states remain clear.
• At 1440, 768, 390, and 320 CSS px in light/dark mode, video, article, rail, homework seam, and controls have no overlap or document-level overflow. Reduced-motion behavior and focus remain intact.
• Shared route/canonical/cache behavior, lesson sanitization, imported assets/code links, homework form state/submission, and legacy course pages continue to pass.

Verification scenarios

Repository/service

1. Run the AI Dev Tools source checker, proving frontmatter/body-link parity and unchanged lesson navigation/content outside the four recording lines.
2. Run shared curriculum parser/import, shared route, Unit video, homework context/design, URL/context, cache, sanitization, and accessibility tests.
3. Test allowed YouTube watch/short URLs, no video, malformed URL, and non-allowlisted provider; assert unsafe values never reach iframe/link markup.
4. Before gates, import the pinned uncommitted candidate tree twice and compare SharedLesson identities, video URLs and rendered body; record its tree digest.
5. After gates, prove the pushed source commit tree equals that tested digest, sync the accepted SHA twice, and compare identities, URLs, body and persisted provenance.

Browser

1. With ?cohort=2026, traverse module → first → middle → last lesson → homework using only page controls; then traverse backward. Verify query preservation, labels, current state, and browser history.
2. Repeat anonymously without a resolved cohort and with archive context; confirm chooser/archive behavior and absence of fabricated homework.
3. Inspect the player and external fallback with keyboard and a screen reader; confirm one recording presentation and no body duplicate.
4. Capture module, first/middle/last lesson, and homework at 1440/768/390/320 in both themes, including focus. Verify document.documentElement.scrollWidth === document.documentElement.clientWidth.
5. Regression-check one cohort-bound Unit video and one legacy homework page.

Evidence to attach

• Pre-gate AI Dev Tools base/candidate-tree digest and diff summary; after gates, the matching accepted source SHA plus sync provenance/replay output.
• Focused test results.
• Desktop/mobile light/dark screenshots of the complete flow, plus video safety/fallback evidence.

Start with shared_lesson.html, SharedLesson.video_url, the existing Unit video presentation, and the shared-curriculum parser/import and route, accessibility, URL/context, cache, sanitization, and homework tests named in the issue. Trace the module rail through first, middle, last, and terminal-homework states, including cohort and archive contexts. Done means the focused tests and browser scenarios pass without regressions, with the required source-tree and sync evidence attached.