D5.3a Prove the course source and policy contract for shared curriculum

Read DTC AGENTS/process/spec 04, docs/plan/STATUS.md, #436 and #414, then inspect courses/services/curriculum_source.py, existing source fixtures, the route contract, and the named shared-course files. Run the maintained DTC source-contract and route-baseline tests; completion requires tagged package fixtures, conversion and route/policy evidence, documented owners for gaps, and no production reader, schema, database, template, or UI changes.

Plan issue D5.3a, phase 5 of the community-base unification plan; child milestone of DTC #436.

Authority: D5.3a in the reviewed docs/plan/phase-5.md sequencing correction tracked by community-base #348. Implementation waits for that plan change and this milestone’s prerequisites. docs/plan/STATUS.md remains the source of truth.

Process and boundaries

DTC AGENTS.md, _docs/PROCESS.md, _docs/specs/ and coding-standard govern implementation, verification, independent QA and PM acceptance. Use an isolated worktree; preserve other sessions' work. Package changes must be tagged before site dependency adoption. No live source conversion, database reset or production operation is authorized by this issue. No visible UI change or feature removal is allowed.

Spec

Repository: DataTalksClub/website. Depends on: C5.4, C7.12b, C7.12d / community-base #366. Freeze required: no.

Goal: establish executable source and DTC policy expectations against a tagged shared package,
without adopting package storage, changing production readers or converting a live repository.

Read first

• DTC AGENTS/process/spec 04 and current source-format specs.
• #436, #414, courses/services/curriculum_source.py, existing source fixtures and route contract.
• Package FORMAT, public course parser, converter and #347 semantic regression evidence.
• courses/views/shared_course.py, curriculum_flow.py, course_context.py and the existing
  mapping document; read the affected contracts, do not reopen a broad inventory.

Steps

1. Inventory the exact public source commits and accepted source shapes for the six repositories,
   plus target-required content absent from them. Record dispositions as decisions still owned by
   D5.1; do not assume a source-only import recreates the public catalog.
2. Add bounded executable fixtures consuming public tagged converter/parser APIs. Establish
   expected source IDs, order, parentage, homework schemas/bindings, section/bonus metadata,
   project references, explicit ignores and route identities from source data. For an ordered
   cohort project flow that FORMAT section 3.8 cannot represent, prove a cohort-scoped refusal
   rather than treating a successful lossy conversion as a supported graph.
3. Compare supported legacy flat source expectations with converted graphs; include the newly
   supported mixed/YAML-homework shapes as synthetic contracts. Preserve module boundaries.
4. Record DTC policy mappings separately from generic structure: publication, archive behavior,
   cohort context, homework/project flow, module-local neighbors, access, asset links and URLs.
5. Name unresolved metadata/storage/behavior gaps explicitly; each required field/feature needs
   a known target owner before this milestone can be accepted. Do not introduce a runtime shim
   or duplicate parser to make the contract look complete.

Acceptance criteria

• Exact tagged package and source/fixture identities are recorded. No branch/path dependency
  is committed and DTC source guards pass.
• Flat and mixed source fixtures produce the expected authored identities/parentage/order;
  YAML homework/questions and explicit cohort bindings survive conversion without loss.
• Course source conversion is idempotent and obeys the accepted #347 partial-refusal policy. A test using a published immutable package release containing C7.12d/#366 proves that a cohort with ordered module/project flow is refused with its path and reason, retains its exact source bytes, and does not prevent unrelated valid cohort/source conversion. The test must fail against v0.5.20, whose successful report drops the project placement. Do not count refusal as project-flow adoption.
• Explicit expected DTC canonical slugs/routes and module-local navigation are recorded;
  package default prefix stripping or whole-course neighbors cannot silently replace them.
• The required public-content inventory and field/policy owner matrix are reviewable. Missing
  import paths/owners are unresolved blockers, not omissions from the contract.
• Required DTC verification passes; no production reader, schema, database, template or UI
  changes. This is source-contract proof, not imported-data/render/deployment equivalence.

Verification

• Run the selected source-contract and route-baseline tests through the maintained DTC test
  runner and all components selected by its verification plan; record exact counts and source
  identities. Validate converter output and the unsupported-flow refusal with the immutable tagged
  package, not a copied parser or local/path dependency. Record the tag and package identity.
• Complete independent QA and PM review under the DTC process. Package capability evidence is
  linked separately; imported site rows and deployed reader parity remain D5.1/D5.3b work.

Docs: DTC source-contract/mapping documentation and this plan's STATUS row. Test additions use
existing bounded fixture owners; no new general parser or generated production content files.

Browser and operations scenarios

No product page changes belong to this source-contract milestone. Characterize the existing flat route/policy baseline through its owning tests; the generated site verification plan still selects its required browser tier. No new screenshots or live source/database operations are required by a pure source-contract diff. Imported-data and deployed reader equivalence remain #414/#447.

Sequencing references

• Source/policy proof: D5.3a / #446.
• Storage and single source-writer activation: D5.1 / #414.
• Reader projection: D5.3b / #447.
• Full preservation acceptance: D5.3 / #436.
• Coordinated course cutover: D5.2 / #415.
• Plan sequencing correction: community-base #348; its phase-5/phase-7 and generated STATUS update must merge before these revised dependencies govern implementation. No milestone is completed by this grooming.
• Package conversion semantics: C7.12b / community-base #347; fail-closed ordered-flow correction: C7.12d / community-base #366. Package capability, donor compatibility and site adoption remain separate gates.
• D5.1/#414 retains the full feature gate: DTC-owned source, importer, durable target placement and reader projection must preserve project identity and its interleaved cohort order before shared storage or writer activation. C7.12d refusal prevents silent loss but is not feature adoption.