Add the term, equation, value, and misconception registries (src/model/course/glossary.rs) and the new optional fields on objectives, targets, lectures, readings, bank options, and policy. Load registry entries from objective files, glossary.yaml, and course.yaml, with one definition site per id as for every other registry. Port every edit in docs/design/2.1/build_schemas.py into the hand-written schema builders, add glossary.schema.json, and test the generated schemas against the targets; the only differences are two 2.0 spellings the code already had. The 2.0 example fragments load and validate unchanged. The 2.1 example bank gains `status: draft`, which every coursebank item requires. tests/docs.rs skips docs/design/, which holds design records rather than guide pages. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
8.7 KiB
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, sodiff -r schemas-original schemasshows every change.examples/v20/: 2.0 fragments that must still validate unchanged.examples/migration/: a 1.0terms.yamlandvalues.yamland theglossary.yamlthe 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 --selftestbreaks the example once per rule and shows each rule firing; that list is your test plan.--page l09prints the lecture-page content the renderer should produce, saved asexamples/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
- 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_versionbecomes 2.1. - 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
descriptionstrings, so carry the wording fromschemas/over. Then diff the generated schemas againstdocs/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 (thepropertyNamesid patterns are the likely case), enforce it in the validator and say so. List every remaining difference, with the reason, in your final report. - 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. - 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. - Student-facing versus instructor-facing.
authoring,notes_private,evidence,conflicts, andstatusmust 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. - 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.yamlfragment 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.
- 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, andcourse.yaml. Regenerate the schemas and diff them as in rule 2. Done whenexamples/v20/andexamples/v21/both load, and the existing test suite passes. - 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.
- Lint. W2101 to W2111, I2112, I2113. Done when
coursebank linton the example reports exactly W2101 forval-per-decade(migrated, not yet linked to a target) and I2113 (two proposed entries), and each lint has a test. - 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 ofexamples/v21/lecture-page-preview.md, and the rule-5 test passes. Send me a screenshot or the rendered HTML of the example lecture page. - Migration.
coursebank migrate glossary --terms terms.yaml --values values.yamlwritingglossary.yaml, with the report the specification describes (renamed ids; terms and values whose oldfirstorlecturesdiffer from the derived ones; entries no target lists yet). Done when migratingexamples/migration/terms.yamlandvalues.yamlreproducesexamples/migration/glossary.expected.yaml(field order aside) with the report its header comment describes, and migrating twice is a no-op. (examples/v21/glossary.yamlis that output after a person linked the value to its term.) - 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.