Unit 3 lesson-spec authoring contract (binding, 2026-08-06)

You are writing lesson specifications for one instructional sequence of AP Chemistry Unit 3 (Properties of Substances and Mixtures, register prefix PSM). Your output is a single JSON file. Every word you write in text, stem, fb, good, wrong, steps, checklist, and alt fields is student-visible and binding — it ships verbatim.

Sources you must read first

Your sequence's atoms in ../unit3_design_v1.json: each atom's statement is the binding behaviour; its bracketed example fixes scope. scopeDecisions, explicitExclusions, atomisationExceptions, whatWhyPairs/whatWhyExceptions, and canonicalLexicon bind you.
u2_calibration_seeds.json in this directory — the two James-approved Unit 2 pilot lessons in this schema. They are the gold standard for tone, pacing, and feedback style. Calibrate against them. (They are Unit 2 content — never copy their chemistry into Unit 3 lessons.)
schema_seeds.json — Unit 3's verified pilot lessons (PSM-070, PSM-084), converted from the twice-blind-reviewed pilot specs. If your sequence contains one of these atoms, DO NOT author it — the seed wins.
../../FORMAT_ROLLOUT_PROMPT_20260805.md — the line-by-line format and the nine wording rules.
../../Content_Quality_Feedback_Master_Log.md — sections dated 2026-07-31 through 2026-08-06. The 2026-08-06 section carries three rulings this contract already encodes below.

Output schema

Write specs/<SEQ-ID>.json (e.g. specs/U3-S01.json):

{"sequence":"U3-S01","lessons":[
  {"atom":"PSM-001","title":"Student-facing title","outcome":"Outcome line (verb-first, plain)",
   "flow":[
     {"t":"part","title":"Part title (sentence case; no 'know'; no quantity symbols if avoidable)"},
     {"t":"idea","text":"One idea. One sentence per reveal line (provisional James rule — comply).","fig":{...optional figure spec...}},
     {"t":"note","text":"What the student is expected to be able to do (from the atom statement, plain English)."},
     {"t":"we","q":"Q: The question this worked example answers?","steps":[
        {"label":"Write down the values from the question","lines":[["P = 2.00 atm","T is constant"]]},
        {"label":"Write down the equation","lines":[["PV = nRT",""]]},
        {"label":"Make V the subject","lines":[["V = nRT/P",""]]},
        {"label":"Substitute in the values, and calculate","lines":[["V = (1.00 × 0.08206 × 300)/2.00",""],["V = 12.3 L",""]]}]},
     {"t":"nq","q":{"stem":"...","key":"400","unit":"m/s","fig":{...},
        "good":"Correct. <why>","wrong":{"200":"<names the actual mistake>: ..."},
        "signRetry":{...only when the key is signed...},
        "revealSteps":[["Write down the values from the question",["..."]],
                       ["Write down the equation",["..."]],
                       ["Substitute in the values, and calculate",["...","..."]]]}},
     {"t":"mcq","q":{"stem":"...","fig":{...},"opts":["...","...","...","..."],"ok":1,
        "fb":["This option is wrong — you ...","Correct. ...","This option is wrong — you ...","This option is wrong — you ..."]}},
     {"t":"draw","q":{"stem":"Take a pen and paper and draw ... When you are done, select Check to compare your drawing with the model answer.",
        "modelFig":{...},"checklist":["Your drawing shows ...","...","..."]}}
   ]}
]}

Figure specs (`fig` objects — deterministic renders, resolved at build time)

Every fig needs "alt". The Unit 2 families remain available exactly as documented in ../../unit2_build/course/SPEC_CONTRACT.md (lewis, resonance, pecurve, anneq, particulate, alloy, vsepr, orbital, dipole incl. diatomic + arrows mask, datatable, barcompare, periodictable, continuum, touchingions, layershift, atompair, and the pecurve/particulate flaw params). Unit 3's new families are documented in FIGLIB_U3.md in this directory — read it in full; those schemas are as binding as this file. TODO escape hatch unchanged: {"kind":"TODO", "desc":"exact description"} — use sparingly and report it.

Binding rules (violations fail validation or blind review)

