Teaching → assessment → year-end promotion

A worked example on live data: one student, one subject, one school year, all the way to the next year. Every screen below was used on 16 November 2026 and every number was read back from the database.

Student: Sabiyyah (STU1789624283366) 2025-2026 · ALIMGY1C1 · Arabic → 2026-2027 · ALIMGY2C (Year 2) Result: 77.5 · Meets · promoted

1. At a glance

Sabiyyah is a Year 1 student (grade 239 ALIMGY1) at HidayatUnNisa (institution 12). The example teaches one subject — Arabic (subject 102) — through 2025-2026, evaluates it, releases a report card, validates the year and promotes her to Year 2 (grade 240 ALIMGY2) in 2026-2027.

Chapters / objectives
4 / 12
Lessons really available
71
Chapter progress at year end
38.3%
Subject final
77.5
Decision
Meets
WhatValue in this run
School year42 · 2025-2026 · 2025-01-06 → 2025-12-19 · two semesters
Class34 · ALIMGY1C1 (2025-2026) · grade 239 · homeroom Amina Yusuf
Subject offered46 · ARABICY1-2025 · 3 lessons a week, 71 in the year
Programme4 chapters weighted 15 / 25 / 30 / 30 = 100, 12 objectives, 4 reserved chapter tests
Tests72 Unit Test 1 (80/100) · 73 Vocabulary Quiz (absent) · 74 Reading Test (75/100) · 75 Listening Quiz (draft)
Report cardtemplate RC-2025-G1, term “Semester 1 - 2025”, average 77.5, “Competent”, approved then released
Promotionrule mode evaluations, pass 50 → Meets → class 10 ALIMGY2C, grade 240

2. How the model fits together

There are five words to hold on to, and they map one-to-one onto screens:

WordWhat it isWhere it is edited
ProgrammeOne subject of one grade in one school yearCurriculum → Programmes (Chapters)
ChapterAn ordered part of the year with a weight; may reserve lessons for its testsame screen
ObjectiveWhat the class must be able to do; each counts equally inside its chaptersame screen
Week planWhich objectives the class works on in which weekTeaching → Week plan
Lesson logWhat was actually taught in one lesson, objective by objectiveTeaching → Lesson log
The one rule that ties them together: objective progress = the furthest any lesson log took it · chapter progress = the average of its objectives · programme progress = chapters weighted by their weight. Every screen that shows a percentage uses that same calculation (App\Support\ProgrammeProgress), so the teacher’s screen, the administrator’s screen and the family’s screen can never disagree.

3. Administrator: set the year up

Admin  Do these in order. Each one is what the next needs.

There is no “outcome template” step any more. A programme creates its own catalogue row the first time you save it — this run's 2025-2026 programme produced PRG-ALIMGY1-42 “ALIMGY1 programmes 2025-2026” without anyone touching a template. The national catalogue (one document per grade and school year, shared by every university) lives at Settings → Curriculum catalogue (national) and is super-admin only. Step 1 of Curriculum Onboarding now shows your programmes instead.

1 Create the school year and its semesters

Path: Settings → Academic periods · /settings

Do: add 2025-2026 (start 2025-01-06, end 2025-12-19, not current — 2026-2027 stays current), then two terms on the school: “Semester 1 - 2025” and “Semester 2 - 2025”.

Why: the week plan takes its weeks from the terms; without them there are no weeks to place objectives in.

  • Period is visible in every “School year” picker.
  • Both terms appear under the school’s calendar.

2 Offer the grade and create the class

Path: Multi-university → Grades, then Students → Classes · /classes

Do: make sure grade 239 (ALIMGY1) is offered for 2025-2026, then create the class ALIMGY1C1 (2025-2026) in that year with grade 239 and a homeroom teacher.

  • The class shows the right school year and grade.
  • The homeroom teacher can open the class (this is what lets a teacher plan and mark for it).

3 Add the subject to the class, with lessons per week

