From 268b97b59da311827b31d276a2c2bd9857ae6959 Mon Sep 17 00:00:00 2001 From: Anthony Giacalone Date: Sun, 28 Jun 2026 12:24:57 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20add=20grading-handoff.md=20=E2=80=94=20?= =?UTF-8?q?signpost=20to=20where=20grading=20lives?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Scriptorium authors content and has no grader. Two of its artifacts — the Classroom README (lab/programming variant) and the question bank — hand off to the grading side of the suite. This signpost doc points a content author to where the grading info lives rather than re-explaining it: lectern's grading-types.md (pick a type) + assignment-authoring.md, oracle's grading-model.md (mechanics), and reg-exam-build/verify for exams from the bank. Linked from the README suite section and the SKILL.md exam/README callouts. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_015cY2osrcunEXb5a8xtTy2V --- CHANGELOG.md | 9 ++++++ README.md | 3 +- SKILL.md | 6 ++++ docs/grading-handoff.md | 64 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 docs/grading-handoff.md diff --git a/CHANGELOG.md b/CHANGELOG.md index edd4c52..85bdd4f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,15 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## [Unreleased] +### Added +- **`docs/grading-handoff.md` — signpost to where grading lives.** Scriptorium authors + content and has no grader; two of its artifacts (the Classroom README lab/programming + variant, and the question bank) hand off to the grading side of the suite. The new doc + points content authors to where the grading info lives — lectern's `docs/grading-types.md` + (pick a grading type) and `docs/assignment-authoring.md`, and oracle's `docs/grading-model.md` + (engine mechanics) — plus `reg-exam-build`/`reg-exam-verify` for exams from the bank. Linked + from the README suite section and the SKILL.md exam/README callouts. + ### Fixed - **PDF/UA-1 metadata remediation (ADA Title II, issue #7).** Both shared preambles now declare `\DocumentMetadata{…pdfstandard=ua-1,pdfversion=1.7,…}` (writes the PDF/UA-1 identifier into XMP and diff --git a/README.md b/README.md index e506a2a..4d52419 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,8 @@ ways: driven by an AI agent (Claude Code skill) *or* run directly by a human via | **[Scriptorium](https://github.com/agiacalone/scriptorium)** — the workshop | Course **content** — lecture notes, Cornell handouts, quizzes, slides, question banks. | `agiacalone/scriptorium` | | **[Oracle](https://github.com/agiacalone/oracle)** *(private)* — the secret box | **Grading** — a verify-by-proof oracle service + a sandboxed code-runner (gradebox). | `agiacalone/oracle` *(private — licensed)* | -*You are here: **Scriptorium**.* +*You are here: **Scriptorium**.* Authored a lab or a question bank and wondering how it gets graded? +See [`docs/grading-handoff.md`](docs/grading-handoff.md) — a signpost to where the grading info lives. > **Suite licensing.** Lectern and Scriptorium are open source ([MIT](LICENSE)). **Oracle** — the grading engine — is **licensed, not open**: a **source-available license** (PolyForm Strict 1.0.0), private repo, source provided on licensing. Accredited **educational institutions can license it for free**; commercial and other use is by arrangement. Either way, **contact the author for a license** — [@agiacalone](https://github.com/agiacalone). diff --git a/SKILL.md b/SKILL.md index 51e5443..6662670 100644 --- a/SKILL.md +++ b/SKILL.md @@ -80,6 +80,12 @@ PDF via `pdflatex`. Slides emit Slidev markdown (`.md`) — no PDF export. The > serials, emits a register) and verify with `reg-exam-verify`. See > [[notes/exam-tex-doctrine]]. This skill no longer generates exams. +> **Grading lives in the other suite repos.** When you author a Classroom README +> (lab/programming variant) or a question bank, see [`docs/grading-handoff.md`](docs/grading-handoff.md) +> — a signpost to where the grading info lives: lectern's `docs/grading-types.md` +> (pick a grading type) and `docs/assignment-authoring.md`, oracle's `docs/grading-model.md` +> (engine mechanics). Scriptorium authors content; it has no grader. + **Default (generate everything — single session):** > "Generate lecture materials for [TOPIC] in [COURSE]. Cover: [KEY CONCEPTS]. Case studies: [EXAMPLES]. ~[N] minutes." diff --git a/docs/grading-handoff.md b/docs/grading-handoff.md new file mode 100644 index 0000000..168db86 --- /dev/null +++ b/docs/grading-handoff.md @@ -0,0 +1,64 @@ +# Where Authored Content Goes to Be Graded + +Scriptorium is the **content workshop** of the Lectern · Scriptorium · Oracle suite. It *authors* +materials; it does **not** grade. This doc is a signpost: two of the artifacts Scriptorium produces +hand off to the grading side of the suite, and rather than re-explain grading here, this points you +to where the right information lives — so you don't go hunting. + +``` + Scriptorium Lectern Oracle + (content) → (administration) → (grading) + ───────── ─────────────── ───────── + Classroom README picks the grading type, runs the grader: + question bank assembles exams verify-by-proof + gradebox +``` + +You are in the **content** box. The grading docs live in the other two repos. + +--- + +## Handoff 1 — a Classroom README (lab/programming variant) → how it gets graded + +When you generate a GitHub Classroom `readme` in its **lab/programming variant** ("build something, +with verifiable requirements"), you've authored a *student-facing assignment*. *How* that assignment +is graded — and *which* grading mechanism fits it — is documented on the lectern/oracle side: + +- **Pick a grading type → lectern [`docs/grading-types.md`](https://github.com/agiacalone/lectern/blob/main/docs/grading-types.md).** + A plain-language, use-case guide (no security/OS background assumed): manual rubric · oracle + verify-by-proof · gradebox (code-running / exploit-verification / binary-artifact) · hybrid. Start here. +- **Author the full graders' contract → lectern [`docs/assignment-authoring.md`](https://github.com/agiacalone/lectern/blob/main/docs/assignment-authoring.md).** + Fixed deliverable paths, the rubric, and academic-integrity patterns (forcing-functions/canaries, + per-student individualization). +- **The engine mechanics → oracle [`docs/grading-model.md`](https://github.com/agiacalone/oracle/blob/main/docs/grading-model.md).** + What each grading type *is*, with the deep specialist docs linked from there. + +> The *reading-assignment* README variant (answer questions from a chapter) is typically hand- or +> rubric-graded — no autograder needed. The handoff above is for the lab/programming variant. + +## Handoff 2 — a question bank → exams + +The append-only `*_question_bank.md` you maintain here is the **source exam assembly draws from**. +Exams are controlled documents built by **lectern**, not Scriptorium: + +- **lectern `reg-exam-build`** assembles an exam from the bank with per-student serials + a register, + and **`reg-exam-verify`** checks any paper back to one student/form. See lectern's exam-build docs + and `notes/exam-tex-doctrine`. + +(The `code`-type questions in the bank are *interpretation* questions for exams — not the same thing +as a runnable lab. A runnable lab is authored as a Classroom README and graded via Handoff 1.) + +--- + +## What stays here vs. what doesn't + +- **Scriptorium owns the content** — the `_lecture_main.md` source and everything projected from it, + including the Classroom README and the question bank. Keep authoring those here. +- **Grading lives in the grading repos** — selection and mechanics in lectern + oracle (the links + above). Scriptorium has no grader and never runs student code. + +| If you want to… | Go to | +|---|---| +| Choose how a lab gets graded | lectern `docs/grading-types.md` | +| Author an assignment's full graders' contract | lectern `docs/assignment-authoring.md` | +| Understand a grading type's mechanics | oracle `docs/grading-model.md` | +| Build/verify an exam from the question bank | lectern `reg-exam-build` / `reg-exam-verify` |