# Prompt for a new Claude Code session in the coursebank repository How to use it: copy this whole folder into the coursebank repository as `docs/design/2.1/` (or anywhere, and change the path below), open Claude Code at the repository root, and paste everything under the line. Claude Code stops once, after it has read the code and written a plan, and waits for your go-ahead. --- You are working in the coursebank repository, the Rust tool that manages my course registry (course, lectures, objectives, targets, references, stimuli), item banks, assessments, measurements, and calibration. I want coursebank 2.1, and everything you need is in `docs/design/2.1/`: - `SCHEMA-CHANGES.md`: the specification. What changes, why, the validation rules, the lints, the derived data, the rendering, the migration. Read it first and treat it as authoritative. - `schemas/`: the target JSON Schemas, one per file, written as coursebank would generate them. `schemas-original/` holds the 2.0 schemas they were built from, so `diff -r schemas-original schemas` shows every change. - `examples/v20/`: 2.0 fragments that must still validate unchanged. `examples/migration/`: a 1.0 `terms.yaml` and `values.yaml` and the `glossary.yaml` the migration should write. `examples/v21/`: a small course (course.yaml, references.yaml, glossary.yaml, two objective files, one lecture, one bank) that uses every new field and must validate with no errors. - `prototype/check21.py`: a Python sketch of every new error, lint, and lecture-page derivation. `python3 prototype/check21.py examples/v21 --selftest` breaks the example once per rule and shows each rule firing; that list is your test plan. `--page l09` prints the lecture-page content the renderer should produce, saved as `examples/v21/lecture-page-preview.md`. ## Why Read `SCHEMA-CHANGES.md` "Why". In one paragraph: a lecture today is only its objectives, targets, and readings; its terms, numbers, equations, and common mistakes live in side files (`terms.yaml`, `values.yaml`) or in each pipeline's notes, so the lecture page shows students half of what they study from and the slide, brief, and item pipelines keep drifting copies. 2.1 makes those first-class registries, keyed by id and defined once, that targets point at; gives objectives, targets, and lectures short student-facing text; keeps the item-writing judgments the objectives prompt produces (the ceiling evidence, stem constraints, supplied data) on the target instead of losing them in chat; moves each course's exam conditions, blueprints, and level names into `policy` so the tools stop assuming one course; and lets a bank option name the misconception it encodes so reports can group misses by it. ## Ground rules 1. **Additive and backward compatible.** No field renamed or removed, no new required field on an existing object. Every course that validates under 2.0 validates under 2.1 with no new errors. `schema_version` becomes 2.1. 2. **The schemas are generated; change the Rust.** Find how the JSON Schemas are produced (schemars or similar), change the types and their doc comments, and regenerate. The doc comments become the `description` strings, so carry the wording from `schemas/` over. Then diff the generated schemas against `docs/design/2.1/schemas/`: field names, types, enums, required lists, `additionalProperties: false`, and descriptions should match. Ordering and formatting do not matter. Where the generator cannot express something (the `propertyNames` id patterns are the likely case), enforce it in the validator and say so. List every remaining difference, with the reason, in your final report. 3. **Ids are join keys.** Never rename an existing id or field. The new prefixes are `term-`, `eq-`, `val-`, `mis-`, and ids are unique across all registries. 4. **Follow the repository's conventions** for module layout, error and lint codes, messages, tests, documentation, and the changelog. The prototype's codes (E2101 to E2108, W2101 to W2111, I2112, I2113) are placeholders: map each onto the repository's scheme and keep the mapping in `docs/design/2.1/CODES.md`. 5. **Student-facing versus instructor-facing.** `authoring`, `notes_private`, `evidence`, `conflicts`, and `status` must never appear in a student page, a student report, or a student-visible export (Canvas, solutions). Add a test that renders the example and asserts none of their text is present. 6. **Port semantics, not Python.** The prototype is a readable sketch. Where coursebank already has a better mechanism (its own loader, its own markup renderer, its own teaching order), use it and make the behaviour match the specification. ## Phase 0: read, then plan, then stop Before changing anything, find out and write down in `docs/design/2.1/PLAN.md`: - how the schemas are generated, and the command that regenerates them; - how fragments are discovered and merged (which directories and files the loader reads, and how a duplicate id is reported), and what it takes to load the new `glossary.yaml` fragment and the new registries from objective fragments; - where validation, lint, and rendering live, and how lint codes and error codes are numbered; - how teaching order is computed, and how the lecture page and student reports are rendered today (templates, markup handling of `{t-...}` braces and `$...$` math); - the test layout, and the fixtures that represent a real course; - any place where the specification conflicts with how the code works, with your proposed resolution; - the phases below, adjusted to what you found, each with the files it touches. Then **stop and wait for me**. Do not start Phase 1 until I reply. ## Phases (after I approve the plan) Work on a branch named `schema-2.1`. Commit at the end of each phase with a message that says what the phase did. Do not push, open a pull request, or merge unless I ask. 1. **Types and schemas.** The four registries and their entry types; the new fields on objectives, targets, lectures, readings, bank options, and policy; the glossary fragment type; the loader reading glossary entries from objective fragments, `glossary.yaml`, and `course.yaml`. Regenerate the schemas and diff them as in rule 2. Done when `examples/v20/` and `examples/v21/` both load, and the existing test suite passes. 2. **Validation.** E2101 to E2108 as specified, including the extension of the duplicate-id rule across registries and the brace-reference resolution in every student-facing prose field. Done when the example validates with no errors and each error has a test built from the prototype's self-test case. 3. **Lint.** W2101 to W2111, I2112, I2113. Done when `coursebank lint` on the example reports exactly W2101 for `val-per-decade` (migrated, not yet linked to a target) and I2113 (two proposed entries), and each lint has a test. 4. **Derived data and rendering.** A glossary entry's first lecture; new versus earlier terms per lecture; the lecture page sections in the order the specification gives, with ceilings labelled by `policy.levels`; the course glossary page; brace references rendered as specified; student reports with the target explanation and the misconception correction, grouping misses by misconception. Done when a snapshot test of the example's lecture page has the content and order of `examples/v21/lecture-page-preview.md`, and the rule-5 test passes. Send me a screenshot or the rendered HTML of the example lecture page. 5. **Migration.** `coursebank migrate glossary --terms terms.yaml --values values.yaml` writing `glossary.yaml`, with the report the specification describes (renamed ids; terms and values whose old `first` or `lectures` differ from the derived ones; entries no target lists yet). Done when migrating `examples/migration/terms.yaml` and `values.yaml` reproduces `examples/migration/glossary.expected.yaml` (field order aside) with the report its header comment describes, and migrating twice is a no-op. (`examples/v21/glossary.yaml` is that output after a person linked the value to its term.) 6. **Documentation.** The authoring docs for the new registries and fields (with the example), the brace-reference table, the lint and error codes, the migration command, and the changelog entry for 2.1. ## Final report When the phases are done, give me: what changed, by phase and file; the code mapping; every difference between the generated and the target schemas, with the reason; anything in the specification you could not do, or did differently, and why; how to run the migration on my course; and anything you think should change in the specification itself. Keep it short and put the details in `docs/design/2.1/REPORT.md`. If anything in the specification is ambiguous in a way that changes behaviour, ask me rather than guess. If it is ambiguous only in a way that does not change behaviour, choose, and list the choice in the report.