Path: Curriculum setup → Institution subjects, then Class subjects

Do: offer Arabic for grade 239 in 2025-2026, then link it to the class with 3 lessons per week.

Why: the programme’s capacity check is “lessons per week × teaching weeks”, and the week plan can only count lessons for a subject the class actually has.

  • The class-subject row shows 3 periods a week.
  • The timetable builder lists the class and the subject in its drawer.

4 Build the timetable (real lesson slots)

Path: Timetable builder

Do: put Arabic in the same three weekly slots the subject has in the live year, publish the timetable.

Why: the year’s 71 lessons are counted from the published timetable, minus term gaps and holidays. Without slots the programme editor warns that lessons cannot be counted.

  • The guided trace at the bottom of the builder turns green for Timetable.
  • Coverage shows subjects timetabled, not a 0% figure.

5 Build the programme: chapters, weights, objectives

Path: Curriculum setup → Programmes (Chapters) → Open the programme editor · /curriculum/programmes

Do: open the programme for Arabic · grade 239 · 2025-2026 and add four chapters. Give each a weight and list its objectives with an estimated number of lessons. Reserve one test lesson at the end of each chapter.

Ch.TitleWeightObjectivesEst. lessons
1Greetings and introductions15Holds a short conversation · greets and introduces themselves · asks and answers simple questions7
2The Arabic alphabet and sounds25Names all the letters · writes joined forms · reads vowelled words10
3Everyday vocabulary30Family and classroom objects · numbers 1–20 · daily routine10
4Reading short texts30Reads aloud · answers questions · summarises11
Weights do not have to total 100. This programme totals exactly 100 (15+25+30+30), but a 90/10 split or a 0-weight optional chapter is allowed: the percentage is scaled by the total. The editor shows the running total and offers Split evenly. The one thing it refuses is a programme whose chapters all weigh zero, because progress could then never move above 0%.
  • The programme list shows 4 chapters · 12 objectives · 100 / 100.
  • The budget card reads “71 lessons, planned 38” — the plan fits the year.
  • Deleting an objective that is already planned or taught is refused (OBJECTIVE_IN_USE).

6 Tell the promotion rules how the year is decided

Path: Promotion rules

Do: choose Arabic · 2025-2026 · grade 239, set the mode to All published marks (evaluations & graded homework), pass mark 50, no failed subjects allowed, and leave “every term must have a mark” off.

Why this mode exists. Each class test is its own assessment with its own period, so the older “term weights” mode cannot describe them. This mode reads every published mark of the subject in the year, weighted by the weight you gave each test — exactly what the report card shows. Subjects with no marks are skipped instead of counting as failures.

7 Create the report card template for the year

Path: Report cards

Do: add a template for grade 239 in 2025-2026 (here RC-2025-G1, copied from the 2026 card so the layout matches).

4. Teacher: plan, teach, test

Teacher  Amina Yusuf teaches Arabic to this class.

1 Plan the weeks

Path: Teaching → Week plan

Do: pick the class + subject, then drag objectives into weeks (or select a week and press +). Each objective carries a number of lessons; the four chapter tests already appear as reserved rows, so they only need placing.

  • Weeks show the lessons that week really has (3 a week here) — an overloaded week is a warning, never a block.
  • Placing an objective twice, or after its chapter’s test week, is refused.

2 Log each lesson

Path: Teaching → Lesson log

Do: open today’s lesson. For each objective the lesson touched, choose Done (100%) or Partly and type a percentage; the box starts at “where the class is + 25”, so a class already at 80% is offered 99%, not 50%. If nothing was taught, press Nothing taught and write why — the note is required.

