Instructor Handover Report

Date: 2026-09-18 · Status: complete and validated · Audience: the course instructor taking ownership of this repository.

This report is the one-page map of what you have been handed: what exists, how it is built, what the automation does and does not do, and what remains for you to do manually. Detailed teaching advice lives in the Instructor Guide; operational detail in Deployment.

1 · Repository structure

README.md                  course front page (setup, preview, publication)
CONTRIBUTING.md            content conventions and validation rules
LICENSE                    MIT (tooling) + CC BY 4.0 (teaching content)
docs/                      handbook: overview, outcomes, outline, methodology,
                           assessment, instructor guide, resources, glossary,
                           FAQ, deployment, handover report (this file),
                           case review, topic-coverage heatmap (CSV/SVG),
                           final-audit-report.md
docs/instructor-reports/   instructor-only audits (never published)
lectures/lecture-01..32/   per lecture: plan.md (student-safe),
                           notes.md, examples.md, quiz.md (student-facing),
                           teaching-notes.md (instructor-only)
case-studies/student/      cs-001 … cs-144 — projected in class
case-studies/instructor/   matching full solutions — never published
case-studies/CATALOG.md    generated index of all 144 cases
labs/                      12 labs + keys/ (instructor-only)
activities/                5 non-graded activities + facilitation map
quizzes/                   8 quizzes + keys/ (instructor-only answer keys)
assignments/               6 assignments + rubrics + marking keys
projects/                  3 term projects + proposal template + progress
                           checklist + final rubric
resources/                 python-setup.md, pseudocode-style.md
slides/                    deck sources + generated HTML decks (slides/decks/)
scripts/                   build + validation tooling (stdlib-only Python)
tests/                     pytest suite for the tooling
.github/workflows/         validate.yml (CI) + pages.yml (single deployer)

2 · Technology stack

Content: plain Markdown; cases and lectures follow a fixed section contract enforced by scripts/validate.py.
Tooling: Python 3 (developed and tested on 3.12), standard library only — no runtime dependencies. pytest==8.3.4 is the single dev dependency (requirements-dev.txt).
Website: dependency-free static HTML + one stylesheet generated by scripts/build_site.py; browser-side search over pages.json.
Slides: generated HTML decks from lecture sources via scripts/gen_slides.py (no proprietary application needed).
CI/CD: GitHub Actions; one validation workflow, one deployment workflow (upload-pages-artifact + deploy-pages).

3 · Commands

# --- validation (run after any content change) ---
python scripts/validate.py         # structure, links, case pairing, metadata
python -m pytest tests/ -q         # tooling tests
python scripts/qa_report.py        # full suite + qa-report.md

# --- regeneration (only when content changed) ---
python scripts/generate_catalog.py # case catalog from metadata
python scripts/gen_slides.py       # slide decks from lecture sources

# --- builds ---
python scripts/build_site.py       # public student site → site/
python scripts/build_instructor.py # everything → public_instructor/ (local)

# --- preview ---
python -m http.server 8000 --directory site
# open http://localhost:8000/   (Ctrl+C to stop)

# --- audit of the built site (optional) ---
python scripts/audit_site.py       # pages, references, broken links

Regenerating overwrites generated files; hand-edit sources, not output.

4 · GitHub Pages setup requirements

One manual setting, then everything is automatic:

Repository Settings → Pages → Build and deployment → Source: GitHub Actions. The deployment workflow does not run correctly until this is chosen.
Push to main (or use Run workflow in the Actions tab). The workflow validates → regenerates → builds → leak-checks → uploads → deploys; every stage gates the next, so a failing validation blocks publication.
First deployment creates the github-pages environment automatically. No secrets, no branch selection, no other settings.

See Deployment for the gate table and local reproduction of the full pipeline.

5 · Instructor-only content handling

What is instructor-only: case-studies/instructor/, every keys/ directory (quizzes, labs), assignment marking keys, lecture teaching-notes.md, the activities facilitation map, and docs/instructor-reports/ (they quote reference output — answers in disguise).

How separation is enforced:

scripts/build_site.py excludes all of these by path and runs a leak scan over its own output; any hit fails the build, and the deployment workflow re-verifies the artifact before upload.
scripts/build_instructor.py produces the complete public_instructor/ build for your own devices; that directory is gitignored and is never run or uploaded by the deployment workflow.
scripts/validate.py verifies the 144 student/instructor pairs and the lecture↔case mappings on every run.

Your responsibility: never deploy public_instructor/ anywhere public, and distribute solutions through your institution's access-controlled system (LMS, shared drive). A private-looking folder on a public host is not protection — build-time exclusion is the control that matters. Full policy: Instructor Guide → Instructor-only materials.

6 · Known limitations

Line endings: repository files use CRLF; Python reads them transparently, but git diff output may look noisy across platforms unless you set a .gitattributes policy (see remaining tasks).
Case-count notes, not warnings: fourteen lectures carry more than the base four cases (the applied additions cs-129–cs-144). The validator reports this as informational by design — not a defect.
Slides are generated: hand-editing slides/decks/*.html is lost on regeneration; edit lecture sources and re-run gen_slides.py.
Search is client-side: search.html is excellent for a course corpus but is not a server-side engine; fine at this scale.
No gradebook: the assessment plan defines weights and rubrics; marks live in your institution's system, not here.
Determinism of randomness: the two simulation cases use fixed seeds; if you replace data, keep the seeds so expected outputs stay true.
Python version: tooling targets 3.10+ (validated on 3.12); lecture Python is deliberately conservative (no 3.11+-only syntax).

7 · Remaining manual tasks for the instructor

#	Task	When
1	Review the material. Skim `docs/index.md`, the Course Outline, and a few cases end-to-end (one Beginner, one Expert). Content is validated, but you own the pedagogy.	Before first use
2	Choose the one-time Pages setting (Settings → Pages → Source: `GitHub Actions`).	Before first publish
3	Commit and push manually. Nothing in this repo commits or pushes by itself — that is deliberate. The suggested first commit is in the repository README; publication steps are in Deployment.	At your pace
4	Adapt institutional details: grade weights (defaults in the Assessment Plan), quiz dates, lab scheduling to your calendar.	Semester prep
5	Build and distribute the instructor pack (`python scripts/build_instructor.py` → `public_instructor/`), then load it on your teaching laptop.	Semester prep
6	Optional: add a `.gitattributes` (e.g. `* text=auto`) if you want to normalise line endings before the first push.	Optional, before first push
7	After the semester: follow the end-of-semester checklist in the Instructor Guide and feed timing adjustments back into the plans.	End of term

Sign-off

At handover: 32 lectures (2 hours each, 64 contact hours), 144 case studies with verified instructor solutions (33 Beginner / 37 Foundational / 38 Intermediate / 23 Advanced / 13 Expert), 12 labs, 8 quizzes, 6 assignments, 3 projects, 5 activities, generated catalog/heatmap/slides, and a leak-free public build — all passing scripts/validate.py, the pytest suite, and the site audit at the time of handover.