One atom per lesson. Teach only your atom; recap prerequisites in one line each, "You've already seen…" (never "know", including part titles). Never use a term taught by a LATER atom — the validator enforces the register's glossaryAudit against teaching order. Unit-wide bans: "equilibrium" (except the Unit 2 term "equilibrium bond length"; vapor pressure is worded as equal rates of escape and return), all excluded content (phase diagrams, colligative, molality, percent by mass/volume, M₁V₁ dilution routine, van der Waals equation, effusion, Graham's law, rms/speed formulas, heating curves, Rf values, solubility rules tables).
Unit 2 mechanism atoms are RETRIEVAL, not reteaching. The solid-property reason content in S03/S06 consumes CSP-032A…CSP-039A: one "You've already seen…" recap line each (with the representation shown if a representation is recapped) — never a re-derivation. The IMF-specific mechanisms (LDF, dipole-dipole, H-bonding, ion-dipole, dipole-induced dipole) are Unit 3's own fresh teaching.
Canonical mechanism sentences verbatim (register canonicalLexicon, all James-approved): MECH-LDF (PSM-002), MECH-IMF-ESCAPE (PSM-030/031/037), MECH-LIKE-DISSOLVES (PSM-111), MECH-KMT-TEMP (PSM-068), MECH-GAS-COLLISION (PSM-027/063/073/077), plus the Unit 1/2 Coulomb pair (MECH-COULOMB-CHARGE / MECH-COULOMB-DISTANCE) wherever those mechanisms recur.
Coulomb convention (James 2026-08-06): FORCE form only. Where an equation or exponent is cited, it is F ∝ q₁q₂/r² (the CED EK 1.5.A.2 / equation-sheet form). Prefer qualitative wording ("as the particles get closer, the attraction between them gets stronger") wherever no equation is needed. Never assert an energy-form 1/r relationship.
Headache before aspirin (James 2026-08-05): any lesson introducing a genuinely NEW quantity or concept opens with a concrete felt problem (an object the student can picture, a question they cannot yet answer); the concept arrives as the answer — never definition-first. Such openings get a simple concrete deterministic image matching the prose values exactly. Lessons extending an already-motivated concept need no fresh headache; lessons open directly either way (no scene-setting).
Show, then test. 2–4 checks per lesson, after the teaching. First check mirrors the instruction (fresh example preferred); later checks transfer to new species/cases.
Interaction matches behaviour. Calculate → nq. The Unit 3 engine accepts decimal keys and scientific-notation entry (4.00e2, 4.00 × 10²): "key" is the displayed answer string, optional "tol" is the absolute tolerance. Sig-fig enforcement rides on the key's format: a key with an explicit decimal ("49.2", "4.10") enforces its sig-fig count (right-value/wrong-format entries get a no-penalty retry); a trailing-zero integer key ("400") is graded on value only (rule 6.4 ambiguity non-scope) — write the key with a decimal when you want enforcement. Stems state the required precision; givens in stems are treated as exact by convention (pending James's ruling, 2026-08-10). Still choose value sets for exact arithmetic. Classify/ identify/rank/evaluate → mcq. Draw/Sketch (PSM-033, 061, 071, 072, 082, 102) → at least one draw production item (pen-and-paper + model answer + feature checklist), optionally plus an image-option mcq using figure flaw/variant params.
Feedback contracts. Every mcq option has its own feedback; wrong-option feedback names the actual mistake ("This option is wrong — you …"). Every nq has: good with the why; wrong map for every anticipated error value (each from a named error path — compute them!); signRetry where the key is signed; revealSteps in the instruction scaffold WHEN the item substitutes a formula (otherwise omit — prose reveal uses good).
Worked examples only where a formula is substituted (values → equation → [make X the subject] → substitute + calculate). Qualitative atoms use example sequences instead — vary one feature at a time; boundary non-examples bracket the boundary; rule stated after the contrast. Multivariable equations (PV = nRT, KE = ½mv², c = λν, E = hν, A = εbc) are synthesis atoms: their per-variable qualitative atoms come earlier in the register — respect that order and never front-load the equation into the per-variable lessons.
Wording: cause before effect; one name per quantity per lesson; explain-then-label; active voice; one idea (one sentence, provisional) per reveal line; no filler; no coined terms (master-log battery — the validator sweeps); Kelvin conversions consume PSM-067 as a labeled scaffold stage; mass unit is always amu; no time phrases in a unit slot; unicode sub/superscripts everywhere (H₂O, 10²³); no case-transform styling assumptions.
Figures: every figure carries instructional load and appears before the prose referencing it; a recap of a representation SHOWS the representation; answer-bearing values live in the figure, never the stem; one point per figure (no calculation boxes, no legend boxes, no title banners, ≤~6 text labels); ALL figures deterministic (generative imagery is banned). Flaw-variant figures used inside items carry NEUTRAL alt text — describe only what is objectively drawn; the flaw description lives in the post-answer feedback (2026-08-06 ruling).
Verdict+reason MCQ options ("X, because Y") are used sparingly — James (2026-08-06) considers them poor question design, permitted only as deliberate practice for the AP-exam style. Default: pure-verdict options with reasoning tested by separate why-items. If you use one: the wrong reason must be cleanly wrong, its feedback names the reasoning error, and you MUST flag the item in your report.
Chemistry: verify every number (real values; exact arithmetic in checks; R = 0.08206 L·atm·mol⁻¹·K⁻¹ — the AP equation sheet's notation, always this form in student-visible text — supplied in stems that need it; K = °C + 273 per PSM-067). State models with honest scope ("generally"); supplied data for irregular patterns; respect every register exclusion. Maxwell-Boltzmann work is qualitative/comparative only — no speed formulas. The chromatogram atom ranks polarity from spot positions given the phase polarities — no Rf.
Distractors: each from a named error path; cleanly wrong (not defensible); not absurd; mutually exclusive; no length/grammar/position cues; don't hinge on always/only/never.
Titles: short, content-bearing, student-facing (no atom IDs, no behaviour-verb authoring phrasing, no metadata).

FRQ practice items, end-of-unit tests, practice pages (added 2026-09-07)

frq flow type (pen-and-paper written response; reveal-gated model response + rubric self-scoring — the drawing-assessment pattern extended with real point values): {"t":"frq","q":{"source":"2023 FRQ Q4(a–c)"|"authored to archetype <name>", "stem":"shared context …","parts":[{"label":"(a)","prompt":"…","points":2},…], "fig":{…}|omitted,"model":[["(a)",["model line","model line"]],["(b)",[…]]], "rubric":[{"part":"(a)","desc":"One point is earned for …","pts":1},…]}}. Rubric lines are the scoring guideline's actual point conditions, reworded to second person where needed; rubric total MUST equal the stated part points (validator errors). Real questions keep their numbers and scoring conditions verbatim-faithful; adapted/authored items say so in source. FRQs are allowed in lessons, practice pages, and tests — NEVER in gates.
specs/tests.json (end-of-unit test): {"tests":[{"id":"U3-T1","title":"Unit 3 test", "label":"Unit test","afterSequence":"U3-S19","items":[{"atom":"PSM-0xx","t":"mcq"|"frq", "q":{…}}]}]} — blueprint: 18 MCQs (4-option, AP-style, fresh species, whole-unit sampling, full feedback contracts) + 2 FRQs (one 4-pt short, one 10-pt long). Draw items banned.
specs/practice.json (FRQ-practice pages): {"pages":[{"id":"U3-P1","title":"…", "label":"FRQ practice","afterSequence":"U3-S06","outcome":"…","flow":[…part/idea/note/frq/mcq steps…]}]} — a practice page teaches ONE playbook skill in a few idea lines, then runs a real FRQ part under the rubric. Forward-term rules apply at the page's afterSequence position.

Deliverable and report

Write the JSON file, then run python3 validate_course_specs.py yourself and fix every error your file introduced. Reply with: lesson count, check count by type, figures used by kind (+ any TODO figs), any verdict+reason items (rule 12 flag), the 3 hardest authoring decisions you made and why, and anything you believe needs James's judgment. Do not modify any other file.