Lesson dateObjectiveAfter the log
2025-01-061.1 Holds a short conversation100%
2025-01-131.2 Greets and introduces themselves100%
2025-01-201.3 Asks and answers simple questions100%
2025-02-032.2 Writes the letters in their joined forms100%
2025-02-102.3 Reads short vowelled words60%
2025-02-173.1 Names family and classroom objects100%
Result: chapter 1 completed (100%), chapter 2 53.3%, chapter 3 33.3%, chapter 4 not started → programme 38.3%. Correcting a log is done by re-saving that same lesson: its rows are replaced, so progress is recomputed.

3 Schedule a test on a real lesson

Path: Assessments (Tests) → Schedule a test

Do: pick a lesson slot, a type and what the test covers. Only chapters the class has started can be ticked — a test cannot examine what was never taught.

The test replaces its lesson. The timetable shows the test on that slot, the lesson log marks it “Test” instead of “missing”, and the coverage board does not ask for a log for it.

4 Enter the scores (draft → published)

Path: Assessments → Scores · /assessment/72/scores

Do: set Out of (here 20), Weight in the result (40), and the chapters it covers; type the marks and publish. Students the class register marked absent are pre-ticked Absent.

TestDateOut ofWeightCoversSabiyyahState
Arabic Unit Test 12025-02-242040Ch. 1–216 → 80/100Published
Arabic Vocabulary Quiz2025-03-061020Ch. 3AbsentPublished
Arabic Reading Test2025-03-132040Ch. 2–315 → 75/100Published
Arabic Listening Quiz2025-03-201020Ch. 3—Draft (not visible to her)
  • Publishing needs a score or Absent for every student (SCORES_MISSING names the ones left blank).
  • Marks are stored as typed (/20) and copied to the report book as 0–100, which is what report cards, GPA and the student’s results read.
  • Once published, changing a mark asks for a reason (≥ 5 characters) and writes an audit line plus a notification to the class and guardians.

5 Homework and assignments use the same gradebook

Path: Homework · Assignment hub

Graded homework writes into the same mark table with its own weight, so it reaches the report card and (if you switch it on in the promotion rule) the year-end decision. Ungraded homework never counts.

5. Student & guardian: what they see

1 Chapter progress

Student /my-progress  ·  Guardian /parent/programs

They see: the class and school year, then each subject with its percentage, how many chapters are completed, the current chapter, and — on demand — the chapter list with a status each. No objective-level teacher notes, and no other class: the API refuses anything outside their own record.

After promotion this page follows the current year. Sabiyyah opened it the day after promotion and it showed ALIMGY2C · 2026-2027 with four subjects at 0% — the new year has not started. The previous year stays in the record but is not shown as “current”.

2 Results, including “Absent”

Student /my-results · Guardian /parent/results

They see: every published test with its mark out of 100 and the average. The vocabulary quiz shows an Absent badge — not “not graded yet” — and the hint says it does not count towards the average. A test still in draft simply does not appear.

3 Report card

/my-report-cards · /parent/bulletins

Only a released card is visible, and once released its marks are frozen for teachers (see below).

6. Year-end validation & promotion

1 Generate, approve and release the report card

Path: Report cards → generate for the class → approve → release

Do: generate for class 34, term “Semester 1 - 2025”, template RC-2025-G1; then move it draft → approved → released.

StudentAverageGradeResultFailed subjects
Sabiyyah77.5Competentpass0

77.5 = (80 × 40 + 75 × 40) ÷ (40 + 40). The absent quiz contributes nothing — it is neither a zero nor a missing mark.

Release locks the marks. With the card released, the teacher who owns the class is refused: REPORT_CARD_RELEASED — the report card of this term has been released, so its scores are locked. An administrator or principal can still correct a mark (with a reason, an audit line and a notification), which is the deliberate escape hatch before the card is regenerated.

2 Validate the year

Path: Students → Year-end promotion

Do: pick the school, the year (2025-2026), the source class and the target class; the page lists the students with their combined result and a decision.

StudentOverallFailedDecisionSubject results
Sabiyyah77.50MeetsARABICY1 77.5 (pass)
  • Incomplete means a mark is missing (when “every term must have a mark” is on) or there are no marks at all.
  • Shortfall means the overall is below the pass mark, or too many subjects failed — the reason is spelled out (“Overall 46 < 50”, “Failed 2 subject(s) (max 0)”).
  • The decision is advisory: the administrator still chooses whom to promote.

3 Promote

Same page → select the students → Promote

Do: choose the target class of the next year — ALIMGY2C (grade 240, 2026-2027) — and promote.

What the system does: it creates the new enrolment for the new year, keeps last year’s enrolment as history (with a pointer to the class she moved to), and refuses a student who is already enrolled in that year, a class that is full, or a grade that does not match the class.

YearClassGradeStatusPoints to
2025-2026ALIMGY1C1 (2025-2026)239EnrolledALIMGY2C
2026-2027ALIMGY2C240Enrolled (new)—
Verified as the student: after promotion, /my-progress returned ALIMGY2C · 2026-2027 and her results still listed the three published tests (80, Absent, 75). The draft test stayed invisible.

7. What the model decides

QuestionDecision
Must chapter weights total 100?No. The editor warns and offers “split evenly”; progress is scaled by the total. A total of zero is refused, because progress would be stuck at 0%.
Do objectives have weights?No. Each counts equally inside its chapter; emphasis is expressed by the chapter weight.
Free percentage or one step per objective?Both. “Done” = 100; “Partly” takes any 1–99, pre-filled from where the class is. Progress is the furthest any log reached, so it never slides back.
Plan chapters or objectives?Chapters structure, objectives plan. The week plan holds objectives; the chapter carries the weight and the reserved test.
“Per hour / per day”?A lesson estimate, not a slot binding. Objectives are planned per week against the lessons that week really has. Only tests are bound to a real slot.
Same programme, two classes?Separate. One programme per grade, one plan and one progress figure per class.
Score formatThe teacher’s own “out of” (default 20), stored as typed, copied to 0–100 on publish; each test has a weight in the subject’s final mark.
Absent studentsExplicit Absent. No mark row, excluded from averages, must be set before publishing; shown as “Absent” to the family.
Editing after publishingYes, with a reason, an audit line and a notification — until the report card is released, when teachers are locked out and an administrator must step in.
Who sees progressStudent and guardian, chapter level only. Objectives stay with the teacher; marks live on Results.

8. Evidence: the exact records

Everything below was read back from the database after the run, not copied from a screen.

RecordWhereValue
School yearacademic_periods42 · 2025-2026
Termsinstitution_schedule_termsSemester 1 - 2025, Semester 2 - 2025
Classinstitution_classes34 · ALIMGY1C1 (2025-2026)
Offering / class subjectinstitution_subjects, institution_class_subjects46 · Arabic · 3 lessons/week
Timetableinstitution_schedule_timetables28 · 8 slots · 3 Arabic lessons a week
Chapterscurriculum_chapters37, 38, 39, 40 · weights 15 / 25 / 30 / 30
Objectivesoutcome_criterias1129–1140 · 12 rows, each inside a chapter
Week planclass_week_plans12 objectives over 12 weeks (2025-01-06 → 2025-03-24)
Lesson logsinstitution_lesson_coverage6 lessons, each a row per objective with a percentage
Testsassessments, assessment_chapters72–75 · chapter coverage recorded
Marksassessment_scores → assessment_item_results16/20 → 80 · absent · 15/20 → 75
Report cardinstitution_students_report_cardsaverage 77.5 · approved · released
Promotion ruleinstitution_promotion_rulesmode evaluations · pass 50 · 0 failed subjects
Promotioninstitution_class_studentsnew row for class 10 / grade 240; last year’s row points to it

9. Known limits & next steps

Reproducing this run: the seed and the API calls live in .e2e/ (seed-prev-year.sql, seed-prereq.sql, cleanup-old-curriculum.sql, api.ps1) and every request/response is in .e2e/log.jsonl.